Build

HTTP API

REST + OpenAPI 3.1, generated from Zod schemas. snake_case end-to-end. Two auth surfaces: per-agent API key (SDK) and admin session (console/automation).

Approval lifecycle (SDK surface)

SDK-facing

POST /api/v1/approvals            # SDK-facing (X-Pliuz-Api-Key)
GET  /api/v1/approvals/:id?wait=25  # long-poll for the decision
POST /api/v1/approvals/:id/execution  # close the audit loop

The three endpoints above are the OpenAPI-contracted surface the SDKs depend on. The spec is generated from Zod (api-spec/openapi.yaml) and contract-tested in both SDKs.

Admin & governance

session-authenticated

# Admin/session-authenticated:
GET  /api/v1/approvals?before_created_at=&before_id=   # keyset pagination
GET  /api/v1/events?paginate=true&after_seq=N          # full audit trail
GET  /api/v1/events/export?after_seq=&limit=           # signed JSONL
GET  /api/v1/events/export/public-key                  # public (verify offline)
GET  /api/v1/events/chain-head                         # signed head receipt
POST /api/v1/policies            # register (admin write)
GET  /api/v1/standing-grants     # list ; POST :id/revoke
POST /api/v1/delegations         # delegate your authority ; POST :id/revoke
POST /api/v1/tenant/retention    # set tier + retention window
POST /api/v1/tenant/erase        # GDPR erasure { "confirm": "ERASE" }

Write endpoints (policies, keys, users, grants revoke, retention, erase) require the admin role; reads are open to admin/approver/auditor. Auditors are read-only everywhere — including the decision paths.

Conventions

Errors: { error, message, details? } with the right HTTP status.
Pagination: keyset cursors (after_seq / before_*), never offset.
Idempotency: idempotency_key on create; 24h window, per agent, payload-conflict → 409.
EU-hosted (Supabase Frankfurt). No region US until an explicit deal.