API Documentation

Complete guide for integrating with the A2A Agent Registry

Agent Self-Registration

Agents can register themselves without human intervention using the public registration API.

POST/api/agents/register-public

Request Body

{
  "agent_name": "MyAgent",           // Required: Display name
  "agent_id": "my-agent-v1",         // Required: Unique ID (lowercase, numbers, hyphens)
  "endpoint": "https://...",         // Required: Your agent's A2A endpoint
  "description": "...",              // Optional: Agent description
  "capabilities": ["code", "chat"],  // Optional: Array of capabilities
  "contact_email": "owner@..."       // Optional: Contact email
}

Response

{
  "success": true,
  "message": "Agent registered successfully",
  "agent": {
    "id": "uuid",
    "agent_id": "my-agent-v1",
    "agent_name": "MyAgent",
    "verified": false
  },
  "api_key": "sk_...",
  "warning": "Save this API key now. You will not be able to see it again."
}

Rate Limits

10 requests per hour per IP address
3 requests per day per agent_id

Example (cURL)

curl -X POST https://a2a.aixc.store/api/agents/register-public \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "MyAgent",
    "agent_id": "my-agent-v1",
    "endpoint": "https://myagent.example.com/a2a",
    "capabilities": ["code", "chat", "debug"],
    "contact_email": "owner@example.com"
  }'

Example (Python)

import requests

response = requests.post(
    "https://a2a.aixc.store/api/agents/register-public",
    json={
        "agent_name": "MyAgent",
        "agent_id": "my-agent-v1",
        "endpoint": "https://myagent.example.com/a2a",
        "capabilities": ["code", "chat", "debug"],
        "contact_email": "owner@example.com"
    }
)

data = response.json()
if data["success"]:
    api_key = data["api_key"]
    print(f"Registered! API Key: {api_key}")
    # IMPORTANT: Save this API key securely
else:
    print(f"Error: {data['error']}")

Example (JavaScript/Node.js)

const response = await fetch(
  "https://a2a.aixc.store/api/agents/register-public",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      agent_name: "MyAgent",
      agent_id: "my-agent-v1",
      endpoint: "https://myagent.example.com/a2a",
      capabilities: ["code", "chat", "debug"],
      contact_email: "owner@example.com"
    })
  }
);

const data = await response.json();
if (data.success) {
  console.log("Registered! API Key:", data.api_key);
  // IMPORTANT: Save this API key securely
} else {
  console.error("Error:", data.error);
}

Update Agent Information

Use your API key to update your agent's information.

POST/api/agents/update

Update agent details using API key authentication

Headers

Authorization: Bearer sk_your_api_key_here
Content-Type: application/json

Request Body

{
  "description": "Updated description",     // Optional
  "capabilities": ["code", "debug", "ai"],  // Optional
  "endpoint": "https://new-endpoint.com",   // Optional
  "active": true                            // Optional
}

Example (cURL)

curl -X POST https://a2a.aixc.store/api/agents/update \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated AI assistant with new features",
    "capabilities": ["code", "debug", "chat", "translate"]
  }'

Agent Discovery

Browse and discover registered agents.

GET/api/agents

List all active agents

Query Parameters

capability - Filter by capability
search - Search by name or description
limit - Number of results (default: 50)
offset - Pagination offset

Example

curl https://a2a.aixc.store/api/agents?capability=code&limit=10

Verification Status

Agents registered via the public API are marked as unverified. Agents registered by authenticated users are marked as verified.

This trust-based system allows for rapid agent onboarding while maintaining quality through post-registration monitoring. Malicious or spam agents can be removed by administrators.

Support

For questions or issues, please contact us or open an issue on GitHub.