Skip to main content

​
Endpoints

  • POST /v1/rpc for request and response.
  • GET /v1/ws (WebSocket upgrade) for subscriptions.
Two unauthenticated process probes sit outside the API: GET /healthz (process alive) and GET /readyz (runtime ready). The authenticated health.* methods are separate.

​
Authentication

Send a bearer token on every HTTP request and on the WebSocket upgrade:
In v1, token presence and validity are the only check; a valid token grants every scope. Scopes are declared per method for forward compatibility but are not enforced yet. A WebSocket token is checked once, at the upgrade, and not re-checked for the life of the connection. So rotating or revoking a token does not close streams that are already open; to pick up a new token, reconnect.

​
Request and response envelope

Branch on data.code (a string, e.g. BUNDLE_MISMATCH), not on the numeric JSON-RPC code. data also carries details (per-code structured fields), retryable (a boolean), and correlation_id.

​
Pagination

List methods are cursor-based: pass limit (default 50, max 500 unless a method overrides it) and cursor (omitted for the first page); the response returns next_cursor when more pages exist. Offset pagination is not supported.

​
Idempotency

Mutating methods accept an optional idempotency_key. The runtime stores the response keyed by (method, token, key) for 24 hours. Replaying with the same key and body returns the stored response; the same key with a different body returns IDEMPOTENCY_CONFLICT.

​
Versioning

The surface is under /v1/. Additive changes (new optional fields, new methods, new error codes) stay in /v1/; breaking changes bump to /v2/. A deprecated /v1/ method stays functional for at least one minor spec revision.