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"}.
• 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, 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"}.

Platform operator (GET /api/documents/summary with a breakdown flag; 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 and who has an authenticator enrolled (both re-checked per request; it fails closed without the enrolment). global_administrator does not qualify — see the tenant-scoping note below.
• Authenticated non-operator → 403 {"detail": "cross-tenant breakdowns require operator access"}.

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 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".

Three 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}).
• 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.

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. 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, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id

Matching is case-insensitive on the exact code (EN → en, zh-hans → zh-Hans). Regional subtags and bare variant bases are rejected by design: en-US, fr-CA, bare zh, and bare pt all fail. 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, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id"
}

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.

Gotcha: the JSON request_id field inside pipeline error bodies is read from the inbound X-Request-ID header. If you do not send one, the response header carries a generated id but the JSON field is null. Send your own X-Request-ID if you want the two to agree.

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 whose layout has not been produced yet 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 (keyed additionally by challenge_id), mfa-enroll, mfa-confirm, mfa-recovery, invite-preview, password-reset, oauth-authorize, oauth-callback.

The client IP is taken from the first entry of X-Forwarded-For when present, otherwise the socket peer.

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 can run for minutes on a large document, so allow at least 480 s — four times the per-stage budget — before giving up on it.
• Document processing runs in stages, each with a server-side budget of 120 s and up to two automatic retries. A stage that exhausts its budget surfaces as a stage_timeout failure on the job.
• 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.

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 capacity rejections, and every billing request-body rejection (the tier on POST /api/billing/checkout and the packs on POST /api/billing/topup, including the raw validation message when the field is missing or of the wrong type) return 422 with a string detail. Branch on the type of detail, not on the status code.

Three 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:

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.

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

error_code values

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

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, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id"}

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 — layout document translation always requires an active subscription and returns 402 without one.

Idempotency and retries

Idempotency-Key

Two endpoints honor an Idempotency-Key request header:

Keys are matched exactly and are scoped to the job store, not to your tenant — use a value with enough entropy to be globally unique (a UUID, or a namespaced key like order-4471-en-fr).

On a replay, the original job is returned, and the pipeline does not run again:

• POST /api/translations returns the existing TranslationJob with its original id and status.
• POST /api/documents/translate returns the existing DocumentTranslationJob, with status 200 (not 202) when that job has already reached translated or failed.

Concurrent identical submissions collapse onto a single job: two requests carrying the same key race safely, and only one job is created.

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.

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 returns 409 document translation is still in progress while the job is queued rather than handing back untranslated source.

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.

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.