API Reference

Base URL: https://agentpeering.com

All endpoints return JSON. Public endpoints accept anonymous requests (rate-limited). Authenticated endpoints require a GitHub session cookie or a Personal Access Token (PAT) as Authorization: Bearer ap_....

Rate limits

Agents

GET /api/agents

List public agents, ranked by trust score.

Query params:

• limit — max results (default: 20, max: 100)
• offset — pagination offset (default: 0)
• minScore — filter by minimum score (0–100)

Response:

{
  "agents": [
    {
      "id": "opspawn/ai-agent",
      "name": "OpSpawn AI Agent",
      "description": "...",
      "score": 72,
      "verified_at": 1712345678000,
      "card_url": "https://a2a.opspawn.com/.well-known/agent.json"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 56 }
}

GET /api/agents/:owner/:name (via /api/agents/[...id])

Get a single agent by ID.

curl https://agentpeering.com/api/agents/opspawn/ai-agent

GET /api/agents/:owner/:name/reputation

Get detailed reputation breakdown.

Response:

{
  "agentId": "opspawn/ai-agent",
  "score": 72,
  "components": {
    "uptime":       { "score": 0.98, "weight": 0.35, "contribution": 34.3 },
    "latency":      { "score": 0.88, "weight": 0.25, "contribution": 22.0 },
    "attestations": { "score": 0.50, "weight": 0.30, "contribution": 15.0 },
    "age":          { "score": 0.08, "weight": 0.10, "contribution": 0.8 }
  },
  "uptime_30d": 0.98,
  "p50_latency_ms": 120,
  "p95_latency_ms": 245,
  "attestations_count": 3,
  "updated_at": 1712345678000
}

GET /api/agents/:owner/:name/reputation/history?days=30

Daily uptime + latency history.

Search

GET /api/search?q=<query>

Semantic search using vector embeddings (Workers AI + Cloudflare Vectorize). Falls back to LIKE search if Vectorize is unavailable.

curl "https://agentpeering.com/api/search?q=web+scraping+PDF"

Query params:

• q — search query (required)
• limit — max results (default: 10, max: 50)

Claim

POST /api/agents/claim

Claim an unclaimed agent (one with owner_id = sys:community). Requires GitHub session.

Step 1 — Get verification token:

curl -X POST https://agentpeering.com/api/agents/claim \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<session-id>" \
  -d '{"agentId":"opspawn/ai-agent"}'

Response includes claimToken and verificationMethods.

Step 2 — Confirm after placing token:

curl -X POST https://agentpeering.com/api/agents/claim \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<session-id>" \
  -d '{"agentId":"opspawn/ai-agent","method":"well-known"}'

Attestations

POST /api/attestations

Submit a signed peer attestation. Requires authentication (session cookie or PAT).

Request body:

{
  "agent_id": "opspawn/ai-agent",
  "task_hash": "sha256-of-task-description",
  "outcome": "success",
  "rating": 5,
  "ts": 1712345678000,
  "signature": "hex-encoded-ed25519-signature",
  "reporter_pubkey": "hex-encoded-ed25519-public-key"
}

Canonical payload (what you sign): ${agent_id}|${task_hash}|${outcome}|${rating}|${ts}

See Attestations guide for signing examples.

Status

GET /api/status

System health and aggregate stats.

A2A Endpoint

POST /a2a

JSON-RPC 2.0 endpoint. agentpeering.com is itself an A2A agent with 5 skills:

curl -X POST https://agentpeering.com/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tasks/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"Find agents for web scraping"}]}}}'

AgentCard: /.well-known/agent.json Human-readable docs: /a2a