AY Developer docs

Rate limits

Request budgets per endpoint, and the headers that tell you where you stand.

Limits are counted per client IP for public endpoints and per account for owner endpoints. A request over the limit returns 429 with Retry-After and X-RateLimit-* headers.

Owner endpoints

EndpointLimit
POST /api/v1/agents5 per hour
POST /api/v1/agents/{id}/attest10 per 10 minutes
POST /api/v1/agents/{id}/keys/rotate10 per 10 minutes
POST /api/v1/agents/{id}/credentials/rotate5 per hour
GET /api/v1/agents, `GETPATCH

Agent endpoints

EndpointLimit
GET /api/v1/agents/meNo dedicated limit
POST /api/v1/agents/me/keys/rotate/challenge, POST /api/v1/agents/me/keys/rotate10 per 10 minutes, and 60 per minute

Public identity endpoints

All 30 per minute per IP:

  • GET /api/v1/identity/resolve
  • POST /api/v1/identity/verify
  • POST /api/v1/identity/credentials/verify
  • GET /api/v1/identity/status-list, GET /api/v1/identity/status-list/businesses
  • /.well-known/did.json, /.well-known/did.jsonl
  • /twins/{id}/did.json, /twins/{id}/did.jsonl, /users/{id}/…, /agents/{id}/…
  • /agents/{id}/.well-known/agent.json

Limits that are not rate limits

LimitValue
Active agents per account10
Attestation and rotation challenge validity10 minutes
Signature age300 seconds, 60 seconds skew
Nonce memory360 seconds per key
Request body of a signed call to a twin inbox256 KiB, 15 seconds

Caching

ResourceCache-Control
DID documents and logsmax-age=3600, ETag
Agent Cardmax-age=300, ETag
GET /api/v1/identity/resolvemax-age=60, ETag

Send If-None-Match to save the budget: a 304 costs nothing on your side.

Errors

Every error code of the agent and identity API, with its status, its reason values, and what to do.

Test vectors

Real signed requests for all three signature contexts, a signed twin mandate, and reference verifiers in Python.

On this page

Owner endpointsAgent endpointsPublic identity endpointsLimits that are not rate limitsCaching