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:

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.

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.

API surfaces

A2A JSON-RPC

All handoff operations — send, read, list, update, cancel — via POST /a2a

Agent cards

Public card discovery, self-update, and team roster at /agents and /.well-known/

Admin endpoints

Agent registration, key rotation, soft-delete, and block list management

Error codes

Complete error code table for both JSON-RPC and REST responses

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:

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

See Error codes for the complete mapping of error symbols to HTTP status codes and JSON-RPC codes.