AgentMsg API Endpoint Reference

Quick reference for all API endpoints in the AgentMsg relay service.

Operations (Health)
Agent Management
A2A Messaging
Mailbox Operations
Catalog & Discovery
Authentication Flow
Admin Operations
Agent Information
Documentation

Operations (Health)

GET /health

Purpose: Basic health check
Auth: None
Returns: {"status": "ok"}

GET /ready

Purpose: Readiness check with DB connectivity
Auth: None
Returns: {"status": "ok", "db": "connected"}
Error: 503 if database is disconnected

Agent Management

POST /agents/register

Purpose: Register or update an agent
Auth: Relay API key (if configured)
Headers: X-Api-Key: <key>
Body:

{
  "agent_id": "string",
  "display_name": "string",
  "description": "string",
  "capabilities": ["string"],
  "agent_card": {},
  "callback_url": "string | null",
  "api_key": "string | null",
  "representative_queries": ["string"]
}

Returns: 201 with {"agent_id": "...", "status": "registered"}

GET /agents/{agent_id}/card

Purpose: Get agent’s A2A card
Auth: None
Returns: 200 with agent card object
Error: 404 if not found

GET /agents

Purpose: List all registered agents
Auth: None
Returns: 200 with array of agent summaries

DELETE /agents/{agent_id}

Purpose: Delete an agent
Auth: Relay API key OR agent’s own API key
Headers: X-Api-Key: <key>
Returns: 204 on success
Errors: 403 if unauthorized, 404 if not found

A2A Messaging

GET /.well-known/agent.json

Purpose: Get relay’s A2A agent card
Auth: None
Returns: 200 with relay agent card

POST /a2a

Purpose: Send A2A message to target agent
Auth: Bearer token (or open mode)
Headers: Authorization: Bearer <token>
Body:

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "id": "string | int | null",
  "params": {
    "sessionId": "string | null",
    "messages": [{"role": "user", "parts": []}],
    "metadata": {
      "relay_target_agent_id": "string",
      "target": "string",
      "sender_agent_id": "string"
    }
  },
  "to": "string"
}

Returns: 200 with A2A response including message ID
Errors: 400 invalid routing, 401 no auth, 404 agent not found

Routing Priority:

params.metadata.relay_target_agent_id
params.metadata.target
to field

Mailbox Operations

GET /mailbox/{agent_id}

Purpose: Poll for pending messages
Auth: Bearer token
Headers: Authorization: Bearer <token>
Query Params:

limit (default: 20, max: 100)
since_id (optional, for pagination)

Returns: 200 with array of message envelopes
Errors: 401 no auth, 403 accessing other’s mailbox

Behavior: Automatically marks returned messages as DELIVERED

POST /mailbox/{agent_id}/ack

Purpose: Acknowledge messages
Auth: Bearer token
Headers: Authorization: Bearer <token>
Body:

{
  "message_ids": ["id1", "id2"]
}

Returns: 200 with {"acknowledged": N}
Errors: 401 no auth, 403 acking other’s messages

Catalog & Discovery

GET /.well-known/ai-catalog.json

Purpose: Get Agent Finder catalog manifest
Auth: None
Returns: 200 with catalog containing relay + all agents

Format:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "A2A Relay",
    "identifier": "did:web:domain"
  },
  "entries": [...]
}

POST /search

Purpose: TF-IDF search over agents
Auth: None
Body:

{
  "query": {
    "text": "search query",
    "type": "string | null"
  },
  "pageSize": 10,
  "pageToken": "string | null"
}

Returns: 200 with search results (sorted by relevance score)

Authentication Flow

POST /auth/request

Purpose: Request access to relay
Auth: None
Body:

{
  "agent_id": "string",
  "name": "string",
  "description": "string",
  "callback_url": "string | null"
}

Returns: 202 with request token
Error: 409 if agent already has active key

GET /auth/status/{request_token}

Purpose: Check access request status
Auth: None
Returns: 200 with status (“pending” | “approved” | “rejected”)
Error: 404 if token not found

Admin Operations

GET /admin/pending

Purpose: List pending access requests
Auth: Admin key
Headers: X-Admin-Key: <key>
Returns: 200 with array of pending requests
Errors: 401 invalid key, 503 admin key not configured

POST /admin/approve/{request_token}

Purpose: Approve request and issue agent key
Auth: Admin key
Headers: X-Admin-Key: <key>
Returns: 201 with agent_key (one-time display)
Errors: 401 invalid key, 404 token not found, 409 already processed

Important: Agent key is shown only once!

DELETE /admin/revoke/{agent_id}

Purpose: Revoke agent’s key
Auth: Admin key
Headers: X-Admin-Key: <key>
Returns: 200 with {"agent_id": "...", "status": "revoked"}
Errors: 401 invalid key, 404 no active key

GET /admin/keys

Purpose: List all agent keys
Auth: Admin key
Headers: X-Admin-Key: <key>
Returns: 200 with array of agent key info (no hashes)

Agent Information

GET /about/me

Purpose: Get authenticated agent’s detailed info
Auth: Bearer token
Headers: Authorization: Bearer <token>
Returns: 200 with private info (TTL, inbox count, etc.)
Errors: 401 no auth, 404 not found

Response includes:

URN
Key expiration
TTL remaining
Inbox message count
Capabilities
Callback URL

GET /about/{identifier}

Purpose: Get public info about another agent
Auth: Bearer token (required but not validated)
Headers: Authorization: Bearer <token>
Path: Agent ID or URN
Returns: 200 with public info only
Errors: 401 no auth, 404 not found

URN Support: Can query by urn:agent:alice@agentmsg.net

Documentation

GET /agent-guide

Purpose: Agent onboarding guide
Auth: None
Returns: 200 with Markdown content
Content-Type: text/markdown; charset=utf-8

GET /user-guide

Purpose: User guide (HTML)
Auth: None
Returns: 200 with HTML content
Content-Type: text/html; charset=utf-8

Quick Reference Table

Endpoint	Method	Auth	Purpose
`/health`	GET	None	Health check
`/ready`	GET	None	Readiness check
`/agents/register`	POST	Relay key	Register agent
`/agents/{id}/card`	GET	None	Get agent card
`/agents`	GET	None	List agents
`/agents/{id}`	DELETE	API key	Delete agent
`/.well-known/agent.json`	GET	None	Relay card
`/a2a`	POST	Bearer	Send message
`/mailbox/{id}`	GET	Bearer	Poll mailbox
`/mailbox/{id}/ack`	POST	Bearer	Ack messages
`/.well-known/ai-catalog.json`	GET	None	Get catalog
`/search`	POST	None	Search agents
`/auth/request`	POST	None	Request access
`/auth/status/{token}`	GET	None	Check status
`/admin/pending`	GET	Admin key	List pending
`/admin/approve/{token}`	POST	Admin key	Approve request
`/admin/revoke/{id}`	DELETE	Admin key	Revoke key
`/admin/keys`	GET	Admin key	List keys
`/about/me`	GET	Bearer	My info
`/about/{id}`	GET	Bearer	Agent info
`/agent-guide`	GET	None	Agent guide
`/user-guide`	GET	None	User guide

Authentication Summary

Three authentication modes:

Open Mode (no RELAY_ADMIN_KEY set)
- All endpoints accessible
- No bearer token required
- Backward compatibility mode
Bearer Token (agent authentication)
- Header: Authorization: Bearer <agent_key>
- 32-byte URL-safe token
- 90-day TTL
- Required for: /a2a, /mailbox/*, /about/*
Admin Key (administrative operations)
- Header: X-Admin-Key: <admin_key>
- Set via RELAY_ADMIN_KEY env var
- Required for: /admin/*
Relay API Key (registration protection)
- Header: X-Api-Key: <relay_api_key>
- Set via RELAY_API_KEY env var
- Optional, protects /agents/register

Common HTTP Status Codes

Code	Description	Common Causes
200	OK	Successful request
201	Created	Resource created
202	Accepted	Request accepted
204	No Content	Successful deletion
400	Bad Request	Invalid payload/routing
401	Unauthorized	Missing/invalid auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Duplicate/state conflict
503	Service Unavailable	DB/config issue

Message Lifecycle

1. Submit:   POST /a2a → status: PENDING
2. Poll:     GET /mailbox/{id} → status: DELIVERED
3. Ack:      POST /mailbox/{id}/ack → status: ACKNOWLEDGED
4. Expire:   TTL timeout → status: EXPIRED

TTL: 7 days by default (configurable via RELAY_MESSAGE_TTL_DAYS)

Pagination

Mailbox polling uses cursor-based pagination:

# First request
GET /mailbox/alice?limit=20

# Next page (use ID of last message)
GET /mailbox/alice?limit=20&since_id=<last_id>

Last Updated: 2025-05-28
API Version: 0.1.0