Agent Registry

Register agents in the cloud, manage their A2A identity cards, and discover agents by capability.

Base path: /api/v1/cloud/agents

Local Agent Auto-Registration

Local OpenClaw agents use the ensure_registered() function in agent_report.py to auto-register on first run. The registration (agent_id and API key) is cached locally in ~/.ainative/agent_registration.json, so subsequent runs skip the registration call. If you need to re-register, delete the cached file.

POST /register

Register a new agent with an optional A2A card. Requires user authentication.

The two required fields are agent_type and capabilities — there is no name, agent_name, or callback_url field on this endpoint. Sending those returns 422 Unprocessable Entity.

curl -X POST https://api.ainative.studio/api/v1/cloud/agents/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "code-reviewer",
    "capabilities": ["code-review", "testing"],
    "protocols": ["mcp", "a2a"],
    "is_public": true,
    "endpoint_url": "https://my-agent.example.com",
    "description": "A helpful research agent",
    "agent_card": {
      "name": "My Agent",
      "description": "A helpful research agent",
      "version": "1.0.0",
      "skills": [
        { "name": "code-review", "description": "Reviews pull requests" }
      ],
      "input_modes": ["text"],
      "output_modes": ["text"]
    }
  }'

Request fields:

Field	Type	Required	Description
agent_type	string	yes	Type of agent, e.g. code-reviewer, translator (1–100 chars)
capabilities	string[]	yes	At least one capability slug, e.g. ["code-review", "testing"]. Lower-cased and trimmed server-side.
protocols	string[]	no	Supported protocols. Defaults to ["mcp"]. Valid values: mcp, a2a, rest, grpc, websocket.
agent_card	object	no	A2A-spec card. Uses name, description, version, skills[], input_modes[], output_modes[], meta.
endpoint_url	string	no	Agent's callable endpoint. Must be HTTPS.
is_public	bool	no	Whether the agent is discoverable by others. Default false.
description	string	no	Free-text description (≤ 1000 chars).
model	string	no	Model backing the agent.
operator	string	no	Operator/owner label.
tools	string[]	no	Tools to bundle. Defaults to the standard tool set if omitted.
mcp_servers	object[]	no	MCP server configs to attach at registration. See MCP Configuration.

Response (201):

{
  "agent_id": "agent-a1b2c3d4e5f6",
  "agent_type": "code-reviewer",
  "capabilities": ["code-review", "testing"],
  "tools": ["bash", "read", "write", "edit", "glob", "grep", "web_fetch", "web_search"],
  "agent_card": {
    "name": "My Agent",
    "description": "A helpful research agent",
    "version": "1.0.0"
  },
  "protocols": ["mcp", "a2a"],
  "endpoint_url": "https://my-agent.example.com",
  "is_public": true,
  "status": "ACTIVE",
  "created_at": "2026-08-20T12:00:00Z"
}

GET /discover

Find agents by capability. Returns agents ranked by relevance.

curl "https://api.ainative.studio/api/v1/cloud/agents/discover?capability=summarization&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

Parameter	Type	Default	Description
capability	string	required	Capability to search for
limit	int	10	Max results
protocol	string	—	Filter by protocol

GET /{agent_id}/card

Retrieve an agent's A2A identity card.

curl https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/card \
  -H "Authorization: Bearer $TOKEN"

PUT /{agent_id}/card

Update your agent's card. You must be the agent's owner.

curl -X PUT https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/card \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Research Agent v2",
    "description": "Updated description",
    "version": "2.0.0"
  }'

GET /catalog

Browse the public agent catalog. No authentication required for public agents.

curl "https://api.ainative.studio/api/v1/cloud/agents/catalog?page=1&page_size=20"

Query Parameters:

Parameter	Type	Default	Description
page	int	1	Page number
page_size	int	20	Results per page
capability	string	—	Filter by capability

POST /{agent_id}/health

Report health status for a running agent. Called periodically by deployed agents.

The field is health_status and must be one of healthy, unhealthy, or degraded. Optional metadata carries free-form telemetry (e.g. latency, load).

curl -X POST https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/health \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "health_status": "healthy",
    "metadata": {"latency_ms": 42, "requests_served": 142}
  }'

Response (200):

{
  "agent_id": "agent-a1b2c3d4e5f6",
  "health_status": "healthy",
  "last_health_check": "2026-08-20T12:00:00Z",
  "metadata": {"latency_ms": 42, "requests_served": 142}
}

DELETE /{agent_id}

Deregister an agent and cascade-clean its dependent resources (deployments, OAuth clients, schedules). See the Agent Lifecycle page for the full teardown behavior and the soft- vs hard-delete options.