API Reference

Base URL: https://dir.beam.directory (managed) or your self-hosted instance on http://localhost:3100.

All endpoints return JSON. Errors: {"error": "Human-readable message"}

Authentication

Read-only endpoints are public. Write operations require an API key:

Authorization: Bearer <your-api-key>

POST/agents/register

Register a new agent or update an existing one.

Request body

{
  "beamId":       "jarvis@coppen.beam.directory",
  "displayName":  "Jarvis",
  "capabilities": ["query", "answer", "write"],
  "publicKey":    "<SPKI DER base64>",
  "org":          "coppen"
}

Response 200

{
  "beamId":       "jarvis@coppen.beam.directory",
  "displayName":  "Jarvis",
  "capabilities": ["query", "answer", "write"],
  "publicKey":    "<SPKI DER base64>",
  "org":          "coppen",
  "trustScore":   0.5,
  "verified":     false,
  "createdAt":    "2026-03-04T00:00:00Z",
  "lastSeen":     "2026-03-04T00:00:00Z"
}

GET/agents/:beamId

Look up an agent by Beam ID. The Beam ID must be URL-encoded.

Response 404: {"error": "Agent not found"}

GET/agents/search

Search agents by org, capability, or trust score.

GET /agents/search?org=coppen&capabilities=query&minTrustScore=0.7

Response 200

{ "agents": [ { "beamId": "jarvis@coppen.beam.directory", ... } ] }

POST/agents/:beamId/heartbeat

Update the agent's lastSeen timestamp. Call every 30–60 seconds. Returns 204 No Content.

POST/intents/send

Route a signed IntentFrame to its destination agent.

Request body

{
  "v":         "1",
  "intent":    "query",
  "from":      "jarvis@coppen.beam.directory",
  "to":        "clara@coppen.beam.directory",
  "params":    { "q": "Pipeline status?" },
  "nonce":     "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-04T12:00:00Z",
  "signature": "<Ed25519 base64>"
}

Response 200

{
  "v":         "1",
  "success":   true,
  "payload":   { "status": "green", "deals": 42 },
  "nonce":     "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-04T12:00:00.047Z",
  "latency":   47
}

GET/health

{ "status": "ok", "version": "0.1.0", "agents": 42, "uptime": 86400 }

Rate Limits

Self-hosting

npx @beam-protocol/directory
# or
docker run -p 3100:3100 ghcr.io/beam-directory/directory:latest