# AgentDNS

> DNS for the agent economy. Discover AI agents by capability, resolve endpoints in milliseconds, trust scores backed by real data.

AgentDNS is a public registry for AI agents. It allows agents and humans to discover other agents, resolve their endpoints, and assess trust via real usage data. 9,500+ agents indexed from MCP Registry, awesome-mcp-servers, npm, HuggingFace, and owner registrations.

## Base URL

https://www.agent-dns.tech

## API (v1)

All endpoints are under `/api/v1/`. Authentication is via Bearer token: `Authorization: Bearer adns_k1_...`

### Search Agents

GET /api/v1/agents?q={query}&capability={cap}&category={cat}&protocol={proto}&sort={sort}&page={n}&limit={n}

Returns a paginated list of agents matching the filters. All parameters are optional.

- q: free-text search across name, tagline, description
- capability: comma-separated capabilities (OR match)
- category: single category filter
- protocol: one of a2a, mcp, rest, graphql, websocket
- sort: relevance (default), trust, lookups, newest
- page: page number (default 1)
- limit: results per page (default 20, max 100)

### Resolve by Capability

GET /api/v1/resolve?capability={cap}&protocol={proto}&limit={n}

The primary machine endpoint. Returns agents matching the given capability, ranked by trust score. This is the recommended endpoint for agent-to-agent discovery.

- capability: required, comma-separated for multi-capability match
- protocol: optional filter (a2a, mcp, rest, graphql, websocket)
- limit: max results (default 10, max 50)

### Resolve Agent by ID or Slug

GET /api/v1/agents/{id_or_slug}

Returns full agent details including all endpoints, capabilities, trust score, health status, and metadata.

### Autocomplete Suggestions

GET /api/v1/suggest?q={query}&limit={n}

Returns matching agent names and capabilities for search autocomplete.

- q: required, minimum 1 character
- limit: max results (default 8, max 20)

### Compare Agents

GET /api/v1/compare?agents={slug1,slug2,slug3}

Returns detailed data for 2-5 agents with shared/unique capability analysis.

- agents: required, comma-separated slugs (2-5)

### Agent Changelog

GET /api/v1/agents/{id_or_slug}/changelog?page={n}&limit={n}

Returns field-level change history for an agent.

### Register Agent

POST /api/v1/agents (requires API key with write scope)

Body (JSON):
- slug (required): lowercase alphanumeric with hyphens, 3-80 chars
- name (required): 1-200 chars
- tagline: up to 300 chars
- description: up to 10000 chars
- capabilities: array of strings (max 50)
- categories: array of strings (max 20)
- a2a_endpoint: URL of A2A endpoint
- mcp_server_url: URL of MCP server
- api_endpoint: URL of REST API
- docs_url: URL of documentation
- agent_card: JSON object (A2A agent card)
- protocols: array of (a2a, mcp, rest, graphql, websocket)
- input_formats: array of (text, json, pdf, image, audio)
- output_formats: array of (text, json, markdown, pdf)
- pricing_model: one of free, per-task, subscription, usage-based, custom
- pricing_details: up to 500 chars
- tags: array of strings (max 50)
- metadata: JSON object

### Rate an Agent

POST /api/v1/agents/{id_or_slug}/rate (requires GitHub session)

Body: { "rating": 1 } for upvote, { "rating": -1 } for downvote. Same rating again removes it.

GET /api/v1/agents/{id_or_slug}/rate — returns current user's rating and aggregate counts.

### Update Agent

PATCH /api/v1/agents/{id_or_slug} (requires API key with write scope, owner only)

Body: any subset of the registration fields. Changes are tracked in the changelog.

### Delete Agent (Soft)

DELETE /api/v1/agents/{id_or_slug} (requires API key with write scope, owner only)

Sets agent status to inactive.

### Health Check

GET /api/v1/health

Returns status, agent count, version, and timestamp. No authentication required.

## Machine Discovery

- A2A Agent Card: /.well-known/agent.json
- Multi-Agent Manifest: /.well-known/agents.json
- OpenAPI 3.0 Spec: /api/v1/openapi.json
- MCP Server: npx @agentdns/mcp-server
- Full Documentation: /llms-full.txt

## Authentication

1. Sign in at /dashboard with GitHub
2. Create an API key with "write" scope
3. Use header: Authorization: Bearer adns_k1_...

Read operations are public (no key needed, rate limited at 60 req/min).
Write operations require an API key with write scope (rate limited at 30 req/min).
Authenticated reads get higher rate limits (600 req/min).

## Optional

- [API Reference](/api/v1/openapi.json): Full OpenAPI 3.0 specification
- [Agent Card](/.well-known/agent.json): A2A protocol agent discovery card
- [Full Documentation](/llms-full.txt): Complete API reference in one file
- [Explore Agents](/explore): Browse the agent directory
- [Compare Agents](/compare): Side-by-side agent comparison
- [Register](/register): Register a new agent via the web UI