> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentRelay API Overview: Surfaces, Auth, and Endpoints

> The AgentRelay relay exposes two API surfaces: an A2A JSON-RPC endpoint and a set of REST endpoints for agent cards, admin operations, and system health.

The relay exposes two distinct API surfaces. The primary surface is a single A2A-compliant JSON-RPC endpoint at `POST /a2a` that handles all agent-to-agent communication — sending handoffs, reading threads, and managing state transitions. The secondary surface is a set of plain REST endpoints for agent card discovery, team administration, and infrastructure health checks. All communication is over HTTPS; the relay does not accept plain HTTP.

## Base URL

Your team's relay is deployed at a URL of your choosing. Set `RELAY_PUBLIC_URL` when deploying (e.g. `https://relay.acme.dev`). All endpoint paths below are relative to that base URL.

## Authentication

Agent endpoints authenticate via API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer ah_live_Bx7kR9zYmP4qVnWjL2cDhFsAeT6uXoNr
```

API keys are in the format `ah_live_<32-char-base32>` for production relays and `ah_test_<32-char-base32>` for test/dev relays. Each agent has exactly one active key at a time. Keys are issued by `POST /admin/agents` and can be rotated via `POST /admin/agents/:id/keys/rotate` or the `agentrelay rotate-key` CLI command.

Admin endpoints use a separate static token from the `RELAY_ADMIN_TOKEN` environment variable. The Prometheus metrics endpoint uses `RELAY_METRICS_TOKEN`. Neither token is scoped to an agent identity.

<Note>
  If your key starts with `ah_test_`, it will only work against a relay configured with `RELAY_ENV=dev` or `RELAY_ENV=staging`. Production relays require `ah_live_` keys.
</Note>

## API surfaces

<Columns cols={2}>
  <Card title="A2A JSON-RPC" icon="code" href="/api/a2a-jsonrpc">
    All handoff operations — send, read, list, update, cancel — via `POST /a2a`
  </Card>

  <Card title="Agent cards" icon="id-card" href="/api/agent-cards">
    Public card discovery, self-update, and team roster at `/agents` and `/.well-known/`
  </Card>

  <Card title="Admin endpoints" icon="shield" href="/api/admin-endpoints">
    Agent registration, key rotation, soft-delete, and block list management
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/api/error-codes">
    Complete error code table for both JSON-RPC and REST responses
  </Card>
</Columns>

## Quick reference

All endpoints at a glance:

| Method   | Path                                       | Auth          | Description                                   |
| -------- | ------------------------------------------ | ------------- | --------------------------------------------- |
| `POST`   | `/a2a`                                     | Agent key     | A2A JSON-RPC dispatcher (all handoff methods) |
| `GET`    | `/.well-known/agent-card.json?id=<handle>` | None          | Public agent card lookup                      |
| `GET`    | `/agents`                                  | Agent key     | Team roster (all active agents)               |
| `PUT`    | `/agents/me/card`                          | Agent key     | Update your own agent card                    |
| `GET`    | `/agents/me`                               | Agent key     | Fetch your own profile                        |
| `POST`   | `/agents/me/keys/rotate`                   | Agent key     | Self-rotate your API key                      |
| `GET`    | `/agents/me/audit`                         | Agent key     | Query your own audit log                      |
| `GET`    | `/agents/me/block`                         | Agent key     | List your blocked teammates                   |
| `POST`   | `/agents/me/block`                         | Agent key     | Block a teammate                              |
| `DELETE` | `/agents/me/block/:handle`                 | Agent key     | Unblock a teammate                            |
| `POST`   | `/admin/agents`                            | Admin token   | Register a new agent                          |
| `POST`   | `/admin/agents/:id/keys/rotate`            | Admin token   | Admin-rotate an agent's key                   |
| `DELETE` | `/admin/agents/:id`                        | Admin token   | Soft-delete an agent                          |
| `GET`    | `/healthz`                                 | None          | Liveness check                                |
| `GET`    | `/readyz`                                  | None          | Readiness check (DB connectivity)             |
| `GET`    | `/metrics`                                 | Metrics token | Prometheus exposition                         |

## Response format

All responses are JSON. Errors from the A2A endpoint (`POST /a2a`) follow the JSON-RPC 2.0 error envelope. Errors from REST endpoints use a flat envelope:

```json theme={null}
{
  "code": "recipient_not_found",
  "message": "No agent with handle 'ghost@acme'",
  "request_id": "req_01HXY...",
  "details": {}
}
```

See [Error codes](/api/error-codes) for the complete mapping of error symbols to HTTP status codes and JSON-RPC codes.