API Reference

The AgentDNS REST API enables any agent or application to search, resolve, and register AI agents programmatically.

OpenAPI Spec A2A Agent Card MCP Server Register Agent

Authentication

Read operations (search, resolve) are public — no authentication required. Write operations (register, update, delete) require an API key.

Get an API Key

Sign in with GitHub at /dashboard
Click “Generate API Key” and give it a name
Copy your key — it starts with adns_k1_

Using the Key

Authorization: Bearer adns_k1_YOUR_KEY

Rate Limits

Tier	Read (GET)	Write (POST/PATCH/DELETE)
Anonymous	60 req/min	—
Authenticated (API key)	200 req/min	30 req/min

Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset

Base URL

https://agent-dns.tech/api/v1

Try It

Search agents live:

Or call the API directly: curl "https://agent-dns.tech/api/v1/agents?capability=browser-automation&protocol=mcp"

Endpoints

GET/api/v1/agentsNone

Search and list agents with optional filters. Returns paginated results sorted by trust score.

Query Parameters

qstringFull-text search across name, tagline, description

capabilitystringFilter by capability tag (comma-separated for OR)

categorystringFilter by category

protocola2a | mcp | rest | graphql | websocketFilter by protocol

sortrelevance | trust | lookups | newestSort order (default: relevance)

pageintegerPage number (default: 1)

limitintegerResults per page, max 100 (default: 20)

Response

{ agents: AgentListItem[], total: number, page: number, limit: number }

Example

curl "https://agent-dns.tech/api/v1/agents?capability=browser-automation&protocol=mcp"

POST/api/v1/agentsAPI Key (write)

Request Body

slugstring3-80 chars, lowercase alphanumeric with hyphensrequired

namestringAgent display name, max 200 charsrequired

taglinestringOne-line description, max 300 chars

descriptionstringFull description, max 10,000 chars

capabilitiesstring[]Array of capability tags

protocolsstring[]Supported protocols: a2a, mcp, rest, graphql, websocket

a2a_endpointURLA2A agent card URL

mcp_server_urlURLMCP server URL

api_endpointURLREST API endpoint URL

docs_urlURLDocumentation URL

pricing_modelstringfree | per-task | subscription | usage-based | custom

Response

{ data: Agent }

Example

curl -X POST "https://agent-dns.tech/api/v1/agents" \
  -H "Authorization: Bearer adns_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-agent","name":"My Agent","capabilities":["summarization"],"protocols":["mcp"]}'

GET/api/v1/agents/{slug}None

Resolve a specific agent by slug or UUID. Returns full agent details including endpoints, capabilities, and trust score.

Response

{ data: Agent }

Example

curl "https://agent-dns.tech/api/v1/agents/playwright-mcp"

PATCH/api/v1/agents/{slug}API Key (write)

Update an existing agent. Only the owner (matching owner_id) can update. All fields are optional.

Request Body

namestringAgent display name

taglinestringOne-line description

capabilitiesstring[]Replace capabilities array

statusstringactive | inactive | deprecated | suspended

Response

{ data: Agent }

Example

curl -X PATCH "https://agent-dns.tech/api/v1/agents/my-agent" \
  -H "Authorization: Bearer adns_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tagline":"Updated tagline"}'

DELETE/api/v1/agents/{slug}API Key (write)

Soft-delete an agent (sets status to inactive). Only the owner can delete.

Response

{ data: { message: string } }

Example

curl -X DELETE "https://agent-dns.tech/api/v1/agents/my-agent" \
  -H "Authorization: Bearer adns_k1_YOUR_KEY"

GET/api/v1/resolveNone

Primary machine-to-machine discovery endpoint. Resolve agents by capability, optionally filtered by protocol. Returns results ranked by trust score.

Query Parameters

capabilitystringCapability to resolve (comma-separated for multiple)required

protocolstringFilter by protocol: a2a, mcp, rest, graphql, websocket

limitintegerMax results, 1-50 (default: 10)

Response

{ matches: ResolveMatch[], query: object, total: number }

Example

curl "https://agent-dns.tech/api/v1/resolve?capability=browser-automation&protocol=mcp&limit=5"

GET/api/v1/healthNone

Health check endpoint. Returns service status, agent count, and API version.

Response

{ status: "ok", agents_count: number, version: string, timestamp: string }

Example

curl "https://agent-dns.tech/api/v1/health"

Error Codes

HTTP	Code	Description
400	validation_error	Request body or params failed validation
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks required scope
404	not_found	Agent not found
409	conflict	Slug already exists
429	rate_limited	Too many requests — back off and retry
500	db_error	Internal server error

Authentication

Read operations (search, resolve) are public — no authentication required. Write operations (register, update, delete) require an API key.

Get an API Key

Sign in with GitHub at /dashboard
Click “Generate API Key” and give it a name
Copy your key — it starts with adns_k1_

Using the Key

Authorization: Bearer adns_k1_YOUR_KEY

Tier

Read (GET)

Write (POST/PATCH/DELETE)

Anonymous

60 req/min

—

Authenticated (API key)

200 req/min

30 req/min

Endpoints

GET/api/v1/agentsNone

Search and list agents with optional filters. Returns paginated results sorted by trust score.

Query Parameters

qstringFull-text search across name, tagline, description

capabilitystringFilter by capability tag (comma-separated for OR)

categorystringFilter by category

protocola2a | mcp | rest | graphql | websocketFilter by protocol

sortrelevance | trust | lookups | newestSort order (default: relevance)

pageintegerPage number (default: 1)

limitintegerResults per page, max 100 (default: 20)

Response

{ agents: AgentListItem[], total: number, page: number, limit: number }

Example

curl "https://agent-dns.tech/api/v1/agents?capability=browser-automation&protocol=mcp"

POST/api/v1/agentsAPI Key (write)

Request Body

slugstring3-80 chars, lowercase alphanumeric with hyphensrequired

namestringAgent display name, max 200 charsrequired

taglinestringOne-line description, max 300 chars

descriptionstringFull description, max 10,000 chars

capabilitiesstring[]Array of capability tags

protocolsstring[]Supported protocols: a2a, mcp, rest, graphql, websocket

a2a_endpointURLA2A agent card URL

mcp_server_urlURLMCP server URL

api_endpointURLREST API endpoint URL

docs_urlURLDocumentation URL

pricing_modelstringfree | per-task | subscription | usage-based | custom

Response

{ data: Agent }

Example

curl -X POST "https://agent-dns.tech/api/v1/agents" \
  -H "Authorization: Bearer adns_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-agent","name":"My Agent","capabilities":["summarization"],"protocols":["mcp"]}'

GET/api/v1/agents/{slug}None

Resolve a specific agent by slug or UUID. Returns full agent details including endpoints, capabilities, and trust score.

Response

{ data: Agent }

Example

curl "https://agent-dns.tech/api/v1/agents/playwright-mcp"

PATCH/api/v1/agents/{slug}API Key (write)

Update an existing agent. Only the owner (matching owner_id) can update. All fields are optional.

Request Body

namestringAgent display name

taglinestringOne-line description

capabilitiesstring[]Replace capabilities array

statusstringactive | inactive | deprecated | suspended

Response

{ data: Agent }

Example

curl -X PATCH "https://agent-dns.tech/api/v1/agents/my-agent" \
  -H "Authorization: Bearer adns_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tagline":"Updated tagline"}'

DELETE/api/v1/agents/{slug}API Key (write)

Soft-delete an agent (sets status to inactive). Only the owner can delete.

Response

{ data: { message: string } }

Example

curl -X DELETE "https://agent-dns.tech/api/v1/agents/my-agent" \
  -H "Authorization: Bearer adns_k1_YOUR_KEY"

GET/api/v1/resolveNone

Primary machine-to-machine discovery endpoint. Resolve agents by capability, optionally filtered by protocol. Returns results ranked by trust score.

Query Parameters

capabilitystringCapability to resolve (comma-separated for multiple)required

protocolstringFilter by protocol: a2a, mcp, rest, graphql, websocket

limitintegerMax results, 1-50 (default: 10)

Response

{ matches: ResolveMatch[], query: object, total: number }

Example

curl "https://agent-dns.tech/api/v1/resolve?capability=browser-automation&protocol=mcp&limit=5"

GET/api/v1/healthNone

Health check endpoint. Returns service status, agent count, and API version.

Response

{ status: "ok", agents_count: number, version: string, timestamp: string }

Example

curl "https://agent-dns.tech/api/v1/health"

Error Codes

HTTP	Code	Description
400	validation_error	Request body or params failed validation
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks required scope
404	not_found	Agent not found
409	conflict	Slug already exists
429	rate_limited	Too many requests — back off and retry
500	db_error	Internal server error