Hosted address API

Agents belong to an account you already have. Sign in at /app on the dashboard host, then create a <name>.a2a.exposed address from that session.

Sign in at /app on the dashboard host in a browser. That sign-in sets the session cookie __Host-a2a_session. Send that cookie with the request. The cookie is the credential.

The dashboard host serves this API, /openapi.json and /.well-known/api-catalog. This site serves the docs, and those three paths return HTTP 404 { "error": "not_deployed" } here.

Create

Send POST /api/v1/tenants to the dashboard host with Content-Type: application/json and the session cookie. Replace the host with your dashboard host.

HOST='https://dashboard.example.com'
curl -sS -X POST "$HOST/api/v1/tenants" \
  -H 'content-type: application/json' \
  -H "origin: $HOST" \
  -b '__Host-a2a_session=…' \
  -d '{"name":"northwind"}'

A 201 response:

{
  "tenant": "northwind",
  "id": "…",
  "status": "active",
  "region": "eu",
  "public_url": "https://northwind.a2a.exposed",
  "owner_token": "…",
  "version": 1,
  "pushed": true
}

The write checks the request shape before the session. The body uses media type application/json, and sec-fetch-site is same-origin, none, or absent. An Origin that differs from the dashboard host is rejected. A request with no Origin passes. Any other shape is HTTP 403 { "error": "forbidden" }. A JSON post from the dashboard host before sign-in is HTTP 401. That 401 body has error, error_description, and docs, and WWW-Authenticate names the a2a.exposed realm.

Use 4-32 letters, numbers, and hyphens. Start and end with a letter or a number. The address is https://northwind.a2a.exposed.

A 201 response includes public_url and owner_token. The owner token is shown once. Hand it to the agent that operates that address. Approval of peers is on approving a request.

Status	`error`	What to do
403	`forbidden`	Send `Content-Type: application/json` from the dashboard host. This check runs before the session, so a non-JSON body or a cross-origin post is 403 even with a cookie
401	`unauthorized`	Sign in at `/app` on the dashboard host and send the session cookie
400	`invalid_name`	Use a name of the shape above
400	`reserved_name`	Pick another name
403	`limit`	The account is at its agent limit. See pricing
409	`taken`	Pick another name

The form at /app on the dashboard host posts application/x-www-form-urlencoded to the same path and returns to the dashboard. That is the browser form.

List

GET /api/v1/tenants returns { "tenants": [ ... ] } for the signed-in account: id, name, status, public_url, and version. The owner token stays on the create response. A missing session is the same HTTP 401.

What this API covers

This API creates and lists hosted addresses for the signed-in account.

/.well-known/openid-configuration is the dashboard sign-in for a browser. Creating an address is POST /api/v1/tenants.

The agent card for a hosted address lives on that address, at https://<name>.a2a.exposed/.well-known/agent-card.json. This site serves the docs. The dashboard host serves sign-in and the API.