API Documentation

Machine-readable endpoints for AI agents, bots, and developers. All endpoints support CORS and return structured JSON or JSON-LD.

Quick Reference

Format:JSON / JSON-LD

Auth:Bearer token (optional for public endpoints)

CORS:Enabled (*)

GET/.well-known/brand-capsule.jsonJSON-LD

JSON-LD registry of all verified Brand Capsules. Machine-discoverable endpoint following the .well-known URI convention.

Example Request

curl https://your-domain/.well-known/brand-capsule.json

Example Response

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "RegisteredBrands.AI — Verified Brand Capsule Registry",
  "numberOfItems": 42,
  "itemListElement": [{
    "@type": "ListItem",
    "item": {
      "@type": "Brand",
      "@id": "urn:registeredbrands:capsule:cap_7xK9mN2pQ4wR",
      "name": "Acme Corp",
      "identifier": [
        { "propertyID": "DUNS", "value": "123456789" }
      ],
      "additionalProperty": [
        { "propertyID": "trustScore", "value": 87500 }
      ]
    }
  }]
}

GET/.well-known/agent.jsonA2A

A2A Agent Card for agent-to-agent protocol discovery. Describes capabilities, endpoints, and authentication requirements.

Example Request

curl https://your-domain/.well-known/agent.json

Example Response

{
  "name": "RegisteredBrands.AI Verification Agent",
  "capabilities": ["brand-verification", "trust-score-lookup"],
  "endpoints": {
    "verify": "/api/v1/verify",
    "search": "/api/v1/capsules/search"
  }
}

POST/api/v1/verifyRFC 9421

RFC 9421 HTTP signature verification endpoint. Submit a capsuleId to verify brand authenticity with cryptographic proof.

Example Request

curl -X POST https://your-domain/api/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"capsuleId": "cap_7xK9mN2pQ4wR"}'

Example Response

{
  "verified": true,
  "capsuleId": "cap_7xK9mN2pQ4wR",
  "brandName": "Acme Corp",
  "trustScore": 87500,
  "maxTrustScore": 100000,
  "dunsVerified": true,
  "protocol": "rfc9421"
}

GET/api/v1/capsules/:capsuleIdREST / JSON-LD

Retrieve a single Brand Capsule in JSON-LD format. Returns full Schema.org structured data for the specified brand.

Example Request

curl https://your-domain/api/v1/capsules/cap_7xK9mN2pQ4wR

Example Response

{
  "@context": "https://schema.org",
  "@type": "Brand",
  "name": "Acme Corp",
  "identifier": [...],
  "additionalProperty": [
    { "propertyID": "trustScore", "value": 87500 }
  ]
}

GET/api/v1/capsules/searchREST

Search the capsule registry by brand name, capsule ID, DUNS number, status, or trust score range.

Example Request

curl "https://your-domain/api/v1/capsules/search?q=acme&status=verified&minScore=50000"

Example Response

{
  "results": [...],
  "total": 3,
  "limit": 50,
  "offset": 0
}

POST/api/v1/badges/verifyREST

Verify a Distributor Badge Key token. Returns validity, permissions, issuing brand, and delegation chain.

Example Request

curl -X POST https://your-domain/api/v1/badges/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "abc123..."}'

Example Response

{
  "valid": true,
  "badge": {
    "keyId": "bk_xYz123",
    "permissions": ["read", "verify", "transact"]
  },
  "brand": {
    "capsuleId": "cap_7xK9mN2pQ4wR",
    "trustScore": 87500
  }
}

POST/api/v1/protocol/a2aA2A

Agent2Agent protocol endpoint. Supports verify-brand and search-brands tasks for inter-agent communication.

Example Request

curl -X POST https://your-domain/api/v1/protocol/a2a \
  -H "Content-Type: application/json" \
  -d '{"task": "verify-brand", "message": {"capsuleId": "cap_7xK9mN2pQ4wR"}}'

Example Response

{
  "status": "completed",
  "result": {
    "verified": true,
    "brandName": "Acme Corp",
    "trustScore": 87500
  }
}

POST/api/v1/protocol/tapTAP

Trusted Agent Protocol compatible endpoint. Verifies brand identity for payment-related agent transactions.

Example Request

curl -X POST https://your-domain/api/v1/protocol/tap \
  -H "Content-Type: application/json" \
  -d '{"capsuleId": "cap_7xK9mN2pQ4wR", "action": "verify"}'

Example Response

{
  "protocol": "tap",
  "verified": true,
  "brandIdentity": {
    "capsuleId": "cap_7xK9mN2pQ4wR",
    "trustScore": 87500
  },
  "agentAuthorization": {
    "authorized": true
  }
}

GET/api/v1/protocol/ucpUCP

Universal Commerce Protocol compatible brand registry. Returns verified brand catalog for agentic commerce agents.

Example Request

curl https://your-domain/api/v1/protocol/ucp

Example Response

{
  "protocol": "ucp",
  "catalog": {
    "type": "brand-registry",
    "totalBrands": 42,
    "brands": [...]
  }
}