Document Translation

Start here: README · Related: Authentication · Conventions & errors · Text translation · Storage

The document endpoints translate PDF, DOCX and XLSX files in place — the original layout, pagination, tables and styling are preserved, and only the text is replaced. Submission is asynchronous by default: you upload a file, receive a job, poll it to completion, then optionally walk the document's segments, post human corrections, approve, and download the translated file. Use this page when you need the source file back in its original format; for plain-text or batch string translation use the text endpoints (POST /api/translations).

• Base URL (production): https://trueidiom.com
• Path prefix: /api
• API version: ?api-version=2026-09-01 — optional; omitting it serves the oldest supported version. X-Api-Version: 2026-09-01 is an accepted alias for the query parameter, which wins when both are sent, and a pin naming a version that has not been released is rejected with 400 naming the supported set. Full contract: Versioning

Authentication

These endpoints are published in the OpenAPI document served at /openapi.json. The generated document declares no securitySchemes and no global security requirement, so the interactive /docs page shows every endpoint as unauthenticated. They are not: auth is enforced server-side, and every endpoint on this page requires tenant credentials.

Send credentials in one of two ways:

Every curl example on this page uses $TRUEIDIOM_API_KEY for a tenant API key. If you do not have one yet:

export TRUEIDIOM_API_KEY=$(curl -sS -X POST "https://trueidiom.com/api/auth/signup/email?api-version=2026-09-01" \
  -H "Content-Type: application/json" \
  -d '{"tenant_name":"Acme Legal","email":"you@example.com","password":"correct-horse-battery-staple"}' \
  | jq -r .tenant_api_key)

Use the session access token instead when you want the reviewer identity on /review and /approve derived server-side rather than declared in the body.

Without usable credentials every endpoint below returns 401:

{ "detail": "missing or invalid tenant credentials" }

On deployments that run with a single global operator key and no tenant accounts, the same 401 reads {"detail": "missing or invalid API key"}.

Tenant scoping. Reads are scoped to the calling tenant. A document belonging to another tenant returns 404 document job not found — never 403 — so document ids are not confirmed to callers who may not see them. The global_administrator role does not widen this; it is a per-tenant admin role. Only the platform operator API key or a designated platform-operator session sees across tenants.

Reviewer identity. For /review and /approve, the server derives the reviewer from the authenticated session (email, falling back to user id) and that value wins over any reviewer field in the request body. A client-supplied reviewer is only honoured when no session can be resolved (API-key-only clients). See Reviewer identity.

Every response carries an X-Request-ID header. Send your own X-Request-ID to correlate with server logs.

The job model

A document upload creates a document translation job (TenantDocumentJob) that moves through these statuses:

status only becomes translated after the translated output artifact is registered, so a poller that sees translated can download the translated file immediately.

POST /api/documents/translate
        │
        ├── wait=true  ── runs inline ──┐
        │                               │
        └── default ──► queued ─────────┤
                          │  (poll GET /api/documents/{id} — there are no webhooks)
                          ▼             │
                      extracted ────────┤
                          │             │
              ┌───────────┴─────────────┴───────────┐
              ▼                                     ▼
          translated                             failed
              │                                (failure.code:
              │                                 stage_timeout | transient_error
              │                                 | unexpected_error | interrupted
              │                                 | quota_exceeded)
              ├──► GET  .../download          ← available now, and after every re-render
              ├──► GET  .../segments?flagged=true
              ├──► POST .../review     (repeatable; re-renders; status unchanged)
              └──► POST .../approve    (idempotent; stamps approved_at/approved_by;
                                        feeds the golden translation memory)

Neither review nor approve changes status: a reviewed, approved document stays translated. Approval state lives in approved_at / approved_by.

Pipeline stages, in order, as they appear in failure.stage:

ingest → extract → admit → map_translate → reconstruct

admit runs once extraction has counted the document's characters: when the month's allowance has no headroom left for them, the job stops there with failure.code = "quota_exceeded", before anything is translated or billed (see Server flags). A job interrupted by a service restart is marked failed with failure.stage = "worker".

A failing review never changes a job's status (see POST .../review). The four review_* stage names (review_apply_corrections, review_validate, review_persist_layout, review_reconstruct) appear only on a job that a failing review marked failed under an earlier release. Such a job's translation still counts as delivered — its segments and its download are still served — and a successful review returns it to translated.

What a job response contains

Every endpoint on this page that returns a job returns the same shape, whether the job is queued, translated or failed:

• layout is always null. The extracted layout is kept server-side and is not served. Reviewable content comes from GET /api/documents/{document_id}/segments, which pages the same server-side walk the renderer and the approval sweep use.
• artifacts lists the source document you uploaded and the translated output — the two kinds you can act on. The pipeline's own intermediate files are not listed, and entries carry no server-side path.
• quality_report and each segment's quality carry review signals — scores, needs_review, terminology compliance, fast-path provenance — and not the details of how a segment was produced.
• billable_chars is the metering quantity for the job: the source characters of its translated segments, as a raw count — the job's usage record, which is what the allowance and the invoice count, weights them by language pair (see Dense-script character weighting). A job is billed once, when it reaches translated; a failed job is not billed, even when billable_chars is already filled in. The one exception is a tenant using its own storage: a job whose translated output had already reached that storage account is billed even if a later step fails or the job is deleted, and a failure after delivery says in its message that the file was delivered and needs no resubmission.

Platform-operator diagnostics (the platform operator API key or a designated platform-operator session) receive extended fields on these same routes; everything documented on this page is the tenant contract, which is also what /openapi.json publishes.

Layout preservation and in-place translation

A document is translated one unit at a time — a text region, or a single table cell — and each translation is written back into the document in place. What that preserves, per format:

• PDF — page count, page size, rotation and images are unchanged, and translated text is laid back into the same position and typography as the source; a left-to-right document translated into Arabic, Persian or Urdu is set flush right. Bookmarks, page labels, links and fillable form fields carry over — except an XFA form, and the fields of a signed form (a signature cannot cover a translation). Only text on the visible page is translated and billed. Where a translation runs longer than the source it replaces, it first takes free space beside and below its box — never a neighbouring region's, and never past the edge of the sheet — then is shrunk and, at the limit, truncated; neither happens silently — each is reported as a quality finding on the job (see Finding codes).
• DOCX / XLSX — styles, numbering, formulas and sheet structure survive untouched; only the text changes. Formatting that varies inside one paragraph or cell does not survive: a DOCX paragraph takes the formatting of its dominant run, and a rich-text cell becomes plain text in the cell's own style. Hyperlinks keep their targets, and page and column breaks stay where they were. Fields Word computes itself — page numbers and counts, dates and times, and every field in a header or footer — keep their live value, with the text around them translated; other fields are translated as part of their sentence. A DOCX translated into Arabic, Persian or Urdu gets right-to-left paragraphs. Some text deliberately stays in the source language: an Excel Table's column headers (its formulas refer to them by name), sheet names, text inside formulas, and dropdown lists typed directly into a data-validation rule. Hyperlinks the write-back could not place exactly, and Table headers it kept, are reported as findings. Known limits: DOCX tracked changes, content controls and text boxes are left untranslated, and a translated PDF does not carry over the source's accessibility tags (its tagged structure).

Because the unit of work is a region or a table cell, the reviewable segment ids you get back (region_id, cell_id) address exactly the units the translated file is written from. That is what lets POST /review put a corrected translation back into the one unit it belongs to. The re-render that follows is not partial: every review re-renders the entire output file and appends a new artifact.

Supported uploads

Detection rules:

1. The file extension wins. HTTP clients routinely send application/octet-stream for Office files, so report.docx with a generic content type is still detected as DOCX.
2. If the name carries no known extension, the declared content type is used. When a file is matched on content type alone, the server appends the format's extension to the stored file name — uploading contract as application/pdf yields source_file_name: "contract.pdf".
3. Anything else is rejected with 415, and the error names the accepted set.

Request bodies are capped at 30 MB (30,000,000 bytes). A body over the cap is rejected with 413 before it is read in full.

Office files are also bounded by what they hold, not only by their upload size. A DOCX or XLSX is refused with 400 when it unpacks to more than 200,000,000 bytes, holds more than 80,000,000 bytes of XML that must be read whole, or — a DOCX — holds more than 1,000,000 XML elements; and one document may carry at most 2,000,000 characters of translatable text and 50,000 translatable segments. These checks run before any job exists, except the segment count and an XLSX's text, which are only known once the file is read: such a job fails at the extract stage instead (400 with wait=true). Each message names the limit and asks you to split the file.

Language codes must come from the supported set — 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); any other regional tag or bare variant base (en-US, fr-FR, zh, pt) is not accepted. fr is French as written in France and fr-CA is Canadian French.

An unsupported code is rejected before any job is created. The pair is checked at the API boundary, the same check and the same body as POST /api/translations: 422, naming the codes it rejected and the whole supported set — {"detail": "unsupported language(s): 'en-US'. Supported: en, es, fr, …"}. Validating client-side still saves the round trip.

POST /api/documents/translate

Upload a source document and start a translation job.

Auth: tenant credentials required (401 without). Also gated by the deployment's translation switch (503 when off) and, when billing is enabled, by an active subscription (402). Layout document translation is never covered by the free-character trial — a subscription is required whenever billing is on.

Content type: multipart/form-data. The endpoint reads the form directly, which is why no request body appears in openapi.json; the fields it reads are below.

Form fields

text_type: "Html" does nothing on a document job. This endpoint handles PDF/DOCX/XLSX, and none of those formats carry their inline formatting as HTML tags — asking for markup to be reproduced verbatim would only put stray angle brackets in the output. The value is recorded on the job and otherwise ignored. To translate HTML, post the fragment or an .html/.htm upload to POST /api/translations, which honors text_type in full.

Headers

Response codes

Example

curl -sS -X POST "https://trueidiom.com/api/documents/translate?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Idempotency-Key: contract-2026-07-26-001" \
  -F "source_document=@contract.pdf;type=application/pdf" \
  -F "source_lang=en" \
  -F "target_lang=fr" \
  -F "domain=legal"

import os
import requests

with open("contract.pdf", "rb") as handle:
    resp = requests.post(
        "https://trueidiom.com/api/documents/translate?api-version=2026-09-01",
        headers={
            "X-API-Key": os.environ["TRUEIDIOM_API_KEY"],
            "Idempotency-Key": "contract-2026-07-26-001",
        },
        files={"source_document": ("contract.pdf", handle, "application/pdf")},
        data={"source_lang": "en", "target_lang": "fr", "domain": "legal"},
        timeout=300,
    )
resp.raise_for_status()
doc = resp.json()
print(doc["id"], doc["status"])

// Node 20+ for fs.openAsBlob
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append(
  "source_document",
  await openAsBlob("contract.pdf", { type: "application/pdf" }),
  "contract.pdf",
);
form.append("source_lang", "en");
form.append("target_lang", "fr");
form.append("domain", "legal");

const res = await fetch("https://trueidiom.com/api/documents/translate?api-version=2026-09-01", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TRUEIDIOM_API_KEY,
    "Idempotency-Key": "contract-2026-07-26-001",
  },
  body: form,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const doc = await res.json();
console.log(doc.id, doc.status);

HTTP/1.1 202 Accepted

{
  "id": "b92fa968814843b08aea7b78f84d3894",
  "tenant_id": "7fa2bff864961656",
  "request": {
    "source_lang": "en",
    "target_lang": "fr",
    "domain": "legal",
    "idempotency_key": "contract-2026-07-26-001",
    "metadata": {
      "content_type": "application/pdf",
      "size_bytes": 83421,
      "idempotency_key": "contract-2026-07-26-001",
      "tenant": { "id": "7fa2bff864961656", "name": "acme" }
    },
    "text_type": "Plain",
    "tone": null,
    "gender": null
  },
  "status": "queued",
  "source_file_name": "contract.pdf",
  "source_format": "pdf",
  "layout": null,
  "quality_report": null,
  "billable_chars": 0,
  "review_history": [],
  "artifacts": [
    {
      "id": "fef4070fce1241dbb28a3d9ffd910478",
      "kind": "source_pdf",
      "stage": "ingest",
      "content_type": "application/pdf",
      "checksum": "8f27627500903fb03ee21bac28b291bde1e451900a31e0763f496f2ec8e180ab",
      "size_bytes": 83421,
      "created_at": "2026-07-26T09:14:02.370869Z",
      "metadata": { "source_file_name": "contract.pdf" }
    }
  ],
  "approved_at": null,
  "approved_by": null,
  "feed_manifest": { "fed_pairs": [], "skipped": {}, "golden_skipped_at_cap": 0, "last_feed_error": null },
  "error": null,
  "failure": null,
  "created_at": "2026-07-26T09:14:02.368957Z",
  "updated_at": "2026-07-26T09:14:02.370877Z"
}

Choosing sync vs async

wait=true holds the connection open until the document is finished and returns the completed job. Budgets are server-side: each stage gets one 1,800-second (30-minute) budget, inside which a transient failure is retried up to twice, and a busy service queues submissions rather than running them all at once. Prefer the default async path for anything larger than a couple of pages.

With wait=true, a stage failure surfaces as an error response rather than a job body — but the job is still persisted with status: "failed" and a populated failure object. Typed failures use the documented JSON error shape: 400 validation_error for a file that cannot be read or is over a per-document limit, 429 quota_exceeded when the month has no headroom left for the document, 429 rate_limit or 503 transient_error when the model provider stayed saturated or unavailable through the retries, 422 content_filtered when its content policy refused a segment, and 504 stage_timeout when a stage ran out of its time budget. Anything else is an unexpected internal failure: 500 with {"detail": "internal error", "error_code": "internal_error", "request_id": "<id>"}. Either way the persisted job record is the authoritative outcome, so read it rather than the response: resubmit with the same Idempotency-Key (which returns the existing job), or list GET /api/documents?status=failed.

Uploading a .pdf/.docx/.xlsx to POST /api/translations as multipart/form-data with a source_document part routes into this same document pipeline and returns a document job in the same shape this endpoint returns — with the same format detection, so a name without an extension gets the detected format's. That door always answers 200 and takes uploads up to the same 30 MB cap; see Text translation. Poll and download the job through the endpoints on this page.

GET /api/documents

List the calling tenant's document jobs, most recently updated first (updated_at descending).

Auth: tenant credentials required (401 without). Results are filtered to the caller's tenant.

layout is null here, as it is on every document response. Leaving it out is what keeps list responses small. quality_report, artifacts and review_history are included; page through reviewable content with GET /api/documents/{document_id}/segments.

Query parameters

Example

curl -sS -G "https://trueidiom.com/api/documents?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  --data-urlencode "status=failed" \
  --data-urlencode "failure_code=stage_timeout" \
  --data-urlencode "created_since=2026-07-01T00:00:00Z"

[
  {
    "id": "b92fa968814843b08aea7b78f84d3894",
    "tenant_id": "7fa2bff864961656",
    "request": {
      "source_lang": "en",
      "target_lang": "fr",
      "domain": "legal",
      "idempotency_key": null,
      "metadata": {
        "content_type": "application/pdf",
        "size_bytes": 83421,
        "idempotency_key": null,
        "tenant": { "id": "7fa2bff864961656", "name": "acme" }
      },
      "text_type": "Plain",
      "tone": null,
      "gender": null
    },
    "status": "failed",
    "source_file_name": "contract.pdf",
    "source_format": "pdf",
    "layout": null,
    "quality_report": null,
    "billable_chars": 0,
    "review_history": [],
    "artifacts": [
      {
        "id": "fef4070fce1241dbb28a3d9ffd910478",
        "kind": "source_pdf",
        "stage": "ingest",
        "content_type": "application/pdf",
        "checksum": "8f27627500903fb03ee21bac28b291bde1e451900a31e0763f496f2ec8e180ab",
        "size_bytes": 83421,
        "created_at": "2026-07-26T09:14:02.370869Z",
        "metadata": { "source_file_name": "contract.pdf" }
      }
    ],
    "approved_at": null,
    "approved_by": null,
    "feed_manifest": { "fed_pairs": [], "skipped": {}, "golden_skipped_at_cap": 0, "last_feed_error": null },
    "error": "TimeoutError",
    "failure": {
      "code": "stage_timeout",
      "stage": "map_translate",
      "message": "TimeoutError",
      "error_type": "TimeoutError",
      "retry_attempts": 0,
      "transient": true,
      "timeout": true,
      "metadata": {}
    },
    "created_at": "2026-07-26T09:14:02.368957Z",
    "updated_at": "2026-07-26T09:44:09.114003Z"
  }
]

Errors: 401 (no credentials), 422 (invalid filter value).

GET /api/documents/summary

Aggregate job counts grouped by status and failure taxonomy.

Auth: tenant credentials required for the plain summary (401 without); the counts cover only the caller's tenant. The two breakdown flags aggregate across all tenants, so they are reserved for the platform operator API key or a designated platform-operator session — and which refusal you get depends on how you authenticated. A tenant API key is stopped at the admin gate with 401 admin credentials required and never reaches the flags. A signed-in admin who is not a platform operator — a global_administrator is exactly that — reaches them and gets 403 cross-tenant breakdowns require operator access; a signed-in non-admin is turned away one step earlier with 403 admin role required.

Query parameters

Example

curl -sS "https://trueidiom.com/api/documents/summary?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

{
  "total": 38,
  "failed": 2,
  "by_status": { "translated": 35, "queued": 1, "failed": 2 },
  "failures": {
    "by_code": { "stage_timeout": 1, "unexpected_error": 1 },
    "by_stage": { "map_translate": 1, "reconstruct": 1 }
  }
}

With include_stage_timing_breakdown=true (operator credentials), the response gains:

{
  "stage_timings_ms": {
    "overall": {
      "extract": { "count": 38, "avg_ms": 812.4, "p50_ms": 640.2, "p95_ms": 2104.9 },
      "map_translate": { "count": 38, "avg_ms": 9310.7, "p50_ms": 7420.0, "p95_ms": 24110.5 },
      "reconstruct": { "count": 37, "avg_ms": 1962.4, "p50_ms": 1801.0, "p95_ms": 3550.7 }
    }
  }
}

by_tenant (from include_tenant_breakdown=true) maps tenant_id — or the literal "unassigned" — to {"total": n, "failed": n}, and when both flags are set stage_timings_ms.by_tenant carries the same per-stage stats per tenant.

Errors: 401 (no credentials, or a tenant API key on the breakdown flags), 403 (a non-operator session on the breakdown flags), 422 (invalid filter value).

GET /api/documents/{document_id}

Fetch one job. This is the poll target: read status until it is translated or failed.

Auth: tenant credentials required (401 without). A job belonging to another tenant returns 404.

Path parameters

Example

curl -sS "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

import os
import requests

resp = requests.get(
    "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    timeout=60,
)
resp.raise_for_status()
doc = resp.json()
print(doc["status"])  # poll until "translated" or "failed"

// Node 18+
const res = await fetch(
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894?api-version=2026-09-01",
  { headers: { "X-API-Key": process.env.TRUEIDIOM_API_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const doc = await res.json();
console.log(doc.status); // poll until "translated" or "failed"

{
  "id": "b92fa968814843b08aea7b78f84d3894",
  "tenant_id": "7fa2bff864961656",
  "request": {
    "source_lang": "en",
    "target_lang": "fr",
    "domain": "legal",
    "idempotency_key": "contract-2026-07-26-001",
    "metadata": {
      "content_type": "application/pdf",
      "size_bytes": 83421,
      "idempotency_key": "contract-2026-07-26-001",
      "tenant": { "id": "7fa2bff864961656", "name": "acme" }
    },
    "text_type": "Plain",
    "tone": null,
    "gender": null
  },
  "status": "translated",
  "source_file_name": "contract.pdf",
  "source_format": "pdf",
  "layout": null,
  "quality_report": {
    "schema_version": "1.0",
    "document_id": "e67fe11f03804045ab65cabe55473d82",
    "source_lang": "en",
    "target_lang": "fr",
    "overall_score": 0.97,
    "translated_units": 24,
    "total_units": 24,
    "findings": [],
    "metadata": {
      "page_count": 3,
      "schema_version": "1.0",
      "llm_quality": { "needs_review_units": 2, "noncompliant_units": 1 }
    }
  },
  "billable_chars": 4820,
  "review_history": [],
  "artifacts": [
    {
      "id": "fef4070fce1241dbb28a3d9ffd910478",
      "kind": "source_pdf",
      "stage": "ingest",
      "content_type": "application/pdf",
      "checksum": "8f27627500903fb03ee21bac28b291bde1e451900a31e0763f496f2ec8e180ab",
      "size_bytes": 83421,
      "created_at": "2026-07-26T09:14:02.370869Z",
      "metadata": { "source_file_name": "contract.pdf" }
    },
    {
      "id": "2adee39df2994c288e2de190108f0040",
      "kind": "translated_pdf",
      "stage": "reconstruct",
      "content_type": "application/pdf",
      "checksum": "3515540984a6e48aff7821df05b50b97334c06c6b94d1a81b9b50a05bfd81670",
      "size_bytes": 91234,
      "created_at": "2026-07-26T09:14:12.403125Z",
      "metadata": { "rendered_pages": 3 }
    }
  ],
  "approved_at": null,
  "approved_by": null,
  "feed_manifest": { "fed_pairs": [], "skipped": {}, "golden_skipped_at_cap": 0, "last_feed_error": null },
  "error": null,
  "failure": null,
  "created_at": "2026-07-26T09:14:02.368957Z",
  "updated_at": "2026-07-26T09:14:12.408112Z"
}

The two artifacts above are the whole list for a completed PDF job: the source you uploaded and the translated output. For reviewable text, use GET /api/documents/{document_id}/segments, which is paged.

Errors: 401 (no credentials), 404 (unknown id, or another tenant's job).

GET /api/documents/{document_id}/segments

Paged list of reviewable segments, walked server-side off the persisted layout. This walk is the single source of truth for what counts as a segment.

Auth: tenant credentials required (401 without). Cross-tenant → 404.

Semantics that matter:

• index is the segment's position in the full, unfiltered walk, so it stays stable across pages and across the flagged filter.
• total is the size of the selected set (the filtered set when flagged=true).
• flagged_total always counts flagged segments in the whole document, regardless of flagged, so you can render "N need attention" without a second request.
• Only a delivered translation is served. A job that is not translated — still queued or extracted, or failed at any stage — returns total: 0, flagged_total: 0, segments: [] with your limit/offset echoed back — not an error.
• Table regions yield one segment per non-empty cell; every other region yields one segment from its source text. Empty-source regions and cells are dropped by the walk, which is exactly why index is not a positional index into layout.

Path parameters

Query parameters

Response body (DocumentSegmentsResponse)

Each DocumentSegment:

quality carries the review signals for the segment and nothing else. The complete set of keys it can contain:

Keys are present only when the service recorded them: score and needs_review appear when per-segment quality scoring is enabled on the deployment (needs_review also, on any deployment, when a segment's translation came back empty), and fast_path appears whenever the text came straight from translation memory or the glossary. Scoring internals — traces, token counts, and what produced a given segment — are not part of this object.

Example

curl -sS -G "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/segments?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  --data-urlencode "flagged=true" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0"

import os
import requests

resp = requests.get(
    "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/segments?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    params={"flagged": "true", "limit": 50, "offset": 0},
    timeout=60,
)
resp.raise_for_status()
page = resp.json()
print(page["total"], page["flagged_total"])
for segment in page["segments"]:
    print(segment["region_id"], segment["cell_id"], segment["source"])

// Node 18+
const url = new URL(
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/segments?api-version=2026-09-01",
);
url.searchParams.set("flagged", "true");
url.searchParams.set("limit", "50");
url.searchParams.set("offset", "0");

const res = await fetch(url, {
  headers: { "X-API-Key": process.env.TRUEIDIOM_API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const page = await res.json();
console.log(page.total, page.flagged_total);
for (const segment of page.segments) {
  console.log(segment.region_id, segment.cell_id, segment.source);
}

{
  "total": 2,
  "flagged_total": 2,
  "limit": 50,
  "offset": 0,
  "segments": [
    {
      "index": 0,
      "page": 1,
      "target": "region",
      "region_id": "577ab4ee0485426fac76b74e22f4fdbc",
      "cell_id": null,
      "source": "Termination for cause",
      "translated": "Résiliation pour cause",
      "quality": {
        "score": 74.0,
        "below_threshold": true,
        "terminology_compliant": true,
        "missing_terms": {},
        "needs_review": true
      }
    },
    {
      "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 }
    }
  ]
}

Errors: 401 (no credentials), 404 (unknown id, or another tenant's job), 422 (limit/offset out of bounds).

GET /api/documents/{document_id}/artifacts

List the job's document files: the source you uploaded and the translated output.

Auth: tenant credentials required (401 without). Cross-tenant → 404.

This is a metadata listing (TenantDocumentArtifact[]) — there is no per-artifact fetch endpoint. Retrieve the bytes with GET /api/documents/{document_id}/download, read the quality report inline from the job object, and page reviewable content with GET /api/documents/{document_id}/segments. The pipeline's own intermediate files are not listed (see What a job response contains).

Artifact kinds

Artifacts are append-only. Each review re-render appends a new translated_pdf / translated_document entry with a fresh checksum; the last entry of that kind is the one whose checksum matches the stored bytes, and the one GET .../download serves.

Artifact fields (TenantDocumentArtifact)

Example

curl -sS "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/artifacts?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

{
  "document_id": "b92fa968814843b08aea7b78f84d3894",
  "artifacts": [
    {
      "id": "fef4070fce1241dbb28a3d9ffd910478",
      "kind": "source_pdf",
      "stage": "ingest",
      "content_type": "application/pdf",
      "checksum": "8f27627500903fb03ee21bac28b291bde1e451900a31e0763f496f2ec8e180ab",
      "size_bytes": 83421,
      "created_at": "2026-07-26T09:14:02.370869Z",
      "metadata": { "source_file_name": "contract.pdf" }
    },
    {
      "id": "2adee39df2994c288e2de190108f0040",
      "kind": "translated_pdf",
      "stage": "reconstruct",
      "content_type": "application/pdf",
      "checksum": "3515540984a6e48aff7821df05b50b97334c06c6b94d1a81b9b50a05bfd81670",
      "size_bytes": 91234,
      "created_at": "2026-07-26T09:14:12.403125Z",
      "metadata": { "rendered_pages": 3 }
    }
  ]
}

Errors: 401 (no credentials), 404 (unknown id, or another tenant's job).

GET /api/documents/{document_id}/download

Stream the translated file.

Auth: tenant credentials required (401 without). Cross-tenant → 404.

Selection rules:

1. Unless the job's translation was delivered — it is translated — respond 409; the source document is never served in its place. A job still in flight (pending, queued or extracted) gets document translation is still in progress — keep polling. A failed job gets document translation failed; no translated output is available.
2. Otherwise take the most recent translated_pdf / translated_document artifact — the latest review re-render, if there has been one.
3. If the job has no downloadable artifact, respond 404.

So call this once status is translated; every other status gets 409.

The stored SHA-256 is re-verified against the bytes before they are returned; a mismatch fails the request with 500 document artifact failed integrity check rather than serving suspect content.

Response headers:

Example

curl -sS -o contract.fr.pdf -D - \
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/download?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

import os
import requests

resp = requests.get(
    "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/download?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    timeout=300,
)
resp.raise_for_status()
print(resp.headers["content-type"], resp.headers["content-disposition"])
with open("contract.fr.pdf", "wb") as handle:
    handle.write(resp.content)

// Node 18+
import { writeFile } from "node:fs/promises";

const res = await fetch(
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/download?api-version=2026-09-01",
  { headers: { "X-API-Key": process.env.TRUEIDIOM_API_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(res.headers.get("content-type"), res.headers.get("content-disposition"));
await writeFile("contract.fr.pdf", Buffer.from(await res.arrayBuffer()));

HTTP/1.1 200 OK
content-type: application/pdf
content-disposition: attachment; filename="contract.pdf"
content-length: 91234
x-request-id: c2ac6a3b91ad4608ad744a56fd74d448

Errors: 401 (no credentials), 404 (unknown id, another tenant's job, no downloadable artifact, or the stored bytes are missing), 409 (job not translated: still in flight, or failed — or storage_binding_not_verified when the file is held in the tenant's own storage and that binding is not verified, or its stored secret is missing or unreadable), 500 (checksum mismatch), 503 transient_error (the service's own secret storage could not be read — retry shortly).

POST /api/documents/{document_id}/review

Apply human corrections to individual segments, then re-validate, re-render and persist the document.

Auth: tenant credentials required (401 without). Cross-tenant → 404, checked before anything is mutated. The reviewer identity is derived server-side; see Reviewer identity.

What one call does, in order: apply each correction to the layout → rebuild quality_report — the document checks run again, the translate pass's unresolved per-segment findings are kept, and a segment a reviewer corrected stops counting as low-quality or non-compliant → persist the corrected layout server-side → re-render the entire output file — not only the pages corrections touched — and append a new translated artifact → feed the applied corrections into the tenant's golden translation memory (best-effort) → append a DocumentReviewRecord to review_history.

Review is repeatable, and only a translated job can be reviewed. A review never approves the document and never takes a job out of translated: one that succeeds leaves it translated, and one that fails once it is under way returns its error and changes nothing — the job keeps its previous segments, quality report and output file. The typed refusals below (400, 404) are checked before any correction is applied. Reviews and approvals of one document run one at a time, so concurrent calls never drop each other's corrections.

Path parameters

Request body (DocumentReviewRequest, application/json, required)

DocumentReviewCorrection:

Conflicts

A correction that cannot be located is rejected, not fatal — the rest of the batch still applies. Each rejection appears in conflicts with a reason, and the distinct reasons are collected into conflict_codes:

Response body (TenantDocumentReviewResponse)

DocumentReviewSummary:

A pair counted in fed_pairs is one this document offered to the memory, which is not always one the memory kept: when the tenant is at its translation-memory cap for the language pair, a pair carrying a new source is skipped rather than stored. That is not a feed_error — the running count is on the job as feed_manifest.golden_skipped_at_cap.

Example

curl -sS -X POST \
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/review?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer": "reviewer@acme.example",
    "notes": "Legal review, pass 1.",
    "corrections": [
      {
        "target": "region",
        "region_id": "577ab4ee0485426fac76b74e22f4fdbc",
        "translated_text": "Résiliation pour motif valable",
        "note": "House style."
      },
      {
        "target": "table_cell",
        "region_id": "0000000000000000000000000000dead",
        "cell_id": "4bde2f9c1a7048e6b39d5c81f0a2e743:0:3",
        "translated_text": "Paiement à 30 jours"
      }
    ]
  }'

import os
import requests

corrections = [
    {"target": "region", "region_id": "577ab4ee0485426fac76b74e22f4fdbc",
     "translated_text": "Résiliation pour motif valable", "note": "House style."},
    {"target": "table_cell", "region_id": "0000000000000000000000000000dead",
     "cell_id": "4bde2f9c1a7048e6b39d5c81f0a2e743:0:3",
     "translated_text": "Paiement à 30 jours"},
]
resp = requests.post(
    "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/review?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    json={"reviewer": "reviewer@acme.example", "notes": "Legal review, pass 1.",
          "corrections": corrections},
    timeout=300,
)
resp.raise_for_status()
result = resp.json()["review_result"]
print(result["applied_corrections"], result["rejected_corrections"], result["conflict_codes"])

// Node 18+
const res = await fetch(
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/review?api-version=2026-09-01",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TRUEIDIOM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reviewer: "reviewer@acme.example",
      notes: "Legal review, pass 1.",
      corrections: [
        { target: "region", region_id: "577ab4ee0485426fac76b74e22f4fdbc",
          translated_text: "Résiliation pour motif valable", note: "House style." },
        { target: "table_cell", region_id: "0000000000000000000000000000dead",
          cell_id: "4bde2f9c1a7048e6b39d5c81f0a2e743:0:3",
          translated_text: "Paiement à 30 jours" },
      ],
    }),
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { review_result: result } = await res.json();
console.log(result.applied_corrections, result.rejected_corrections, result.conflict_codes);

The second correction carries a deliberately bogus region_id so the response below shows what a rejection looks like. Ids returned by GET .../segments always resolve — echo region_id and cell_id back exactly as you received them and both corrections apply.

reviewer is supplied here because the call authenticates with an API key and has no session to derive an identity from. A caller sending an Authorization: Bearer session token can omit it — and if it is sent anyway, the session identity is what gets recorded.

The job field carries the whole updated job, in the same shape every document endpoint returns; the abbreviated form below shows only the parts this call changed.

{
  "job": {
    "id": "b92fa968814843b08aea7b78f84d3894",
    "status": "translated",
    "review_history": [
      {
        "reviewer": "reviewer@acme.example",
        "notes": "Legal review, pass 1.",
        "applied_corrections": 1,
        "rejected_corrections": 1,
        "impacted_pages": [1],
        "conflicts": [
          {
            "target": "table_cell",
            "region_id": "0000000000000000000000000000dead",
            "cell_id": "4bde2f9c1a7048e6b39d5c81f0a2e743:0:3",
            "reason": "region_not_found"
          }
        ],
        "fed_pairs": 1,
        "feed_error": null,
        "created_at": "2026-07-26T09:28:09.071039Z"
      }
    ]
  },
  "review_result": {
    "reviewer": "reviewer@acme.example",
    "applied_corrections": 1,
    "rejected_corrections": 1,
    "impacted_pages": [1],
    "conflict_codes": ["region_not_found"],
    "conflicts": [
      {
        "target": "table_cell",
        "region_id": "0000000000000000000000000000dead",
        "cell_id": "4bde2f9c1a7048e6b39d5c81f0a2e743:0:3",
        "reason": "region_not_found"
      }
    ],
    "fed_pairs": 1,
    "feed_error": null
  }
}

Errors:

How this differs from text-pipeline review

POST /api/documents/{document_id}/approve

Stamp the document approved and feed every eligible segment into the tenant's golden translation memory.

Auth: tenant credentials required (401 without). Cross-tenant → 404, checked before anything is mutated, so a cross-tenant caller can never feed another tenant's content into the golden store. Reviewer identity is derived server-side.

Approval is the countable learning event. Review feeds only the human-corrected pairs; approve sweeps the remaining clean segments and records the golden audit.

Eligibility. A segment feeds the golden store unless it is excluded, and every exclusion is tallied in skipped:

Human-corrected segments (quality.corrected) always feed, and are ordered first, regardless of fast_path / needs_review.

Idempotent. A second approve returns already_approved: true, fed_pairs: 0 and replays the recorded skipped tally. approval_result.reviewer is then the original approver, not the current caller.

Path parameters

Request body (DocumentApprovalRequest, application/json, required)

The body is required; send {} when you have nothing to add.

Response body (TenantDocumentApprovalResponse)

A full translation memory does not fail an approval. When the tenant is at its translation-memory cap for the job's language pair, approved pairs carrying a source the memory does not already hold are skipped and not stored, and counted cumulatively in job.feed_manifest.golden_skipped_at_cap. A correction to a source the memory already holds is still admitted at the cap, so reviewer edits keep teaching the memory. A non-zero golden_skipped_at_cap means later identical requests will not get a free exact hit from those pairs; free budget for the pair with DELETE /api/tm/{set_id} on an imported set (see Terminology & translation memory).

Example

curl -sS -X POST \
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/approve?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewer": "reviewer@acme.example", "notes": "Approved for delivery."}'

import os
import requests

resp = requests.post(
    "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/approve?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    json={"reviewer": "reviewer@acme.example", "notes": "Approved for delivery."},
    timeout=300,
)
resp.raise_for_status()
approval = resp.json()["approval_result"]
print(approval["already_approved"], approval["fed_pairs"], approval["skipped"])

// Node 18+
const res = await fetch(
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894/approve?api-version=2026-09-01",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TRUEIDIOM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reviewer: "reviewer@acme.example",
      notes: "Approved for delivery.",
    }),
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { approval_result: approval } = await res.json();
console.log(approval.already_approved, approval.fed_pairs, approval.skipped);

The job below is abbreviated to the fields approval changes, and feed_manifest.fed_pairs to its first entry — the manifest holds one entry per pair ever fed for this document, so after an approve that fed 22 it carries many more than the one shown.

{
  "job": {
    "id": "b92fa968814843b08aea7b78f84d3894",
    "status": "translated",
    "approved_at": "2026-07-26T09:31:44.512004Z",
    "approved_by": "reviewer@acme.example",
    "feed_manifest": {
      "fed_pairs": [
        {
          "source_text": "Termination for cause",
          "target_text": "Résiliation pour motif valable",
          "source_hash": "1a3f9c0e2b7d4854af1b6c9d0e5f2a73c8b41d6e9f0a2b3c4d5e6f708192a3b4",
          "corrected": true,
          "stage": "review",
          "created_at": "2026-07-26T09:28:09.070112Z"
        }
        …
      ],
      "skipped": { "fast_path": 1, "needs_review": 1, "duplicates": 0, "empty": 0 },
      "golden_skipped_at_cap": 0,
      "last_feed_error": null
    }
  },
  "approval_result": {
    "approved": true,
    "already_approved": false,
    "reviewer": "reviewer@acme.example",
    "fed_pairs": 22,
    "skipped": { "fast_path": 1, "needs_review": 1, "duplicates": 0, "empty": 0 },
    "feed_error": null
  }
}

Errors:

DELETE /api/documents/{document_id}

Hard-delete one document job and everything it produced (self-service content deletion).

Auth: admin only, and — the platform operator API key aside — it has to be a session: an Authorization: Bearer <access_token> (or the signed-in browser session) for a user holding the global_administrator role in the document's own tenant, as in the example below. A tenant API key never satisfies this gate. It is refused with 401 admin credentials required — not 403, and never success — however admin the tenant it belongs to. A session that authenticates but does not hold the role gets 403 admin role required. An admin of another tenant gets 404 (deletion never confirms a foreign document id exists). Only platform-operator credentials — the operator API key, or a designated platform-operator session — cross tenants.

The delete cascades. Removed along with the job record:

• every artifact — every file stored for the job (source, intermediate data, quality report, translated output) and, for a Bring-Your-Own-Storage tenant, the blobs in the tenant's own storage account. A BYOS deletion failure is logged and never blocks the platform-side delete; the count reflects only what was actually removed.
• all segments — they live inside the job record and the files deleted with it.
• golden audit record(s) — the document_approval record the approval wrote into the golden system-of-record (platform store, plus the tenant's BYOS golden store when bound).
• TM pairs — exactly the pairs this document fed into the tenant's golden-approved-<src>-<tgt> set (from the job's feed manifest, matched by normalized source hash). Sibling pairs and client TMX imports are never touched.
• learning rows — only rows provably derived from this document. A row without that linkage is left in place rather than risk deleting another tenant's data.

A job still in flight is cancelled before anything is removed, so a running translation cannot write artifacts back after the delete. A delete that arrives while a review or approval of the same document is running waits for it to finish, then removes what it fed as well.

Deliberately retained: usage/billing records and the auth audit log survive deletion (legal/tax retention — see the privacy policy).

Deletion is permanent — there is no undo. Afterwards GET /api/documents/{document_id}, /artifacts, /segments, and /download all return 404.

Path parameters

Response

200 OK. Counts report what was actually removed, not what was expected:

{
  "deleted": true,
  "document_id": "b92fa968814843b08aea7b78f84d3894",
  "artifacts_removed": 5,
  "segments_removed": 24,
  "golden_records_deleted": 1,
  "tm_pairs_removed": 22,
  "learning_rows_removed": 2
}

Example

curl -X DELETE \
  "https://trueidiom.com/api/documents/b92fa968814843b08aea7b78f84d3894?api-version=2026-09-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Errors:

Schemas

TenantDocumentJob

The body of POST /api/documents/translate, every entry of GET /api/documents, GET /api/documents/{document_id}, and the job field of the review and approval responses. This is the shape /openapi.json publishes; see What a job response contains for what it deliberately does not carry.

DocumentTranslationRequest

DocumentFailureDetail

DocumentFeedManifest and DocumentFedPair

feed_manifest is the durable record of what this document has contributed to the tenant's golden translation memory. It is what makes re-review and re-approve non-duplicating.

DocumentFeedManifest:

DocumentFedPair:

DocumentQualityReport and DocumentQualityFinding

DocumentQualityFinding:

Finding codes

code is the stable value to branch on; message is prose written for a human and may be reworded. The codes a document job can carry:

overall_score starts as the share of units that came back translated, and any error-severity finding caps it at 0.5. Two warnings also hold it down, because text a reader cannot see was not delivered: it is never above the share of units that were neither truncated (reconstruction_text_truncated) nor placed entirely off the page (geometry_region_off_page). Every other warning and info finding leaves it alone: the file was produced and the text was translated, and what they report is fit, placement or confidence.

The layout

The extracted layout is internal to the service and is not part of any response — job.layout is always null (see What a job response contains). What crosses the API instead:

• GET .../segments is the structured view of the document's translatable content. Its server-side walk is the single source of truth for what counts as a segment.
• region_id and cell_id are the layout's addressing scheme, surfaced per segment. Treat them as opaque: echo them back verbatim on corrections. A cell_id is {table_id}:{row}:{column} — a 32-character hex table id, a 0-based row and a 0-based column — but you never need to construct one.
• Layout, fonts and formatting are applied server-side when the output file is produced; that is what makes the translation land in place in the downloaded document.

Reviewer identity

POST /review and POST /approve resolve the reviewer as follows:

1. Try the server-derived session identity — the authenticated principal's email, falling back to its user id. It is read from the Authorization: Bearer access token or the browser session cookie.
2. If a session resolves, it wins. A different reviewer in the body is ignored (the server logs the discrepancy) and the response echoes the authenticated identity in review_result.reviewer / approval_result.reviewer.
3. If no session resolves — API-key-only clients such as a CAT tool integration — the body's reviewer is used.
4. If neither exists, the call fails:

{ "detail": "reviewer could not be determined: sign in or supply a reviewer" }

The practical consequence for an API-key integration: always send reviewer on /review and /approve, or the call returns 400.

Error format

The canonical error catalog — body shapes, the full error_code vocabulary, and status-code semantics — is in Conventions & errors. Below is what these endpoints emit.

HTTPException-based errors return:

{ "detail": "document job not found" }

Errors raised from the pipeline layer add a machine-readable code and the request's id — the same value as the X-Request-ID response header: the one you sent, or the server-generated one when you sent none (never null):

{
  "detail": "document job doc_missing not found",
  "error_code": "not_found",
  "request_id": "c2ac6a3b91ad4608ad744a56fd74d448"
}

stage_timeout reaches you only from a wait=true request; on the job it is failure.code = "stage_timeout". internal_error is the answer to an unexpected internal failure — {"detail": "internal error", "error_code": "internal_error", "request_id": "<id>"} — on any of these endpoints.

One storage code can also surface on document calls when a tenant uses its own storage: storage_binding_not_verified (409) — the binding is not verified, or its stored credential can no longer be used. A submission gets it before any job is created (verify the binding, then resubmit); a review, approval or download that needs files held in that storage gets it too — when the stored secret is gone, with workspace storage (BYOS) cannot be used: the stored secret for its binding is missing or unreadable — re-enter the SAS token or connection string in Storage settings and verify the binding, or switch the workspace back to platform storage. When it is the service's own secret storage that cannot be read, those calls answer 503 transient_error (secret storage is temporarily unavailable — try again shortly) instead; retry shortly. Document jobs are never parked, so persistence_failed does not occur here.

Validation failures raised by FastAPI (bad enum value, out-of-range limit) use the standard 422 shape:

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

Server flags that change what you see

The quota is measured in weighted billed characters, not raw ones: a pair touching Chinese (Simplified or Traditional), Japanese, Korean, Thai, Hindi, Marathi or Nepali counts each source character as 3.5 by default, on either side of the pair. See Tenants, usage & billing for the allowance formula, the top-up headroom and the remedies the 429 names.

Worked example: upload → poll → review → approve → download

BASE=https://trueidiom.com
KEY=$TRUEIDIOM_API_KEY

1. Upload. Async submit returns 202 with the job id.

DOC_ID=$(curl -sS -X POST "$BASE/api/documents/translate" \
  -H "X-API-Key: $KEY" \
  -H "Idempotency-Key: contract-2026-07-26-001" \
  -F "source_document=@contract.pdf;type=application/pdf" \
  -F "source_lang=en" \
  -F "target_lang=fr" \
  -F "domain=legal" | jq -r .id)

echo "$DOC_ID"
# b92fa968814843b08aea7b78f84d3894

2. Poll until terminal. Stop on translated or failed.

while true; do
  STATUS=$(curl -sS "$BASE/api/documents/$DOC_ID" -H "X-API-Key: $KEY" | jq -r .status)
  echo "status=$STATUS"
  case "$STATUS" in
    translated|failed) break ;;
  esac
  sleep 2
done

If failed, read the reason:

curl -sS "$BASE/api/documents/$DOC_ID" -H "X-API-Key: $KEY" | jq '.failure'

{
  "code": "stage_timeout",
  "stage": "map_translate",
  "message": "TimeoutError",
  "error_type": "TimeoutError",
  "retry_attempts": 0,
  "transient": true,
  "timeout": true,
  "metadata": {}
}

failure.message and job.error say what failed (an unexpected internal fault reads internal error; a stage that ran out of time reads TimeoutError, as above); failure.code is the stable value to branch on — transient_error is worth retrying later, stage_timeout and unexpected_error are not worth retrying unchanged, interrupted means a service restart dropped the work, and quota_exceeded means the month had no headroom left for the document (see DocumentFailureDetail). Resubmit with a new Idempotency-Key — the same key returns the failed job.

3. List the segments that need attention.

curl -sS -G "$BASE/api/documents/$DOC_ID/segments" \
  -H "X-API-Key: $KEY" \
  --data-urlencode "flagged=true" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" | jq '{total, flagged_total, first: .segments[0]}'

{
  "total": 2,
  "flagged_total": 2,
  "first": {
    "index": 0,
    "page": 1,
    "target": "region",
    "region_id": "577ab4ee0485426fac76b74e22f4fdbc",
    "cell_id": null,
    "source": "Termination for cause",
    "translated": "Résiliation pour cause",
    "quality": { "needs_review": true, "terminology_compliant": false, "score": 74.0 }
  }
}

Page through with offset while offset + limit < total. flagged_total stays constant, so it is safe to use as a progress denominator.

4. Correct a segment. Reuse region_id (and cell_id for table cells) exactly as returned.

curl -sS -X POST "$BASE/api/documents/$DOC_ID/review" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer": "reviewer@acme.example",
    "notes": "Legal review, pass 1.",
    "corrections": [
      {
        "target": "region",
        "region_id": "577ab4ee0485426fac76b74e22f4fdbc",
        "translated_text": "Résiliation pour motif valable"
      }
    ]
  }' | jq '.review_result'

{
  "reviewer": "reviewer@acme.example",
  "applied_corrections": 1,
  "rejected_corrections": 0,
  "impacted_pages": [1],
  "conflict_codes": [],
  "conflicts": [],
  "fed_pairs": 1,
  "feed_error": null
}

The output file has already been re-rendered at this point — a new translated_pdf artifact with a new checksum is appended. Re-fetch the segments to confirm the corrected unit now reports quality.corrected: true and needs_review: false.

5. Approve. This stamps the job and sweeps the clean segments into the golden translation memory.

curl -sS -X POST "$BASE/api/documents/$DOC_ID/approve" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewer": "reviewer@acme.example", "notes": "Approved for delivery."}' | jq '.approval_result'

{
  "approved": true,
  "already_approved": false,
  "reviewer": "reviewer@acme.example",
  "fed_pairs": 22,
  "skipped": { "fast_path": 1, "needs_review": 1, "duplicates": 0, "empty": 0 },
  "feed_error": null
}

6. Download the translated file. The response is named after the source file, so rename on the way out.

curl -sS -o "contract.fr.pdf" \
  "$BASE/api/documents/$DOC_ID/download" \
  -H "X-API-Key: $KEY"

Approval is not a precondition for download — you can download as soon as status is translated, and again after every review re-render.