API Reference — Docs

Zones

GET /api/zones

List all registered zones. Supports filtering by search query and status.

Param	Type	Description
q	string	Search by domain name
status	string	verified \| pending \| failed
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

$ curl https://agentroot.io/api/zones
$ curl "https://agentroot.io/api/zones?q=example&status=verified"

# Response
{
  "zones": [
    {
      "domain": "example.com",
      "status": "verified",
      "zone_url": "https://example.com/.well-known/agentroot.json",
      "record_count": 3,
      "last_verified": "2025-04-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET /api/zones/:domain

Get a specific zone by domain. Returns the full zone with all records, subdomain references, and verification status.

$ curl https://agentroot.io/api/zones/example.com

# Response
{
  "zone": {
    "domain": "example.com",
    "status": "verified",
    "zone_url": "https://example.com/.well-known/agentroot.json",
    "records": [
      {
        "record_id": "assistant",
        "type": "agent",
        "name": "My Assistant",
        "description": "A research assistant",
        "endpoint": "https://example.com/agent"
      }
    ],
    "subdomains": [
      { "domain": "api.example.com", "total_records": 2 }
    ],
    "last_verified": "2025-04-01T12:00:00Z"
  }
}

GET /api/zones/:domain/records/:recordId

Get a specific record within a zone by its ID.

$ curl https://agentroot.io/api/zones/example.com/records/assistant

# Response
{
  "record": {
    "record_id": "assistant",
    "type": "agent",
    "name": "My Assistant",
    "description": "A research assistant that can search and analyze documents",
    "endpoint": "https://example.com/agent",
    "protocol": "a2a",
    "capabilities": ["research", "analysis"],
    "domain": "example.com"
  }
}

Records

GET /api/records

Search across all records in the registry. Supports filtering by type, search query, and capabilities.

Param	Type	Description
q	string	Search name, domain, description
type	string	Filter by type: agent, mcp, skill, a2a
transport	string	Filter MCP records by transport: sse, streamable-http, stdio
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

$ curl "https://agentroot.io/api/records?type=mcp&q=database"

# Response
{
  "records": [
    {
      "record_id": "db-tools",
      "type": "mcp",
      "name": "DataTools",
      "description": "Database query and visualization tools",
      "domain": "example.com",
      "transport": "sse",
      "endpoint": "https://example.com/mcp"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Discovery

GET /api/discover

Combined discovery endpoint. Returns agents, MCP servers, skills, and A2A endpoints in one call. Designed for agents building their tool set.

Param	Type	Description
q	string	Natural language search query
type	string	Filter by type: agent, mcp, skill, a2a

$ curl "https://agentroot.io/api/discover?q=database+tools"

# Response
{
  "records": [
    {
      "record_id": "db-tools",
      "type": "mcp",
      "name": "DataTools",
      "domain": "example.com",
      "description": "Database query and visualization tools"
    }
  ],
  "total": 1
}

Submission

POST /api/submit

Submit a domain for registration. AgentRoot will query the _agentroot.<domain> DNS TXT record, fetch the zone file, and index all records. For legacy support, also checks _agent.<domain> and _skill.<domain>.

Param	Type	Description
domain	string	Domain to register (required)

$ curl -X POST https://agentroot.io/api/submit \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourdomain.com"}'

# Response
{
  "success": true,
  "zone": {
    "domain": "yourdomain.com",
    "status": "verified",
    "record_count": 3
  }
}

POST /api/submit-url

Submit a SKILL.md URL directly for unverified listing. Auto-converts GitHub blob URLs to raw content URLs. Fetches and parses YAML frontmatter or markdown table for name and description.

Param	Type	Description
url	string	URL to a SKILL.md file (required). Must end in .md or serve text/plain or text/markdown.

$ curl -X POST https://agentroot.io/api/submit-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/org/repo/blob/main/SKILL.md"}'

# Response
{
  "success": true,
  "skill": {
    "domain": "org.github.io",
    "skill_id": "repo",
    "name": "My Skill",
    "description": "Does useful things",
    "source": "url",
    "verified": false
  },
  "upgrade_cta": "Want the green checkmark? Add a DNS TXT record..."
}

Other

GET /api/stats

Registry statistics. Returns zone and record counts broken down by type and status.

$ curl https://agentroot.io/api/stats

# Response
{
  "zones": { "total": 150, "verified": 120, "pending": 25, "failed": 5 },
  "records": {
    "total": 430,
    "agent": 85,
    "mcp": 160,
    "skill": 140,
    "a2a": 45
  }
}

POST /api/flag

Flag a record for review. Rate limited to 10 flags per IP per hour.

Param	Type	Description
domain	string	Domain of the record to flag (required)
record_id	string	Record ID to flag (required)
reason	string	Reason for flagging, 3-500 characters (required)

$ curl -X POST https://agentroot.io/api/flag \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "record_id": "bad-bot", "reason": "Contains misleading information"}'

# Response
{
  "success": true,
  "message": "Flag submitted for review"
}

POST /a2a

AgentRoot's A2A (Agent-to-Agent) endpoint. Send tasks to AgentRoot as an A2A agent. Supports JSON-RPC format per the A2A spec.

$ curl -X POST https://agentroot.io/a2a \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "id": "task-123",
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "Find MCP servers for database queries" }]
    }
  }
}'

# Response
{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-123",
    "status": { "state": "completed" },
    "artifacts": [
      {
        "parts": [{ "type": "text", "text": "Found 3 MCP servers..." }]
      }
    ]
  }
}

// next

$ curl api/