API Conventions, Errors & Limits

Start here: README · Related: Authentication · Text translation · Documents · Terminology & TM · Storage · Tenants & billing

This page is the cross-cutting reference for the TrueIdiom REST API: base URLs, credentials and the headers that carry them, JSON and datetime conventions, the complete error model, the payload limits the server enforces, and the middleware behavior that affects every request. Read it once before you write your first integration, then come back to it when you need to map a status code, size a payload, or decide how to retry.

Endpoint-specific request and response schemas live on the per-resource reference pages. Everything documented here applies to every /api/* endpoint unless an endpoint page says otherwise.

Base URLs

All API endpoints are served under the /api prefix. There is no version segment in the path — the contract is selected by the api-version query parameter instead. See Versioning.

Liveness: GET /healthz

Unauthenticated liveness probe. Reports whether the translation and quality-scoring backends are running against live credentials or in stub mode. Not under /api.

Auth required: none.

curl -s https://trueidiom.com/healthz

{
  "status": "ok",
  "stub_mode": {
    "translator": false,
    "refiner": false
  },
  "live_services": true
}

The two stub_mode flags report the same credential check and therefore always agree. Both keys are retained so the response shape does not change for existing consumers, but one credential decides both. Keep reading whichever field you already read; do not treat a disagreement between them as possible.

Errors: none. This endpoint does not fail while the process is up.

Treat live_services: false as a hard signal that translations coming out of that deployment are not real model output.

Machine-readable schema

FastAPI's generated artifacts are served at their defaults and are not disabled:

The generated document declares no securitySchemes and no global security requirement, so the interactive /docs page shows every endpoint as unauthenticated. Authentication is enforced server-side rather than declared to OpenAPI, so /docs will let you fire requests that the server rejects with 401. Use the auth rules on this page and the per-endpoint pages as the authority on what credentials an endpoint needs — not the generated docs.

The service also serves browser pages (/, /app, /signin, /billing, /jobs/{job_id}, /about, /privacy, /terms, /contact, /resources*) and a static asset mount at /static. These return HTML, not JSON, and are not part of the integration surface. They matter to an integrator in exactly one place: several billing errors direct the end user to /billing.

Authentication

Three credential types exist. Which one an endpoint accepts is stated on its reference page; this section defines the mechanics.

When both an X-API-Key header and an Authorization: Bearer header are present, X-API-Key wins for API-key resolution.

Authorization: Bearer <value> is resolved as an OAuth2 access token first. If that fails, the same value is retried as a tenant API key. A bearer token that is neither yields 401.

Optional tenant disambiguation

What each guard does

Endpoints sit behind one of four guards. The distinction matters because the same missing credential produces different statuses depending on the guard.

Tenant identity (/api/translations*, /api/documents*, /api/terminology*, /api/tm*, /api/storage/*)

• Tenant credentials are required. Missing or invalid → 401 {"detail": "missing or invalid tenant credentials"}.
• GET /api/translations/{job_id}/golden also accepts the browser session cookie, because the review page's download links are plain navigations that carry no headers.
• On a single-tenant deployment that authenticates with a single configured operator key instead of per-tenant accounts, a missing or invalid key returns 401 {"detail": "missing or invalid API key"}, and /api/terminology and /api/tm file everything under the literal tenant id default.

Admin (/api/tenants*, DELETE /api/translations/{job_id}, DELETE /api/documents/{document_id}, POST /api/oauth2/revoke, POST /api/oauth2/introspect, GET /api/auth/users, DELETE /api/auth/users/{user_id}, POST /api/auth/users/{user_id}/restore, PATCH /api/auth/users/{user_id}/role, POST /api/auth/users/{user_id}/mfa/reset, POST /api/auth/users/{user_id}/password-reset-link)

• The operator key, or an authenticated principal whose role is global_administrator.
• No usable credentials → 401 {"detail": "admin credentials required"}.
• Authenticated but not an admin → 403 {"detail": "admin role required"}.
• POST /api/tenants passes this gate and then also requires platform-operator standing (below).

Platform operator (GET /api/documents/summary with a breakdown flag, POST /api/tenants; also what widens the scope of the admin reads above)

• The operator key, or a signed-in session whose email is on the deployment's platform-operator list, that is signed in to the deployment's designated operator workspace, and that has an authenticator enrolled (all re-checked per request; it fails closed without any of them). global_administrator does not qualify — see the tenant-scoping note below.
• Authenticated non-operator → 403 {"detail": "cross-tenant breakdowns require operator access"} on the summary breakdowns, and 403 {"detail": "tenant provisioning is operator-only"} on POST /api/tenants.

Bearer-only (GET /api/auth/me)

• Requires Authorization: Bearer <access_token> specifically. A cookie session or API key is not accepted here. Missing → 401 {"detail": "missing bearer token"}.

Guard matrix — every /api operation

Public means no credential is checked; the endpoint's own inputs (a state, a challenge_id, a Stripe signature) are the proof.

Tenant scoping is not widened by the admin role

global_administrator is a per-tenant role — every tenant creator holds it. It grants admin actions inside that tenant only. Cross-tenant reads require platform-operator standing: the operator key, or a session whose email is on the deployment's platform-operator list, signed in to the deployment's designated operator workspace, with an authenticator enrolled. Neither is reachable from the API — there is no route that promotes anyone to operator.

Practically: GET /api/translations, GET /api/documents, and their detail routes filter to the caller's own tenant, and a cross-tenant id returns 404 rather than 403 so the id's existence is never confirmed.

Browser session cookie

Browser panes cannot set headers on navigations, so the server also accepts a session cookie (ll_session by default) carrying the same opaque access token. It is set HttpOnly, SameSite=Lax, Path=/, Max-Age matching the access token's lifetime, and Secure on HTTPS deployments. API clients should use headers and ignore the cookie entirely.

Request conventions

Content types

POST /api/translations is content-type-routed and accepts several shapes:

Responses are application/json except for download endpoints, which return binary or text with a Content-Disposition: attachment header:

JSON conventions

• Send only the fields documented on the endpoint pages, and validate them client-side. A misspelled optional field name will not be applied — check the returned object (request, metadata) to confirm the server received what you intended.
• Nulls are explicit in responses. Optional fields are serialized as null, not omitted. "error": null and "cell_id": null appear in real payloads.
• Enums are lowercase snake_case strings. JobStatus is one of pending, translated, refined, awaiting_review, approved, human_edited, rejected, published, failed, persistence_failed. DocumentJobStatus is one of pending, queued, extracted, translated, failed.
• Free-form metadata objects appear on requests, jobs, and tenants. They round-trip as arbitrary JSON objects. On POST /api/translations the server writes a tenant key into metadata when a tenant is resolved; do not rely on that key surviving your own writes.
• Numbers are JSON numbers. Quality scores are 0–100 floats in the text pipeline (overall_score on a document quality report is a 0–1 float — the two scales differ).

Datetimes

All timestamps are RFC 3339 / ISO 8601 in UTC, serialized with a Z suffix and microsecond precision when non-zero:

2026-07-02T00:00:00Z
2026-07-02T14:33:21.481902Z

In the OpenAPI document these fields carry "type": "string", "format": "date-time".

These exceptions serialize the same UTC instant with a +00:00 offset instead of Z — 2026-08-16T09:14:02.481902+00:00:

• created_at and updated_at on a TM import job (GET /api/tm/imports, GET /api/tm/imports/{job_id}, and the job in a 202 from POST /api/tm).
• created_at and expires_at on the invite entries stored in tenant metadata (GET /api/tenants/invites, and the invites_pending ledger on a tenant).
• created_at in the CSV usage export (GET /api/tenants/{tenant_id}/billing/export?format=csv). Its JSON and JSONL twins of the same records use Z, so the two formats of one export disagree on timestamp spelling — a CSV column and a JSON field carrying the same instant will not compare equal as strings.
• verified_at on a storage binding (GET/PUT /api/storage/binding, POST /api/storage/binding/verify).
• expires_at on an MFA challenge (the mfa_challenge object in sign-in and signup responses) and on the POST /api/oauth2/{provider}/authorize response.
• created_at on a user (GET /api/auth/users, and the user object the member-management routes return).

Parse timestamps with an RFC 3339 parser rather than by stripping a trailing Z. Both spellings denote the same instant.

Datetime query parameters (created_since, created_until on the document list and summary endpoints) accept the same format, and both bounds are inclusive. A value without an offset is read as UTC, and so is a bare date (2026-09-01), which means midnight UTC at the start of that day. Date-only parameters (since, until on GET /api/tenants/usage/daily) use YYYY-MM-DD and are inclusive on both bounds.

Identifiers

Tenant and user ids are not 32 characters. Size database columns and format assertions from this table, not from the job-id row.

Ids are opaque. Do not parse them, and do not assume a prefix. The doc_12345 / tenant_abc values in the OpenAPI examples are illustrative only, not the real format. The one id with internal structure is cell_id, whose three colon-separated parts are documented above because you must echo it back verbatim on a document correction.

Languages

Source and target languages are validated against a fixed allowlist at the API boundary:

en, es, fr, fr-CA, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id, pl, uk, cs, ro, hu, el, sv, da, nb, fi, ms, fa, ur, mr, ne

Matching is case-insensitive on the exact code (EN → en, zh-hans → zh-Hans). A code that is not in the list is rejected by design, regional tags and bare variant bases included: en-US, fr-FR, bare zh, and bare pt all fail. fr is French as written in France and fr-CA is Canadian French. source_lang defaults to en where it is optional; target_lang is always required.

A rejected code returns 422 with a string detail:

{
  "detail": "unsupported language(s): 'en-US'. Supported: en, es, fr, fr-CA, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id, pl, uk, cs, ro, hu, el, sv, da, nb, fi, ms, fa, ur, mr, ne"
}

Request and response headers

Request headers

Response headers

Correlation

The server binds request_id — and tenant_id when X-Tenant-ID is present — into its structured log context for the lifetime of the request, so every log line for one request is correlatable by that id.

The request_id field of a JSON error body is never null: it is always the same id as the response's X-Request-ID header — yours when you sent one, otherwise the server-generated 32-character hex id. Quote either when reporting a problem.

Browser origins

The API is built for server-side callers. Responses carry no cross-origin sharing headers, so a browser on a different origin will block reads of the response. Call the API from your backend, or proxy it through your own origin. The first-party web app at https://trueidiom.com/app is same-origin and unaffected.

Pagination

Pagination exists on exactly one endpoint.

GET /api/documents/{document_id}/segments

curl -s "https://trueidiom.com/api/documents/3a7d0c19b6e34f28a55c1d90ef7b2c46/segments?limit=2&offset=0&api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

{
  "total": 248,
  "flagged_total": 11,
  "limit": 2,
  "offset": 0,
  "segments": [
    {
      "index": 0,
      "page": 1,
      "target": "region",
      "region_id": "577ab4ee0485426fac76b74e22f4fdbc",
      "cell_id": null,
      "source": "Termination for cause",
      "translated": "Résiliation pour motif valable",
      "quality": {"fast_path": "tm_exact"}
    },
    {
      "index": 7,
      "page": 2,
      "target": "table_cell",
      "region_id": "9c31e0af26b4471da58f7d0c1b6e2453",
      "cell_id": "4bde2f9c1a7048e6b39d5c81f0a2e743:0:3",
      "source": "Net 30",
      "translated": "Net 30",
      "quality": {"needs_review": true, "terminology_compliant": false}
    }
  ]
}

Semantics you can rely on:

• total is the count after the flagged filter — it is what you page through.
• flagged_total counts flagged segments across the whole document regardless of the flagged filter, so you can render "N need attention" without a second request.
• index is the segment's position in the full unfiltered walk. It stays stable across filters and pages, which makes it a usable client-side key. It is not the offset within the returned array.
• A job that has not delivered a translation — still in progress, or failed — returns total: 0, flagged_total: 0, and an empty segments array — not an error.

Loop until offset + len(segments) >= total.

Errors: 401 (no tenant credentials), 404 (document job not found, including cross-tenant ids), 422 (limit outside 1..500 or negative offset).

Endpoints that return complete collections

The following return the full result set in one response, with no limit/offset/cursor parameters. Filter server-side where filters exist, and size your client buffers accordingly.

layout is always null on document job responses — the extracted layout is kept server-side (see What a job response contains). Use the segments endpoint above to page through reviewable content.

GET /api/translations and GET /api/documents both return jobs sorted by updated_at descending.

GET /api/tm/imports is the one endpoint in that table which does not return a complete collection: it is a recent-activity view of asynchronous TMX imports, sorted by created_at descending and truncated to the 50 newest jobs, with no way to page past them. Keep the job.id from the 202 if you need a specific import later.

Limits

These are the payload constraints the server enforces. A deployment can raise or lower them, so treat them as the contract's shape rather than immutable numbers.

Auth endpoint rate limiting

Authentication endpoints are rate limited per client IP per bucket. On by default: 30 attempts per 60-second window.

Buckets: signup, token-password, token-mfa and mfa-verify (both keyed additionally by challenge_id), mfa-enroll, mfa-confirm, mfa-recovery, invite-preview, password-reset, oauth-authorize, oauth-callback.

The client IP is the entry the platform's own ingress appends to X-Forwarded-For — the right-most one. Entries a client writes into the header itself are ignored, so they cannot move a request into another bucket; a request that arrives without the header is keyed on the connecting address. The same client IP keys the top-up purchase velocity limit and the per-IP free-trial grant check.

MFA codes carry two further budgets, keyed on the challenge and on the user rather than on the client IP, and enforced even when this limiter is switched off: 5 attempts per challenge, and 10 failed codes per user per 15 minutes — see Limits.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"detail": "too many requests — slow down and retry later"}

Honor Retry-After. Do not retry inside the window.

Practical sizing notes

• A single POST /api/translations runs the full pipeline inline and returns the finished job. Size your HTTP client timeout for pipeline latency, not for a queue acknowledgment: allow 120 seconds for a single-text submission and scale up with the batch size, since batch items run through the same pipeline in sequence. Do not set a 10–30 s default and treat the timeout as a failure — resend with the same Idempotency-Key instead.
• POST /api/documents/translate is asynchronous by default and returns 202 with a queued job. Send wait=true in the form to run it inline and get 200 with the completed job instead — that request holds the connection for the whole pipeline, which on a large document can run far longer than an HTTP client should wait (see the stage budget below). Keep wait=true for small documents, and submit anything larger asynchronously and poll.
• Document processing runs in stages. Extraction, translation and reconstruction each run under one server-side time budget — 1,800 s by default — that also covers the stage's automatic retries: a transient failure is retried, up to two times, only while budget remains. A stage that exhausts its budget fails the job with failure.code stage_timeout and is not retried; the stage's work is fixed by the document, so resubmitting it unchanged normally times out again.
• POST /api/tm follows the same 202-and-poll pattern once an import is large, so size its timeout for a small import only. A TMX file holding more than 5,000 segments after duplicate sources collapse returns 202 with a job to poll at GET /api/tm/imports/{job_id}; at or under it, the import runs inline and returns 200. Rejections are synchronous at both sizes, so a 202 already means the file parsed, the name was legal and the capacity check passed. See Terminology & TM.

Errors

This section is the canonical error catalog for the API. The endpoint pages list only the statuses a given endpoint can produce and the exact detail strings it uses; the body shapes, the error_code vocabulary, and the status-code semantics are defined once, here.

Error body shapes

The API returns one of three JSON shapes. All three are application/json — an unexpected internal failure included, which answers 500 in shape 3.

1. Standard error — a string detail. The common case for every explicit rejection.

{"detail": "job not found"}

2. Validation error — an array detail. Emitted by the framework for malformed path, query, header, or body parameters. Always 422.

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 500",
      "type": "less_than_equal",
      "input": "900",
      "ctx": {"le": 500}
    }
  ]
}

Gotcha: not every 422 uses this shape. Language-allowlist rejections, batch expansion failures, the storage-binding validations, the terminology/TM language and capacity rejections, and every billing request-body rejection (the tier on POST /api/billing/checkout, and a packs below 1 or of the wrong type on POST /api/billing/topup, including the raw validation message when the field is missing) return 422 with a string detail. A packs value above the per-purchase maximum is a 400, not a 422 — the ceiling is a deployment setting rather than a schema constant. Branch on the type of detail, not on the status code.

Four rejections put a stable token at the front of a string detail so you can branch without parsing prose — everything after the token is human-readable detail (counts, allowance, remediation) whose wording may change. The first two are the capacity rejections above; the third is a 409, the fourth a 401:

3. Pipeline error — detail plus error_code and request_id. Emitted when a typed pipeline exception reaches the boundary — the status comes from the exception class — and by the storage errors below and the 500 for an unexpected internal failure: {"detail": "internal error", "error_code": "internal_error", "request_id": "<id>"}.

{
  "detail": "document layout is unavailable",
  "error_code": "validation_error",
  "request_id": "b0a1f2c3d4e5f60718293a4b5c6d7e8f"
}

error_code values

transient_error and rate_limit are the retryable set. Everything else — quota_exceeded, content_filtered and stage_timeout included — indicates the request will fail the same way if replayed unchanged.

Document jobs report how they ended on failure.code rather than as an HTTP error: stage_timeout, transient_error, unexpected_error, interrupted or quota_exceeded — see DocumentFailureDetail.

Status code reference

Handling errors: worked example

curl -i -X POST "https://trueidiom.com/api/translations?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Idempotency-Key: order-4471-en-fr" \
  -H "X-Request-ID: $(uuidgen | tr -d - | tr 'A-Z' 'a-z')" \
  -H "Content-Type: application/json" \
  -d '{
        "source_text": "Payment is due within thirty days of invoice.",
        "source_lang": "en",
        "target_lang": "en-CA"
      }'

HTTP/1.1 422 Unprocessable Entity
content-type: application/json
x-request-id: 4f1c9a02b6d84e7f9c3a5e81d2704b6a

{"detail":"unsupported language(s): 'en-CA'. Supported: en, es, fr, fr-CA, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id, pl, uk, cs, ro, hu, el, sv, da, nb, fi, ms, fa, ur, mr, ne"}

Feature flags

Several capabilities are gated by deployment configuration. They are set per deployment; check GET /healthz for backend liveness and handle these statuses defensively rather than assuming a capability's state.

Auth-endpoint rate limiting is on by default at 30 attempts per 60-second window per client IP per bucket. Budget your sign-in retries accordingly.

When billing is enabled, a newly created tenant is granted a one-time free-trial allowance of source characters (150,000 by default). It covers text translation only, and only for signed-in users — layout document translation always requires an active subscription and returns 402 without one, and so does a request authenticated with the tenant API key (No API during the free trial).

Idempotency and retries

Idempotency-Key

Two endpoints honor an Idempotency-Key request header:

Keys are matched exactly and are scoped to your tenant: the same key sent by another tenant creates that tenant's own job and never returns yours, so a key only has to be unique within your tenant (a UUID, or a namespaced key like order-4471-en-fr).

On a replay, the job that already holds the key is returned as it stands:

• POST /api/translations returns the existing TranslationJob with its original id and status, without running the pipeline again — with two exceptions, both of which run it again under the same id and return the outcome:
  • a job that ended failed (for example after a 503 transient_error) is re-run;
  • a job still pending 10 minutes (by default) after its last update lost the process that was running it, and the replay re-runs it once.
• POST /api/documents/translate returns the existing DocumentTranslationJob — a failed one included; document jobs are never re-run — with status 200 (not 202) when that job has already reached translated or failed.

A replay that starts no work is answered before the billing, quota and storage gates, so it is never refused with 402, 429 or 409 storage_binding_not_verified for work that already happened — the retry of a job that took the month's last characters gets that job back. On POST /api/translations that holds when every job the request names already exists and none of them is failed or stale pending (those are re-run, so they pass the gates like new work); on POST /api/documents/translate it holds whatever the existing job's status.

Concurrent identical submissions collapse onto a single job: two requests carrying the same key race safely, and only one job is created. The later request gets the job as it stands at that moment — possibly still pending (text) or queued (documents); poll it for the outcome.

On the JSON shape of POST /api/translations you may set idempotency_key in the request body instead of the header; it is the same mechanism, and a body value takes precedence. POST /api/documents/translate is multipart and has no equivalent form field — use the header there.

Billing and idempotency

Per-job usage recording is deduplicated by job id, so an idempotent replay that returns an existing job does not record usage a second time, and does not draw the prepaid balance twice for the same work.

Only finished text work is metered. A job that ends failed is never billed, and when a keyed retry re-runs it, only the attempt that finishes is billed, once. Each item of a batch, and each page of a text document, is billed as it completes, so the items before a failing one stay billed — their translations were delivered and remain readable. A job parked as persistence_failed is billed even though the request that parked it answered 409 or 502: its translation is complete and readable through GET /api/translations/{job_id}.

Document approval is idempotent

POST /api/documents/{document_id}/approve can be called repeatedly. A second approve returns approval_result.already_approved: true with fed_pairs: 0, and approval_result.reviewer is the original approver, not the current caller.

Retry guidance

Async jobs are poll-only

There are no webhooks and no callback URL in this API. No endpoint accepts a notification target, and the server never calls out to a client. The only completion signal for an asynchronous job — document or TMX import — is polling.

Poll GET /api/documents/{document_id} until status is translated or failed. A 2-second interval is reasonable; back off to 5–10 seconds for documents over a few pages. GET /api/documents/{document_id}/download never hands back the untranslated source: it returns 409 document translation is still in progress while the job is in flight (pending, queued or extracted), and 409 document translation failed; no translated output is available once it has failed.

Large TMX imports follow the same pattern: poll the poll_url from the 202 (GET /api/tm/imports/{job_id}) until job.status is completed — job.result then holds exactly what a synchronous 200 would have returned — or failed, when job.error explains what to do. Neither terminal state is retried server-side; a failed import imported nothing and is re-run by re-uploading the file. Idempotency-Key is not honored on POST /api/tm, so guard a retry with the 409 tm_import_in_progress: answer rather than resending blindly.

(POST /api/stripe/webhook is an inbound receiver that Stripe calls — it is not a notification channel you can point at your own service.)

The service automatically retries transient upstream failures on your behalf, honoring any upstream Retry-After, so a 503 reaching you means those retries were already exhausted.

An upstream quota that stays saturated past those retries surfaces as 429 rate_limit on the synchronous endpoints, and as failure.code = "transient_error" on asynchronous document jobs (after the automatic stage retries are also spent). Both are retryable — back off further than usual, since the constraint is the deployment's throughput, not your request.

An upstream outage — server errors, timeouts, dropped connections — that outlasts those retries surfaces the same way: 503 transient_error on the synchronous endpoints, failure.code = "transient_error" on document jobs. A content-policy refusal is different: it is not retried, answers 422 content_filtered on the synchronous endpoints, and fails an asynchronous document job with failure.code = "unexpected_error".

Versioning

The API is versioned by date, supplied as a query parameter:

"https://trueidiom.com/api/translations?api-version=2026-09-01"

There is no version segment in the path. Do not construct URLs containing /v1 — those paths do not exist and return 404. If you are looking at an older internal document that describes /v1/agents, /v1/agents/{id}/runs, or /v1/auth/refresh, those endpoints are not part of this API.

Released versions

Supplying the version

When both are sent, the query parameter wins — the same direction as X-API-Key beating Authorization.

Every versioned response echoes the version it was served as:

HTTP/1.1 200 OK
X-Request-ID: 4f1c9a02b6d84e7f9c3a5e81d2704b6a
X-Api-Version: 2026-09-01

If you are not sure what a caller is actually pinned to, read that header rather than inferring it from the request.

The parameter is optional

Omitting it is legal and serves the oldest supported version — today, 2026-09-01. It never means "latest".

That is a deliberate guarantee: an unversioned integration written today keeps receiving today's contract after new versions ship. Silently re-pointing unversioned callers at a newer version is the one change guaranteed to break existing integrations, and this API will not make it.

Send the parameter anyway. An explicit pin is what lets you upgrade on your own schedule instead of on the deprecation clock, and it makes your integration visible in adoption telemetry when a version is being retired.

Unknown versions are rejected, not rounded

A pin that is not a released version returns 400 — including a well-formed date that has not shipped:

curl -sS "https://trueidiom.com/api/translations?api-version=2027-01-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

{"detail": "unknown api-version: '2027-01-01' is not a released version. Supported: 2026-09-01"}

A malformed value (v1, 2026/09/01, an empty string) returns 400 with unsupported api-version: ... and the same supported list. Both messages name every released version, so a broken pin is fixable from the error alone.

Rounding an unknown date to the nearest release would let a client pinned ahead of a deploy silently ride a contract it was never written against. Failing is the safer default.

Endpoints that take no version

These ignore the parameter entirely and emit no X-Api-Version. Sending one is harmless.

Note also that GET /api/translations/{job_id}/golden is frequently opened as a plain browser link, which carries no parameter. Because the pin is optional, those links keep working.

What lands in a new version, and what does not

Additive changes ship inside the current version — they do not get a new date:

• New optional response fields. Parse defensively: ignore unknown fields rather than failing on them, and never depend on JSON key ordering.
• New optional request fields. Pin your integration to the fields documented on the endpoint pages, and assert on the returned object rather than assuming a field you sent was applied.
• New endpoints, and relaxed validation.
• New enum members. JobStatus and DocumentJobStatus can gain values within a version. Treat an unfamiliar status as "not one I handle" rather than as a parse failure — a strict client that throws on an unknown enum will break without a version change to warn it.

A new version date is minted only for a breaking change: removing or renaming a field, tightening validation, changing a status code, or changing a default.

Deprecation policy

No version is deprecated today — there is only one, and nothing emits deprecation headers yet.

The policy for when that changes: at most two versions run concurrently, with at least six months of overlap, and requests pinned to a retiring version will carry Deprecation: true and Sunset: <HTTP-date> (RFC 8594) alongside the normal response for the whole overlap window. Watch for those two headers rather than for an announcement.

Machine-readable schema

GET /openapi.json declares api-version as an optional query parameter (and X-Api-Version as an optional header) on every operation that accepts it, so a generated client exposes the pin without hand-editing.

That document's own info.version reads 2026-09-01, matching the API version it describes. It is a static property of the published document, not a negotiation mechanism: it does not vary per request, and it is not what pins a call. Pin with the api-version query parameter, and read the version a request was actually served as off the X-Api-Version response header.

Diffing GET /openapi.json between deploys remains the most reliable signal that the surface changed.