# AgentDNS — Complete API Reference

> 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 9,500+ AI agents. Agents are indexed from the MCP Registry, awesome-mcp-servers, npm, HuggingFace Spaces, A2A Agent Cards, and owner registrations. Trust scores are calculated algorithmically from metadata completeness, endpoint health, usage popularity, source reputation, verification status, and recency.

Base URL: https://www.agent-dns.tech

## Quick Start

Search for agents:
```
curl "https://www.agent-dns.tech/api/v1/agents?q=database"
```

Resolve by capability (primary machine endpoint):
```
curl "https://www.agent-dns.tech/api/v1/resolve?capability=code-execution&protocol=mcp"
```

Get agent details:
```
curl "https://www.agent-dns.tech/api/v1/agents/playwright-mcp"
```

## Authentication

Read operations are public. No API key needed. Rate limit: 60 requests/minute.

Write operations require a Bearer token:
```
Authorization: Bearer adns_k1_...
```

Get an API key:
1. Sign in at https://www.agent-dns.tech/dashboard with GitHub
2. Generate an API key with "write" scope
3. Key format: adns_k1_... (never expires unless revoked)

Authenticated reads: 600 requests/minute.
Write operations: 30 requests/minute.

## Endpoints

### GET /api/v1/agents — Search agents

Query parameters (all optional):
| Parameter | Type | Description |
|-----------|------|-------------|
| q | string | Free-text search (name, tagline, description) |
| capability | string | Comma-separated capabilities (OR match) |
| category | string | Single category filter |
| protocol | string | a2a, mcp, rest, graphql, websocket |
| status | string | active (default), inactive, deprecated, suspended |
| verified | string | "true" to filter verified agents only |
| sort | string | relevance (default), trust, lookups, newest |
| page | integer | Page number (default 1) |
| limit | integer | Results per page (default 20, max 100) |

Response:
```json
{
  "agents": [
    {
      "id": "uuid",
      "slug": "agent-slug",
      "name": "Agent Name",
      "tagline": "Short description",
      "listing_type": "verified",
      "capabilities": ["search", "database"],
      "categories": ["developer-tools"],
      "protocols": ["mcp"],
      "is_verified": true,
      "trust_score": 0.85,
      "total_lookups": 1234,
      "pricing_model": "free",
      "health_status": "healthy",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}
```

### GET /api/v1/resolve — Resolve by capability

The primary machine-to-machine discovery endpoint. Returns agents ranked by trust score.

Query parameters:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| capability | string | Yes | Capability to match (comma-separated for multi) |
| protocol | string | No | Filter by protocol |
| limit | integer | No | Max results (default 10, max 50) |

Response:
```json
{
  "matches": [
    {
      "id": "uuid",
      "slug": "agent-slug",
      "name": "Agent Name",
      "trust_score": 0.92,
      "a2a_endpoint": "https://...",
      "mcp_server_url": null,
      "api_endpoint": "https://...",
      "pricing_model": "free",
      "capabilities": ["contract-review", "legal"],
      "protocols": ["a2a", "rest"]
    }
  ],
  "query": { "capability": "contract-review" },
  "total": 3
}
```

### GET /api/v1/agents/{id} — Get agent details

Path parameter: Agent UUID or slug.

Returns full agent object with all fields: description, owner info, version, status, all endpoints, agent card (JSONB), protocols, I/O formats, trust score, total lookups, pricing, tags, metadata, health status, and timestamps.

### POST /api/v1/agents — Register agent

Requires Bearer token with write scope.

Request body:
```json
{
  "slug": "my-agent",
  "name": "My Agent",
  "tagline": "Does amazing things",
  "description": "Full description...",
  "capabilities": ["search", "summarization"],
  "categories": ["data"],
  "a2a_endpoint": "https://my-agent.com/.well-known/agent.json",
  "mcp_server_url": "https://my-agent.com/mcp",
  "api_endpoint": "https://my-agent.com/api",
  "docs_url": "https://my-agent.com/docs",
  "protocols": ["a2a", "mcp", "rest"],
  "input_formats": ["text", "json"],
  "output_formats": ["json", "markdown"],
  "pricing_model": "free"
}
```

Required fields: slug, name. All others optional.

### PATCH /api/v1/agents/{id} — Update agent (owner only)

Requires Bearer token with write scope. Only the agent's owner can update.
Send any subset of registration fields. Changes are tracked in the changelog.

### DELETE /api/v1/agents/{id} — Deactivate agent (owner only)

Soft-delete: sets status to "inactive". Agent can be reactivated.

### GET /api/v1/suggest — Autocomplete

Query parameters: q (required, min 1 char), limit (default 8, max 20).

Returns: `{ "agents": [...], "capabilities": ["cap1", "cap2"] }`

### GET /api/v1/compare — Compare agents

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

Returns full agent details plus comparison analysis:
```json
{
  "agents": [...],
  "comparison": {
    "shared_capabilities": ["search"],
    "unique_capabilities": [
      { "slug": "agent-a", "unique_capabilities": ["database"] },
      { "slug": "agent-b", "unique_capabilities": ["browser"] }
    ],
    "shared_protocols": ["mcp"]
  }
}
```

### GET /api/v1/agents/{id}/changelog — Change history

Paginated field-level change history. Shows what changed, old value, new value, and when.

### GET /api/v1/agents/{id}/rate — Get ratings

Returns: `{ "data": { "rating": 1, "up": 42, "down": 3 } }`

### POST /api/v1/agents/{id}/rate — Rate agent

Requires GitHub session. Body: `{ "rating": 1 }` (upvote) or `{ "rating": -1 }` (downvote).
Same rating again removes it (toggle).

### GET /api/v1/health — Health check

Returns: `{ "status": "ok", "agents_count": 9500, "version": "1.0.0", "timestamp": "..." }`

## Trust Score Algorithm

Scores range from 0.10 to 0.99. Calculated from:

- Base: 0.30
- Description > 20 chars: +0.05
- Tagline > 5 chars: +0.05
- 2+ capabilities: +0.05
- Documentation URL: +0.05
- Has endpoint (A2A/MCP/REST): +0.10
- MCP official servers source: +0.10
- MCP registry source: +0.05
- Verified listing: +0.15
- 1000+ lookups: +0.10, 100+: +0.07, 10+: +0.03, 1+: +0.01
- Not updated in 180+ days: -0.05, 90+ days: -0.02
- Endpoint down: -0.10, degraded: -0.05

## Machine Discovery Endpoints

- A2A Agent Card: https://www.agent-dns.tech/.well-known/agent.json
- Multi-Agent Manifest: https://www.agent-dns.tech/.well-known/agents.json
- OpenAPI 3.0 Spec: https://www.agent-dns.tech/api/v1/openapi.json
- LLM Summary: https://www.agent-dns.tech/llms.txt
- MCP Server: npx @agentdns/mcp-server

## Error Responses

All errors follow this format:
```json
{
  "error": {
    "code": "validation_error",
    "message": "Human-readable description"
  }
}
```

Error codes: validation_error (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), rate_limited (429), db_error (500).

## Rate Limit Headers

All responses include:
- X-RateLimit-Remaining: requests left in current window
- X-RateLimit-Reset: Unix timestamp when window resets

## Agent Categories

data, engineering, developer-tools, infrastructure, productivity, content, finance, support, sales, security, healthcare, education, legal, design-creative

## Supported Protocols

a2a (Google Agent-to-Agent), mcp (Anthropic Model Context Protocol), rest, graphql, websocket