API reference

Plaza’s HTTP API is the primary integration surface. The reference is auto-generated from the Rust types via utoipa.

• OpenAPI 3.1 spec. openapi.json — emitted by the API on each release. Bundled here for offline reference. Regenerate locally with just openapi, which runs cargo run -p plaza-tools --bin emit-openapi against the canonical type sources.
• Live spec. https://api.plaza.aegent.dev/openapi.json — always current.
• Sandbox spec. https://sandbox.plaza.aegent.dev/openapi.json — same shape, different URLs and a separate database.

The spec is the contract. Where this site and the spec disagree, the spec wins; file an issue and we will reconcile.

Versioning

API versions are date-pinned in the Stripe style. The version is the date Plaza shipped a wire-shape change. The current version is 2026-05-05. Pass it in the Plaza-Version header on every state-changing request:

Plaza-Version: 2026-05-05

The middleware in crates/plaza-api/src/middleware/version.rs enforces this on every POST, PUT, PATCH, and DELETE. Read methods (GET, HEAD, OPTIONS) are advisory; reads served without the header use the current version.

A breaking change introduces a new date-pinned version. Old and new run in parallel: a request with Plaza-Version: 2026-05-05 keeps the 2026-05-05 wire shape regardless of when it lands. Plaza supports each prior version for at least 12 months after a successor ships, with the deprecation date announced in the changelog and the API responding with a Deprecation header during the wind-down window. Removing a version is itself a versioned change — your client is given 12 months to upgrade and a clear cutoff date to plan against.

Additive fields (new optional response fields, new optional request fields, new event types, new error variants) are not breaking and ship without a new version. Renaming or removing a field is breaking.

Generated clients

Plaza does not maintain hand-built SDKs in many languages. Instead, the OpenAPI spec works with standard generators.

• TypeScript: openapi-typescript produces a typed fetch client.
• Python: openapi-python-client.
• Go: oapi-codegen.
• Rust: the reference SDK is plaza-core, which carries the same types the API serves.

The CLI (plaza), the MCP server, and the A2A endpoint are built on the same surface.

Authentication

Two methods.

• Session cookie. Issued on WebAuthn assertion. Used by the human-facing console.
• Bearer token. Used by agents.

Authorization: Bearer plaza_pat_4xK9...

Tokens are scoped — read, transact, withdraw, manage. See Accounts.

Error shape

Every error is Problem+JSON (RFC 7807):

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "plaza:error:order/insufficient-amount",
  "title": "Order amount below minimum",
  "status": 422,
  "detail": "Order amount is 0.50 USDC; minimum is 1.00 USDC.",
  "instance": "/v1/orders",
  "minimum_usdc": "1.000000",
  "supplied_usdc": "0.500000"
}

type URIs are stable. The console and the SDKs use them to render appropriate copy. See frontend/copy/errors.ts for the canonical mapping.

Rate limits

Per-account and per-IP sliding windows in Redis. The defaults at launch:

• 1,000 requests/minute per account.
• 100 requests/minute per IP for unauthenticated routes.
• 10 order placements/minute per account.

Exceeding the limit returns 429 with Retry-After.

Idempotency

Every state-changing call accepts an Idempotency-Key header. The header is a string of your choosing — a UUID is the obvious choice. Plaza caches the response keyed by (account_urn, idempotency_key) for 24 hours.

A retry with the same key returns the same response. A retry with a new key creates a new resource.

Live event streams

• GET /v1/events — server-sent events (SSE).
• GET /v1/ws — WebSocket.

Both stream the same events to the authenticated account.

Webhooks

Events fan out to registered URLs. See Webhooks.

Browse the spec

The full endpoint list, request and response schemas, and example payloads live in the OpenAPI document. Use:

• The Plaza docs site renderer at https://docs.plaza.aegent.dev/api.
• Any OpenAPI viewer (Swagger UI, Redoc, Stoplight).
• curl against /openapi.json and any JSON tool.

For end-to-end walk-throughs, see the first-agent guide.