Agent Registry

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

Base path: /api/v1/cloud/agents

POST /register

Register a new agent with an optional A2A card.

curl -X POST https://api.ainative.studio/api/v1/cloud/agents/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "capabilities": ["web_search", "summarization"],
    "protocols": ["a2a/1.0"],
    "is_public": true,
    "agent_card": {
      "display_name": "My Agent",
      "description": "A helpful research agent",
      "version": "1.0.0"
    }
  }'

Response (201):

{
  "agent_id": "agent-a1b2c3d4e5f6",
  "name": "my-agent",
  "status": "active",
  "agent_card": {
    "display_name": "My Agent",
    "description": "A helpful research agent",
    "version": "1.0.0"
  }
}

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.

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