← Docs

API Reference

The AgentDNS registry REST API. Base URL: https://agentdns.dev

GET/api/discover#

Search for services by intent. Returns matching services ranked by relevance, with capability matches highlighted.

Query Parameters

qstringRequired. Natural language search query.
Request
GET /api/discover?q=send+email
Response (200)
{
  "success": true,
  "query": "send email",
  "result_count": 2,
  "data": [
    {
      "service": {
        "name": "MailForge",
        "domain": "api.mailforge.dev",
        "description": "Transactional email API",
        "base_url": "https://api.mailforge.dev",
        "auth_type": "api_key",
        "pricing_type": "freemium",
        "verified": true
      },
      "matching_capabilities": [
        {
          "name": "send_email",
          "description": "Send a transactional email",
          "detail_url": "https://api.mailforge.dev/api/capabilities/send_email"
        }
      ],
      "all_capabilities": [ ... ]
    }
  ]
}
GET/api/services#

List all registered services with pagination, filtering, and sorting.

Query Parameters

categorystring?Filter by category slug
searchstring?Text search in name/description
sortstring?"newest" | "name" | "capabilities"
limitnumber?Max 100, default 50
offsetnumber?Pagination offset, default 0
Response (200)
{
  "success": true,
  "data": [
    {
      "name": "MailForge",
      "domain": "api.mailforge.dev",
      "description": "Transactional email API",
      "base_url": "https://api.mailforge.dev",
      "auth_type": "api_key",
      "pricing_type": "freemium",
      "verified": true,
      "capability_count": 3,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": { "total": 42, "limit": 50, "offset": 0 }
}
POST/api/services#

Submit a new service. Two modes: auto-discover by domain, or manual manifest paste.

Mode 1: Auto-discover

Request
POST /api/services
Content-Type: application/json

{
  "domain": "api.example.com"
}

The registry will crawl https://api.example.com/.well-known/agent, validate the manifest, and register the service.

Mode 2: Manual manifest

Request
POST /api/services
Content-Type: application/json

{
  "manifest": {
    "spec_version": "1.0",
    "name": "My API",
    "description": "...",
    "base_url": "https://api.example.com",
    "auth": { "type": "none" },
    "capabilities": [ ... ]
  }
}
Response (201)
{
  "success": true,
  "data": {
    "domain": "api.example.com",
    "name": "My API",
    "verified": true,
    "detail_url_ok": true,
    "response_time_ms": 142,
    "message": "Service discovered and registered successfully."
  }
}
Error Response (422)
{
  "success": false,
  "errors": [
    "Missing required field: spec_version",
    "Description must be 10-200 characters"
  ]
}
GET/api/services/:domain#

Get detailed information about a specific registered service, including all capabilities.

Request
GET /api/services/api.mailforge.dev
Response (200)
{
  "success": true,
  "data": {
    "name": "MailForge",
    "domain": "api.mailforge.dev",
    "description": "Transactional email API",
    "base_url": "https://api.mailforge.dev",
    "auth_type": "api_key",
    "pricing_type": "freemium",
    "verified": true,
    "capabilities": [
      {
        "name": "send_email",
        "description": "Send a transactional email",
        "detail_url": "/api/capabilities/send_email"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "last_crawled_at": "2024-01-20T08:00:00Z"
  }
}
POST/api/verify/:domain#

Re-crawl a registered service and update its verification status. Checks that the manifest is valid and at least one detail_url resolves.

Request
POST /api/verify/api.mailforge.dev
Response (200)
{
  "success": true,
  "data": {
    "domain": "api.mailforge.dev",
    "verified": true,
    "detail_url_ok": true,
    "response_time_ms": 89,
    "message": "Service verified successfully. Manifest updated from live endpoint."
  }
}
POST/api/validate#

Validate a manifest without registering it. Useful for testing before submission.

Request
POST /api/validate
Content-Type: application/json

{
  "spec_version": "1.0",
  "name": "My API",
  "description": "Test manifest",
  "base_url": "https://api.example.com",
  "auth": { "type": "none" },
  "capabilities": [
    {
      "name": "test_cap",
      "description": "A test capability",
      "detail_url": "/api/capabilities/test"
    }
  ]
}
Response (200) — Valid
{
  "valid": true,
  "errors": []
}
Response (200) — Invalid
{
  "valid": false,
  "errors": [
    { "path": "$.description", "message": "Description must be 10-200 characters" },
    { "path": "$.capabilities[0].name", "message": "Capability name must be snake_case" }
  ]
}

Response Format

All API responses follow a consistent format:

// Success
{ "success": true, "data": { ... } }

// Error
{ "success": false, "error": "Description of what went wrong" }

// Validation error
{ "success": false, "errors": ["error1", "error2"] }

// HTTP status codes:
// 200 — Success
// 201 — Created
// 400 — Bad request (missing/invalid params)
// 404 — Not found
// 409 — Conflict (already exists)
// 422 — Validation failed
// 500 — Server error