API reference

#Base URL

https://immiscible.fly.dev

Self-hosted deployments use their own PUBLIC_URL. All requests and responses are JSON (application/json; charset=utf-8) unless an endpoint says otherwise: the OCSF export is NDJSON, the Shared Signals receiver takes application/secevent+jwt, and a few browser routes redirect.

#The surfaces

The full list, grouped, is on all endpoints.

The API is also published as OpenAPI 3.1 at https://immiscible.fly.dev/openapi.json: the gate’s public operations (ask, check, be called back, settle, verify), the gateway and machine admin are written out in full, and the rest of the public surface (the CLI, MCP, SCIM, the well-known documents and health checks) is generated from the router like this reference, with a link to its page and a schema read from its documented example. The console’s own /api/* routes, sign-in pages and signed callbacks are left out: they are not the surface to build on, and may change. They are listed, marked x-internal: true, at https://immiscible.fly.dev/openapi.json?include=internal. See agent builders.

#Conventions

• Ids are prefixed by kind: ws_ workspace, agt_ agent, mdt_ mandate, act_ action, apr_ approval, mcu_ MCP upstream, stk_ service token.
• Money is an integer in minor units of its currency: 4200 is £42.00. Workspace-wide lines (tiers, the chat line) are in reference pence and converted.
• Times are ISO 8601 in UTC; signed tokens use seconds since the epoch.
• Idempotency. Action requests take an idempotencyKey (or the idempotency-key header). A retry with the same key and body gets the same answer; the same key with a different body is 409 idempotency_conflict.
• Tracing. Send a W3C traceparent and it is continued; every response returns one. See traces.
• Lists return { "data": [...] }. Endpoints that page take limit (and since, until where time matters).

#Decisions are not errors

An action that is refused is 200 with "decision": "deny"; one that needs a person is 200 with "decision": "approval_required". HTTP errors are for requests that could not be evaluated. See decisions and errors.

#Rate limits

Limits are per key, per agent, per address for public routes, and per card on the card rail. A limited request is 429 rate_limited with a retry-after header in seconds; honour it.

#CORS

Gateway, gate and OAuth routes allow any origin, because they authenticate with a key, never a cookie. Console routes allow none.

#How this reference is built

The server reads its own router once every route is registered, classifies each route’s authentication from its path, works out its parameters, and renders a page per endpoint. Descriptions, request and response examples are merged in from Markdown files kept beside the server’s source (the server is not open source; the SDKs and the CLI are, at efr7-7/immiscible-sdks). A route without a written description still appears, marked as generated, so nothing the server answers is missing from this reference.