$ curl api/

Query the AgentRoot registry programmatically. Base URL: https://agentroot.io

Manifests

GET/api/manifests

List all registered manifests. Filters compose with AND — pass any combination, the response is the intersection. The web registry page's chip set and search-bar token grammar both lower to these params; deep-link any state.

Param	Type	Description
q	string	Substring match on manifest.domain (case-insensitive)
type	string	Only manifests with at least one record of this type: `agent`, `mcp`, `skill`, `a2a`, `payment`
has_payment	bool	Only manifests with at least one record of type `payment`
recent	string	Only manifests verified within the last N days. Accepts `true` (defaults to 7), `7d`, or a bare integer
domain	string	Substring filter on manifest.domain — pair with `q` only if you want stricter matching
tld	string	Domain TLD suffix — `.ai` or `ai` both work
capability	string	Manifests where at least one record's `capabilities` includes this substring
protocol	string	Manifests where at least one record's `protocol` matches
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

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

# Response
{
  "manifests": [
    {
      "domain": "example.com",
      "status": "verified",
      "manifest_url": "https://example.com/.well-known/agentroot.json",
      "record_count": 3,
      "last_verified": "2026-05-19T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "pages": 1
}

GET/api/manifests/:domain

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

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

# Response
{
  "manifest": {
    "domain": "example.com",
    "status": "verified",
    "manifest_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": "2026-05-19T12:00:00Z"
  }
}

The subdomains field is enriched here into { domain, total_records } objects so a UI can render counts without a second fetch. In the manifest you serve from your own domain, it is just a string array of labels.

GET/api/manifests/:domain/records/:recordId

Get a specific record within a manifest by its ID.

$ curl https://agentroot.io/api/manifests/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. This is the primary cross-manifest search endpoint — what the CLI's agent-root search and the web UI both call.

Param	Type	Description
q	string	Search name, domain, description
type	string	Filter by type: agent, mcp, skill, a2a, payment
capability	string	Filter records by a capability keyword (matches `capabilities[]`)
protocol	string	Filter payment records by protocol (x402, mpp, a2a-payments, ...)
method	string	Filter payment records by accepted method
asset	string	Filter payment records by accepted asset (USDC, USD, ...)
payment	string	Convenience flag for "payment-related" rows (true / false)
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 (legacy)

GET/api/discover

Legacy. New integrations should use GET /api/records instead — it returns the same shapes plus pagination metadata, and is what the CLI and web UI both call. /api/discover is preserved for back-compat and currently caps results at 100.

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

$ 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
}

Collections

GET/api/collections

List every curated collection. Editorial groupings of records — e.g. featured-domains, payments, devtools.

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

# Response
{
  "collections": [
    {
      "slug": "featured-domains",
      "title": "Featured Domains",
      "description": "Hand-picked manifests",
      "item_count": 12
    }
  ]
}

GET/api/collections/:slug

Open a single collection by slug. Returns its items, each pointing at a manifest or record.

$ curl https://agentroot.io/api/collections/featured-domains

# Response
{
  "collection": {
    "slug": "featured-domains",
    "title": "Featured Domains",
    "items": [
      { "domain": "doma.xyz", "position": 1 },
      { "domain": "stripe.com", "position": 2 }
    ]
  }
}

Submission

POST/api/submit

Submit a domain for registration. AgentRoot will query the _agentroot.<domain> DNS TXT record, fetch the manifest, and index all records.

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,
  "manifest": {
    "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.

Param	Type	Description
url	string	URL to a SKILL.md file (required)

$ 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",
    "name": "My Skill",
    "verified": false
  }
}

Health & ops

GET/api/health

Liveness + DB connectivity check. Returns 200 when the registry is healthy, non-2xx otherwise. The CLI's agent-root health wraps this so it can be used as a CI gate.

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

# Response
{
  "status": "ok",
  "db": "connected"
}

GET/api/stats

Registry statistics. Returns manifest and record counts broken down by type and status. Intended for the public stats page on agentroot.io — not part of the CLI surface.

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

# Response
{
  "manifests": { "total": 150, "verified": 120 },
  "records": {
    "total": 430,
    "agent": 85,
    "mcp": 160,
    "skill": 140,
    "a2a": 45
  }
}

GET/api/manifests/:domain/records/:recordId/badge

SVG verification badge for a record. Embed in READMEs or marketing pages so visitors can confirm the record is currently indexed and verified.

$ curl https://agentroot.io/api/manifests/doma.xyz/records/doma-protocol/badge

// next

← DNS Records

Tools →