Documentation

Everything you need to register AI agents, query the directory, and integrate verification into your workflow.

Quick Start

1
Create an account
Go to getaid.dev/signup and sign up with email or OAuth (GitHub, Google). Verify your email address.
2
Register an agent
Open Dashboard → My Agents → Register New Agent. Fill in a name, description, and optional metadata (endpoint, protocols, capabilities).
3
Save your credentials
After registration you receive a permanent Agent ID (e.g. AID-000012347) and an Ed25519 private key. The private key is shown once. Download it and store it securely.
4
Embed your badge
Copy the Markdown or HTML badge snippet from the agent detail page and add it to your README or website. The badge links back to your verified profile on getaid.dev.
markdown
```
[![AID](https://getaid.dev/badge/AID-000012347)](https://getaid.dev/verify/AID-000012347)
```

API Reference

All endpoints are versioned under /api/v1/. Requests and responses use JSON. Public reads require no auth; writes require a Bearer token.

Base URL: https://getaid.dev/api/v1

Agents

GET/v1/agents

Public

Search the agent directory. Supports full-text search, filtering, and cursor-based pagination.

bash

curl "https://getaid.dev/api/v1/agents?query=payment&status=active&limit=10"

POST/v1/agents

write

bash

curl -X POST https://getaid.dev/api/v1/agents \
  -H "Authorization: Bearer aid_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Agent",
    "description": "Handles payment processing for e-commerce",
    "endpointUrl": "https://api.example.com/agent",
    "protocols": ["REST"]
  }'

json

{
  "aid": "AID-000012347",
  "handle": "@yourhandle/payment-agent",
  "name": "Payment Agent",
  "publicKey": "3b6a27bcceb...",
  "privateKey": "9d61b19def..."
}

GET/v1/agents/:aid

Public

Get the full profile of a specific agent by AID.

bash

curl https://getaid.dev/api/v1/agents/AID-000012347

PATCH/v1/agents/:aid

write + owner

Update an agent's mutable fields (name, description, endpoint, etc.).

bash

curl -X PATCH https://getaid.dev/api/v1/agents/AID-000012347 \
  -H "Authorization: Bearer aid_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated description" }'

DELETE/v1/agents/:aid

write + owner

Soft-delete (deregister) an agent. The AID remains permanently reserved and the profile stays accessible in read-only mode.

Challenge & Verify

POST/v1/agents/:aid/challenge

Public

Issue a cryptographic nonce. The agent must sign it with its Ed25519 private key within 5 minutes.

json

{
  "nonce": "a1b2c3d4...",
  "expiresAt": "2026-03-15T12:05:00.000Z"
}

POST/v1/agents/:aid/challenge/verify

Public

Verify a signed nonce to confirm agent identity.

bash

curl -X POST https://getaid.dev/api/v1/agents/AID-000012347/challenge/verify \
  -H "Content-Type: application/json" \
  -d '{
    "nonce": "a1b2c3d4...",
    "signature": "e5f6a7b8..."
  }'

json

{
  "verified": true,
  "aid": "AID-000012347",
  "verificationTier": 1
}

Heartbeat & Status

POST/v1/agents/:aid/heartbeat

write + owner

Push a heartbeat to confirm the agent is alive. Optionally include a status field ("healthy" or "degraded").

bash

curl -X POST https://getaid.dev/api/v1/agents/AID-000012347/heartbeat \
  -H "Authorization: Bearer aid_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "healthy" }'

GET/v1/agents/:aid/status

Public

Get the current heartbeat status and latest check details.

json

{
  "aid": "AID-000012347",
  "status": "active",
  "lastHeartbeatAt": "2026-03-15T11:00:00.000Z",
  "latestHeartbeat": {
    "status": "healthy",
    "responseTimeMs": 142,
    "checkedAt": "2026-03-15T11:00:00.000Z"
  }
}

Keys

GET/v1/agents/:aid/publickey

Public

Retrieve the Ed25519 public key and algorithm for an agent.

json

{
  "aid": "AID-000012347",
  "publicKey": "3b6a27bcceb6a42d62a3a8d02a6f0d73...",
  "keyAlgorithm": "Ed25519"
}

POST/v1/agents/:aid/keys/rotate

admin + owner

Rotate the agent's Ed25519 keypair. The old key is immediately invalidated and a new private key is returned once.

Authentication

API keys authenticate write operations. Public read endpoints (agent lookup, directory search, status) require no auth.

Creating an API Key

Go to Dashboard → API Keys or call POST /v1/auth/keys. Keys follow the format aid_live_[32 hex chars]. The raw key is shown once. Store it securely.

Using Bearer Tokens

Pass your API key in the Authorization header:

bash

curl -H "Authorization: Bearer aid_live_71a2f3..." \
  https://getaid.dev/api/v1/users/me/agents

Scope Hierarchy

Each API key has a scope that determines what operations it can perform. Higher scopes include all lower scopes.

Scope	Grants
`read`	Search agents, view profiles, list own agents, submit reports
`write`	Register/update/delete agents, push heartbeats + everything in `read`
`admin`	Rotate keys, manage API keys + everything in `write`

Rate Limits

Rate limits are per 60-second sliding window, based on your plan tier.

Plan	Read	Write	Heartbeat
Unauthenticated	60	—	—
Free	100	30	10
Pro	3,000	300	100
Business	6,000	1,000	500

Badge Embed

Embed a verification badge in your README, website, or documentation. Badges link to the agent's verification page on getaid.dev.

Styles

Style	Description
`flat`	Default flat badge (no query param needed)
`flat-square`	Square corners
`plastic`	Gradient / 3D style
`for-the-badge`	Large uppercase
`live`	Real-time status dot (requires HMAC signature)

Embed Snippets

Replace AID-000012347 with your agent's AID. You can also copy these directly from the agent detail page in the dashboard.

Markdown

markdown

[![AID Verified](https://getaid.dev/badge/AID-000012347)](https://getaid.dev/verify/AID-000012347)

HTML

html

<a href="https://getaid.dev/verify/AID-000012347">
  <img src="https://getaid.dev/badge/AID-000012347" alt="AID Verified" />
</a>

With style

text

https://getaid.dev/badge/AID-000012347?style=flat-square

Live badge (HMAC-signed)

Live badges include a real-time status dot and require a server-generated HMAC signature. Use the dashboard embed code, which generates a signed URL automatically.

MCP Integration

The @getaid/mcp-server package lets any MCP-compatible AI client query the getaid.dev registry. Supported clients include Claude Desktop, Claude Code, Cursor, Codex, Windsurf, and any tool that implements the Model Context Protocol.

Claude Desktop

Add to claude_desktop_config.json in your Claude Desktop config directory:

json

{
  "mcpServers": {
    "getaid": {
      "command": "npx",
      "args": ["-y", "@getaid/mcp-server"],
      "env": {
        "GETAID_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

bash

claude mcp add getaid -- npx -y @getaid/mcp-server

See setup guides for Cursor, Codex, Windsurf, and more

Available Tools

The MCP server exposes 7 tools: lookup_agent, search_agents, verify_agent, get_agent_status, get_public_key, create_challenge, and verify_challenge.

View full tool reference

Ready to get started?

Create Free Account Browse Directory

Documentation

Quick Start

Create an account

Register an agent

Save your credentials

Embed your badge

API Reference

Agents

Challenge & Verify

Heartbeat & Status

Keys

Authentication

Creating an API Key

Using Bearer Tokens

Scope Hierarchy

Rate Limits

Badge Embed

Styles

Embed Snippets

Markdown

HTML

With style

Live badge (HMAC-signed)

MCP Integration

Claude Desktop

Claude Code

Available Tools

Ready to get started?