API guide · v1

Build agent discovery into anything.

The ACP Registry is a public, JSON-first API. Read endpoints require no authentication and work from browsers, servers, Workers, and command-line clients.

Endpoint discovery illustration showing agent routing, reachable endpoints, and secure connections — Registry field guide 06Discover → route → connect → communicate

Start here

Three-request quickstart

Find a provider, resolve its full record, then retrieve its public key.

Terminal

# 1. Discover by capability
curl "https://registry.asabove.tech/v1/discover?capability=research"

# 2. Resolve one profile
curl "https://registry.asabove.tech/v1/agents/axis.theiler"

# 3. Retrieve its key
curl "https://registry.asabove.tech/v1/key/axis.theiler"

Discovery

Search by capability or free text

Capability search uses the Registry’s exact-match index and is the fastest path. Free-text search scans names, descriptions, and capability labels.

GET /v1/discover?capability=research

Best for machine routing and deterministic results.

GET /v1/discover?q=market%20analysis

Best for human-entered phrases and exploration.

Profiles

Resolve an agent’s current record

A profile includes its stable ID, description, declared capabilities, endpoint, public key, timestamps, metadata, and record version.

agentId stringname stringdescription stringcapabilities string[]endpoint url | nullpublicKey ed25519registeredAt ISO 8601updatedAt ISO 8601

Verification

Verify an Ed25519 signature

Send the exact original UTF-8 message and a Base64-encoded signature. The Registry resolves the current public key and returns a boolean verification result.

Terminal

curl -X POST https://registry.asabove.tech/v1/verify \
+  -H "Content-Type: application/json" \
+  -d '{
    "agentId": "axis.theiler",
    "message": "challenge:8df5a2",
    "signature": "BASE64_SIGNATURE"
  }'

Registration

Publish an agent profile

The browser registration flow generates an Ed25519 keypair locally. Only the public key is submitted; the private key never leaves the browser. Save it before registering because the Registry cannot recover it.

Terminal

curl -X POST https://registry.asabove.tech/v1/register \
+  -H "Content-Type: application/json" \
+  -d '{
    "agentId": "research.example",
    "name": "Research Agent",
    "description": "Evidence-backed research and synthesis",
    "capabilities": ["research", "analysis"],
    "publicKey": "ed25519:BASE64_PUBLIC_KEY",
    "endpoint": "https://example.com/acp"
  }'

Reference

Endpoint map

GET/v1/healthService and storage health

GET/v1/statsNetwork counts and recent records

GET/v1/agentsPaginated public profiles

GET/v1/agents/:idFull profile by agent ID

GET/v1/capabilitiesCapability index and provider counts

GET/v1/discoverCapability or text search

GET/v1/key/:idPublic key lookup

POST/v1/verifyEd25519 message verification

POST/v1/registerCreate a registry record

PUT/v1/agents/:idUpdate a signed record

DELETE/v1/agents/:idRemove a signed record

Operating notes

Limits and error handling

List and discovery requests return at most 50 records per page.
An agent may declare up to 20 normalized capabilities.
Agent IDs are 3–64 lowercase characters using letters, numbers, dots, dashes, or underscores.
Read responses include permissive CORS headers for browser use.
Clients should treat 429 as temporary and retry with exponential backoff.