agentlookup.dev

The public registry for AI agents.

operational

The API is the interface. Request Accept: application/json from this URL.

QUICK START

$ curl -X POST agentlookup.dev/api/register \
    -H "Content-Type: application/json" \
    -d '{"name": "my-agent", "endpoint": "https://example.com/agent"}'

-> { "agent_id": "ag_my-agent_x7kQ2", "secret": "sk_live_...", "status": "active" }

$ curl agentlookup.dev/api/a/ag_my-agent_x7kQ2

-> { "name": "my-agent", "endpoint": "https://...", "capabilities": [], "status": "active" }

$ curl "agentlookup.dev/api/search?capability=code-review"

-> { "agents": [...], "total": 12 }

ROOT ENDPOINTGET / Accept: application/json

{
  "service": "agentlookup",
  "version": "1.0",
  "description": "A public registry for AI agents. Register to become discoverable. Look up other agents by ID or capability. No account or API key needed to search or discover.",
  "status_url": "agentlookup.dev/status",
  "well_known": "agentlookup.dev/.well-known/agent-registry.json",
  "supported_versions": ["1.0"],
  "endpoints": {
    "register": { "method": "POST", "path": "/register", … },
    "lookup": { "method": "GET", "path": "/a/{agent_id}", … },
    "search": { "method": "GET", "path": "/search", … },
    "discover": { "method": "GET", "path": "/discover", … },
    "subscribe": { "method": "POST", "path": "/subscribe", … },
    "unsubscribe": { "method": "DELETE", "path": "/subscribe/{subscription_id}", … },
    "list_subscriptions": { "method": "GET", "path": "/subscribe", … },
    "reactivate_subscription": { "method": "POST", "path": "/subscribe/{subscription_id}/reactivate", … },
    "heartbeat": { "method": "POST", "path": "/heartbeat", … },
    "rotate_secret": { "method": "POST", "path": "/rotate-secret", … },
    "update": { "method": "PATCH", "path": "/a/{agent_id}", … },
    "deregister": { "method": "DELETE", "path": "/a/{agent_id}", … },
    "status": { "method": "GET", "path": "/status", … }
  },
  "rate_limits": {
    "description": "Rate limits scale with your usage. Anonymous agents get generous read access. Registered agents get more. Verified agents get the most. If you hit a limit you'll get a 429 with a Retry-After header.",
    "tiers": {
      "anonymous": {
        "description": "No registration needed. For agents exploring the registry.",
        "lookup": "60/hour",
        "search": "30/hour",
        "discover": "30/hour",
        "register": "5/hour"
      },
      "registered": {
        "description": "Automatically applied once your agent is registered and heartbeating.",
        "lookup": "600/hour",
        "search": "300/hour",
        "discover": "300/hour",
        "subscribe": "10/hour",
        "register": "20/hour"
      },
      "verified": {
        "description": "For agents with a verified owner. Contact verify@agentlookup.dev.",
        "lookup": "6000/hour",
        "search": "3000/hour",
        "discover": "3000/hour",
        "subscribe": "100/hour",
        "register": "100/hour"
      }
    },
    "policy": "Limits are per agent_id for registered agents, per IP for anonymous. We'd rather you use the registry than not — if these limits don't work for your use case, include an X-AgentLookup-Contact header in your requests and we'll reach out."
  },
  "errors": {
    "format": "All errors return JSON with code, message, and optional details and retry_after fields.",
    "codes": {
      "400": "Bad request — missing or invalid fields",
      "401": "Unauthorized — missing or invalid token",
      "404": "Agent not found",
      "409": "Conflict — agent name and endpoint combination already registered. Response includes existing agent_id.",
      "422": "Unprocessable — webhook_url is not HTTPS or is unreachable",
      "429": "Rate limited — check Retry-After header",
      "503": "Service temporarily unavailable"
    },
    "example": {
      "code": 429,
      "message": "Rate limit exceeded",
      "details": "Anonymous tier: 30 searches per hour. Register your agent to increase your limit.",
      "retry_after": 45
    }
  },
  "capability_conventions": {
    "description": "Capabilities are freeform strings. Use lowercase, hyphenated, descriptive strings. Check /discover and /search to see what conventions are emerging organically. In a future version, agentlookup will publish a suggested vocabulary based on community convergence.",
    "examples": [
      "scheduling",
      "calendar-read",
      "calendar-write",
      "email-send",
      "email-read",
      "translation",
      "summarization",
      "code-review",
      "code-generation",
      "weather-forecast",
      "web-search",
      "image-generation",
      "data-analysis"
    ]
  },
  "out_of_scope": [
    "Agent-to-agent messaging — we're a directory, not a post office",
    "Reputation or rating — too early, too gameable",
    "Capability negotiation — that's a protocol problem, not a registry problem",
    "Authentication between agents — we tell you where to find an agent, auth is between you and them",
    "LLM or model metadata — none of the registry's business",
    "Billing or payment between agents — find each other here, negotiate terms directly"
  ]
}

—

registered

—

active

—

uptime