API surface

The generated endpoint reference is the exhaustive inventory of the 370 operations registered by the engine. It is generated from the production Go route registrations; a route change makes the documentation check fail until the OpenAPI file is regenerated.

This page is the map: which family owns a capability, who may call it, and which guide explains the end-to-end task. It deliberately does not duplicate every method and path from the generated reference.

Authentication classes

An application credential is neither a tenant nor a platform administrator: it reaches no organization's data, and platform-admin is stripped from every token a tenant authorization server mints. Its surfaces are therefore self-scoped — the credential names the application, and no path carries an application id.

All /v1/* routes require one of these credentials except /v1/connect/start and /v1/connect/callback. /.well-known/oauth-protected-resource is also public. The engine serves no sign-in route of its own: clients authenticate against the identity provider directly and present the token here.

Capability map

The embedded console's browser-only /admin/api/* backend is intentionally not part of the public API contract. It is a same-origin BFF for the shipped console, not an integration surface.

Pagination

Inventory routes use opaque keyset cursors. Unless an endpoint says otherwise:

• omitted limit uses that surface's default;
• a value below 1, above 100, or non-integer is 400, naming the 1–100 bound;
• pass next_cursor back unchanged and do not parse, compare, or synthesize it.

Out-of-range used to clamp silently (a value above 100 truncated to 100 with no signal it happened) rather than reject. Every list surface now answers the same way: a value outside 1–100 is a 400, not a silently-truncated 200.

Some provider-backed tools use their own opaque cursor field, such as page_token. Treat it with the same opacity rule.

Strict query parameters

Every list endpoint rejects a query key outside its own accepted set with 400 {"error":{"type":"invalid_request","field":"<key>","message":"…"}} naming it, rather than ignoring it. A misspelled or misremembered parameter name is a client bug, not a silent no-op — GET /v1/admin/orgs?external_org_ref=… (the wrong name; it's ref) used to fall through to the unfiltered listing and answer with the first organization in sort order. There is no alias for a wrong name: the 400 teaches the correct one instead of quietly accepting both. Each endpoint's accepted set is its own — see that endpoint's entry in the generated reference rather than assuming every list shares the same limit/cursor pair (/v1/conversations takes limit alone; /v1/admin/orgs also takes ref and status; /v1/models, /v1/model-grants, and /v1/mcp-servers take no query parameters at all).

Conditional updates and idempotency

• Knowledge-agent policy updates return a strong ETag and require If-Match; missing is 428, stale or malformed is 412.
• Dataset and project grant writes are upserts. A create returns 201; an update or no-op repeat returns 200 and remains audited.
• Do not retry any other mutating request unless its endpoint or task guide explicitly states that replay is safe.

Idempotency-Key — supported routes

These routes read and honor Idempotency-Key; every one is also marked on its own entry in the generated reference with whether the header is required or optional there. Every other route answers 400 naming the header rather than silently accepting and ignoring it — see below.

On every route above except the application widget-data-erasure route, the same shape holds — same key and the same input is a true replay that returns the original result unchanged; same key and different input is a 409 refusal that leaves whatever the first call did untouched — but the exact 409 body and what counts as "the same input" both differ by family. Branch on type (and code, where present), not on message text.

Credit-ledger routes (POST /v1/billing/topups, POST /v1/admin/orgs/{id}/credits) compare the raw request body bytes with SHA-256:

409 {"error":{"type":"idempotency_key_reuse","message":"Idempotency-Key was already used with a different request body"}}

A successful replay also sets an Idempotent-Replayed: true response header, following Stripe's convention for telling a deduped replay apart from a fresh write. Neither route enforces a length limit on the header — only "present" is checked (required on top-ups, optional on the credit grant). Retry with the identical bytes. The comparison is over the raw body, not a canonicalized or re-parsed form of it — a re-serialized but semantically equivalent payload (different key order, different whitespace, 25000000 vs 25000000.0) is a different body and hits the 409 above. (Stripe's own idempotency check compares request parameters, not raw bytes — this engine's raw-byte comparison on these two routes is a deliberate, stricter choice.)

Widget and source routes raise a conflict carrying the same code as a distinct field, not a type of its own:

409 {"error":{"type":"conflict","code":"idempotency_key_reuse","message":"…"}}

(the message is fixed prose per resource — "widget changed or preview is no longer current" for every widget route, "this key was used for different input" for sources — not a description of what changed). Each route compares only the specific fields that decide its outcome, at most 200 bytes on the key itself: a source creation compares name; a version upload compares the file's own content and filename (never literal request bytes — the multipart boundary differs on every request even for an identical file); a version restore compares which historical version id is being restored, independent of expected_source_revision; a widget creation compares source_id/name/model; publish compares expected_revision/preview_execution_id; update-source compares expected_revision/source_version_id (the DRAFT's revision, not the widget's — see Widgets and sources); a draft message compares expected_revision/text/decision; a view compares base_execution_id/parameters. POST /v1/widgets/{id}/refresh takes no body, so a replay with the same key always matches — but the key is not scoped to this route alone. Draft open/restore, update-source, a draft message, a view and refresh share ONE receipt table per widget, so reusing a key already used for a different one of those five is still the conflict above. POST /v1/widgets (create) and .../draft/publish each keep their own separate key column and are unaffected by a key already used on any of the other five, or on each other. Each route's own entry in the generated reference states its exact comparison.

Schedule routes raise the same conflict type with no code field at all:

409 {"error":{"type":"conflict","message":"Idempotency-Key reused with a different request"}}

POST /v1/schedules compares a hash of the request body after it is parsed and re-encoded — not the literal bytes sent — so an unrelated formatting difference collapses to the same hash while a changed field does not. POST /v1/schedules/{id}/run takes no body, so a replay with the same key always matches; a key already used for a different schedule's run is the conflict above.

Sending Idempotency-Key to any other native /v1 route answers 400 naming the header — {"error":{"type":"invalid_request","field":"Idempotency-Key","message":"…"}} — instead of silently ignoring it. A retried POST /v1/datasets with the same key, for example, is not deduplicated: each call creates a new dataset, and the engine now says so up front rather than leaving that gap to be discovered by trial and error. Support for further routes is tracked on the product roadmap, not shipped.

Exception: the OpenAI-compatible (POST /v1/chat/completions) and Anthropic-compatible (POST /v1/messages, POST /v1/messages/count_tokens) routes are exempt from that 400 — a drop-in SDK or proxy targeting either dialect may attach Idempotency-Key out of habit, and the engine tolerates it there rather than breaking compatibility. Neither route deduplicates on it: each call still processes independently.

Error and correlation contract

Native routes return a typed JSON error. OpenAI- and Anthropic-compatible routes use their protocol's envelope. Common statuses are:

Every response carries an engine-generated X-Request-ID. Preserve it in support telemetry; it correlates the response with provider calls, billing, audit, conversation persistence, and structured logs.

Deliberate service boundaries

• /v1/embeddings and /v1/rerank are internal memory-service surfaces, not general tenant embedding or reranking APIs.
• /v1/billing/topups records settled payment outcomes; Deeplinq does not process the payment itself.
• /mcp exposes a read-only Deeplinq server. Tenant-registered external MCP servers are managed separately under /v1/mcp-servers/*.
• Hosted login and OAuth callback routes are browser hops. They return redirects and cookies, not API tokens in JSON bodies.