API surface

The generated endpoint reference is the exhaustive inventory of the 314 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 only

Exactly two routes read and honor Idempotency-Key today, both backed by the same credit ledger:

• POST /v1/billing/topups — the key is required; missing is 400.
• POST /v1/admin/orgs/{id}/credits — the key is optional; omitted means every call credits.

On either route:

• Same key, same request body (the engine hashes the raw body bytes with SHA-256 to compare) — a true replay. The original result is returned again, unchanged, with an Idempotent-Replayed: true response header. This follows Stripe's convention for telling a deduped replay apart from a fresh write.
• Same key, a different request body — 409 {"error":{"type":"idempotency_key_reuse","message":"…"}}. The original grant is untouched; the retry is refused rather than silently discarded.

Retry with the identical bytes. The comparison is over the raw request body, not a canonicalized or re-parsed form of it — so a re-serialized but semantically equivalent payload (different key order, different whitespace, 25000000 vs 25000000.0) is treated as a different body and hits the 409 above. Send back the exact bytes of the original request, not a JSON-library re-encoding of the same values. (Stripe's own idempotency check compares request parameters, not raw bytes — this engine's raw-byte comparison is a deliberate, stricter choice, not an oversight.)

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.