Text Translation

Start here: README · Related: Authentication · Conventions & errors · Documents · Terminology & TM

The text translation API submits plain-text source segments through the TrueIdiom human-in-the-loop pipeline: baseline translation, an automated quality gate, optional human review, and publication to the golden store and translation memory. Use this page when you are integrating string, segment, or paragraph translation — anything where you send text and read back a TranslationJob. Layout-preserving PDF/DOCX/XLSX translation is a separate pipeline under /api/documents.

Base URL: https://trueidiom.com. Every endpoint on this page is prefixed with /api. Requests take an optional api-version=2026-09-01 query parameter; omitting it serves the oldest supported version. See Versioning.

Authentication

The generated document declares no securitySchemes and no global security requirement, so the interactive /docs page shows every endpoint as unauthenticated. Auth is real, and every endpoint on this page enforces it.

Treat this page, not /docs, as the contract. Auth is not the only thing the generated spec understates. The batch request body is absent from it entirely; the DELETE response body is typed only as an open object; the three file downloads across this page and Terminology & TM (GET /api/translations/{job_id}/golden, GET /api/tm/{set_id}/export, GET /api/tm/export/golden) are declared application/json with empty schemas, though none of them returns JSON; and several list and create responses are typed as open objects rather than as the shapes documented here.

Credentials resolve as follows for every endpoint on this page:

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

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 Localization","email":"you@example.com","password":"correct-horse-battery-staple"}' \
  | jq -r .tenant_api_key)

A key minted this way cannot run the examples below yet. Signing up starts the free trial, and the trial covers the workspace only. With billing in force, a tenant API key on a trial tenant is refused with 402 {"detail": "the free trial covers the workspace only — API access requires an active subscription; subscribe at /billing"}, even with trial characters left and days on the clock. Subscribe at /billing first, or drive the examples with an OAuth2 access token from POST /api/oauth2/token — a bearer access token resolves as a workspace session and is admitted for as long as the trial is live. See Feature gating.

Resolution order. On a deployment that has tenant accounts, a bearer access token is tried first; if it does not resolve an active tenant, the API key is tried (from X-API-Key, falling back to the Authorization: Bearer value). X-Tenant-ID, when sent, narrows the lookup to that one account — a credential that does not belong to it is rejected rather than resolved against another. If neither credential resolves an active tenant, the request fails with 401 {"detail": "missing or invalid tenant credentials"}. On a deployment with no tenant accounts, the single configured service key is checked instead and a mismatch returns 401 {"detail": "missing or invalid API key"}.

Tenant scoping. GET /api/translations, GET /api/translations/{job_id}, and POST /api/translations/{job_id}/review are scoped to the caller's own tenant. A job belonging to another tenant is reported as 404 job not found rather than 403, so the endpoint never confirms that an id exists to a caller who cannot see it. The global_administrator role does not widen this — it is a per-tenant admin role.

Other headers.

Feature gating

Two service-level conditions change what these endpoints do. Neither is set per request.

Job lifecycle

POST /api/translations runs the pipeline inline. The HTTP response is returned after the workflow finishes, and the job in that response has already reached either published (the quality gate cleared it autonomously) or awaiting_review (a human is required). GET /api/translations/{job_id} is for re-reading a job later — after a review, or from a different process.

submit ──► pending ──► translated ──► [quality gate]
                                       │
                          gate passes ─┴─► published ──► golden store + TM + learning
                                       │
                          gate defers ──► awaiting_review
                                              │
                        review: approve ──────┼──► approved ──► published
                        review: modify ───────┤              └─► human_edited
                        review: save ─────────┤ (stays awaiting_review)
                        review: reject ───────┴──► rejected

JobStatus values

Only published and human_edited jobs can be downloaded from /golden. Only awaiting_review and refined jobs are reviewable.

POST /api/translations

Submit text for translation. Runs the full pipeline and returns the finished job.

Auth: required (tenant API key or bearer access token). Subject to the translation availability gate (see Feature gating).

Request body — TranslationRequest

Content-Type: application/json. A body whose Content-Type is not multipart/form-data, text/*, application/xml, text/xml, application/octet-stream, application/pdf, or the DOCX media type is parsed as JSON.

These six fields are carried verbatim from the wire shape this API grew out of, so a client written against the old shape keeps validating. What they do has changed with the engine, and they now split in two:

• Functional — text_type, tone and gender steer the baseline translation. Under the older shape they applied only when the engine was specifically configured for them; today they always apply, on every request.
• Inert — deployment_name, adaptive_dataset_id and allow_fallback have no equivalent and are ignored. They are still accepted, stored on job.request, and returned unchanged, so nothing breaks; supplying one logs a warning server-side. What replaces each: the baseline engine is a service-side choice, with metadata.candidate_models as the per-request opt-in for extra candidates; the dataset id is replaced by the tenant's translation-memory sets, whose approved pairs inform new translations automatically; and there is no second engine left to fall back to.

Caveat on text_type: "Html". Tag integrity is a strict instruction to the translation engine, not a structural guarantee — the engine sees the markup along with the text it is translating. Malformed, adversarial or very large fragments can still come back with altered markup, so a caller that needs a hard guarantee must validate the returned fragment itself.

These are also the per-target knobs of the batch shape, with the same functional/inert split.

Response

200 OK with a single TranslationJob object. A batch body (inputs) returns a JSON array of jobs — see Batch submission.

Example

curl -X POST "https://trueidiom.com/api/translations?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirm-7741-es" \
  -d '{
    "source_text": "Your order has shipped and will arrive on Tuesday.",
    "source_lang": "en",
    "target_lang": "es",
    "domain": "ecommerce",
    "metadata": {
      "min_quality_score": 90,
      "max_quality_loop_retries": 3
    }
  }'

Response, in the tenant shape every non-operator caller receives (agent_run.steps is abbreviated to one entry — a real run carries one per workflow node):

{
  "id": "9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d",
  "request": {
    "source_text": "Your order has shipped and will arrive on Tuesday.",
    "source_lang": "en",
    "target_lang": "es",
    "idempotency_key": "order-confirm-7741-es",
    "domain": "ecommerce",
    "metadata": {
      "min_quality_score": 90,
      "max_quality_loop_retries": 3,
      "tenant": { "id": "b41d0f9c7a2e4d18", "name": "Acme Localization" },
      "terminology_gate": {
        "passed": true,
        "missing_terms": {},
        "expected_target_counts": {},
        "observed_target_counts": {},
        "matched_source_terms": []
      },
      "golden_uri": "file:///srv/hitl/data/golden/golden-20260726.jsonl"
    },
    "text_type": null,
    "deployment_name": null,
    "adaptive_dataset_id": null,
    "allow_fallback": null,
    "tone": null,
    "gender": null
  },
  "agent_run": {
    "id": "2a7e5c99d1b34f0a86e2c4d7b9f1a3e5",
    "workflow_name": "translation_agent_workflow",
    "status": "completed",
    "current_step": null,
    "steps": [
      {
        "id": "6d4b2f8a0c1e4738b5a9d2c6e0f3a1b7",
        "name": "quality_gate",
        "actor": "quality_judge_agent",
        "kind": "agent",
        "status": "completed",
        "input_summary": "Assess, repair-if-needed, verify-if-repaired.",
        "output_summary": "Quality gate passed at score 93.0; no repair needed.",
        "tool_calls": [],
        "decisions": [],
        "error": null,
        "started_at": "2026-07-26T14:03:09.884120Z",
        "completed_at": "2026-07-26T14:03:11.402665Z"
      }
    ],
    "quality_gate": {
      "id": "c0e7b1a4d29f4c65a3b8e7d1f2c4a6b9",
      "name": "human_review_gate",
      "decision": "pass",
      "reasons": [],
      "triggers": [],
      "score": 93.0,
      "threshold": 90.0,
      "metadata": {
        "verification_passed": null,
        "verification_score": null,
        "assessment_score": 93.0,
        "risk_flags": [],
        "trigger_codes": [],
        "terminology_gate": {
          "passed": true,
          "missing_terms": {},
          "expected_target_counts": {},
          "observed_target_counts": {},
          "matched_source_terms": []
        },
        "repaired": false
      },
      "created_at": "2026-07-26T14:03:11.410882Z"
    },
    "human_review_task": null,
    "error": null,
    "started_at": "2026-07-26T14:03:07.221904Z",
    "completed_at": "2026-07-26T14:03:12.663017Z"
  },
  "baseline_translation": "Tu pedido ha sido enviado y llegará el martes.",
  "quality_assessment": {
    "score": 93.0,
    "issues": [],
    "reasoning": "Accurate and fluent; register matches the source.",
    "created_at": "2026-07-26T14:03:11.398441Z"
  },
  "refinement": null,
  "verification": null,
  "final_translation": "Tu pedido ha sido enviado y llegará el martes.",
  "reviewer": null,
  "review_action": null,
  "review_notes": null,
  "learning_signals": [
    {
      "signal_type": "translation_memory",
      "source_lang": "en",
      "target_lang": "es",
      "domain": "ecommerce",
      "reviewer": null,
      "source_text": "Your order has shipped and will arrive on Tuesday.",
      "before": "Tu pedido ha sido enviado y llegará el martes.",
      "after": "Tu pedido ha sido enviado y llegará el martes.",
      "confidence": 1.0,
      "evidence": { "review_action": null },
      "created_at": "2026-07-26T14:03:12.514773Z"
    }
  ],
  "status": "published",
  "created_at": "2026-07-26T14:03:07.220188Z",
  "updated_at": "2026-07-26T14:03:12.661440Z"
}

Errors

Pipeline failures surface through the shared error handler with {"detail", "error_code", "request_id"}: 429 rate_limit, 503 transient_error, 504 stage_timeout, 500 internal_error. A job whose pipeline raised is saved with status: "failed" and can still be read with GET /api/translations/{job_id}.

Other request shapes accepted by this endpoint

POST /api/translations is content-type polymorphic. Besides the JSON TranslationRequest above:

Layout-document form fields

Flatten-to-text form fields (multipart)

Flatten-to-text query parameters (raw body)

Raw-body mode has no form to read, so the same knobs arrive as query parameters. The source text is the request body itself.

curl -X POST "https://trueidiom.com/api/translations?target_lang=fr&source_lang=en&min_quality_score=92&api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: text/plain; charset=utf-8" \
  -H "X-Source-Filename: handbook.txt" \
  --data-binary @handbook.txt

Document-mode response:

{
  "mode": "document",
  "source_document": "handbook.txt",
  "target_lang": "fr",
  "pages": 3,
  "job_ids": [
    "4f8a1c6d2b9e4703a5c8d1f2e3b4a5c6",
    "7b3e9d0c5a1f42689d0e3b7c2a5f8d14",
    "1d6c4b8e0f2a47539c7e1b5d3f0a2c68"
  ],
  "first_job_id": "4f8a1c6d2b9e4703a5c8d1f2e3b4a5c6",
  "output_file": "data/jobs/handbook-fr.txt"
}

output_file is a server-side path to the concatenated per-page output (pages separated by === Page N === markers), not a URL. To retrieve translated content over the API, read each id in job_ids with GET /api/translations/{job_id} or download it from GET /api/translations/{job_id}/golden.

413 document exceeds MAX_BATCH_ITEMS when split into pages is returned when the page count exceeds MAX_BATCH_ITEMS; 400 source_document has no translatable content when extraction yields nothing.

GET /api/translations

List the calling tenant's translation jobs, most recently updated first.

Auth: required.

Query parameters

Example

curl -G "https://trueidiom.com/api/translations?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  --data-urlencode "status=awaiting_review"

[
  {
    "id": "9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d",
    "request": { "source_text": "Your order has shipped.", "source_lang": "en", "target_lang": "es", "idempotency_key": null, "domain": "ecommerce", "metadata": {}, "text_type": null, "deployment_name": null, "adaptive_dataset_id": null, "allow_fallback": null, "tone": null, "gender": null },
    "agent_run": { "id": "2a7e5c99d1b34f0a86e2c4d7b9f1a3e5", "workflow_name": "translation_agent_workflow", "status": "waiting_for_human", "current_step": null, "steps": [], "quality_gate": null, "human_review_task": null, "error": null, "started_at": "2026-07-26T14:03:07.221904Z", "completed_at": null },
    "baseline_translation": "Tu pedido ha sido enviado.",
    "quality_assessment": null,
    "refinement": null,
    "verification": null,
    "final_translation": "Tu pedido ha sido enviado.",
    "reviewer": null,
    "review_action": null,
    "review_notes": null,
    "learning_signals": [],
    "status": "awaiting_review",
    "created_at": "2026-07-26T14:03:07.220188Z",
    "updated_at": "2026-07-26T14:03:12.661440Z"
  }
]

The full response returns whole TranslationJob objects in the shape described under TranslationJob; the example above elides agent_run.steps and quality_gate for brevity.

Errors

GET /api/translations/{job_id}

Read one translation job, including the full agent run, quality evidence, and review state.

Auth: required. Jobs owned by another tenant return 404.

Path parameters

Example

curl "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

Returns the same TranslationJob shape shown above.

Errors

POST /api/translations/{job_id}/review

Submit a human decision on a job that is waiting for review. This is the endpoint that publishes a translation to the golden store and translation memory.

Auth: required. Ownership is checked before the review is applied, so a caller from another tenant gets 404 and cannot approve, edit, or reject someone else's job.

Path parameters

Request body — ReviewSubmission

Action semantics

What happens on approve/modify

1. job.reviewer, job.review_action, and job.review_notes are recorded, and the open HumanReviewTask is closed with the reviewer's name.
2. The final translation is re-checked against the tenant glossary. The result is written to request.metadata.terminology_gate. If a reviewer publishes output that is not terminology-compliant, the override is recorded at request.metadata.terminology_gate_override ({"overridden": true, "by": …, "action": …, "missing_terms": {…}}).
3. The job is persisted to the golden store; the returned URI is written to request.metadata.golden_uri. If persistence fails, the job is parked as persistence_failed and the request returns 502 (or 409 for an unverified BYOS binding).
4. The approved (source_text, final_translation) pair is dual-written into the tenant's golden translation memory set. TM failures are swallowed — they never fail an approval that already reached the golden store. The same is true of a full memory: once the tenant has reached its segment limit for the language pair across all its sets, a pair whose source is new to the golden set is skipped rather than stored, and the approval still returns 200. A correction to a source already in memory is admitted even at the cap. See Terminology & translation memory. The golden TM set is readable through GET /api/tm/export/golden.
5. Learning signals are extracted onto job.learning_signals. There is no retraining step: the pair written in step 4 is already live, and the next request in that language pair can reuse it on an exact match or draw on it as guidance.
6. The status advances to published (approve) or human_edited (modify), and agent_run.status becomes completed.

Example

curl -X POST "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d/review?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "modify",
    "reviewer": "maria.lopez@acme.example",
    "final_translation": "Su pedido ha sido enviado y llegará el martes.",
    "notes": "Formal register required for this account."
  }'

Response — the updated TranslationJob (fields elided for brevity; the endpoint returns the complete object):

{
  "id": "9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d",
  "final_translation": "Su pedido ha sido enviado y llegará el martes.",
  "reviewer": "maria.lopez@acme.example",
  "review_action": "modify",
  "review_notes": "Formal register required for this account.",
  "status": "human_edited",
  "updated_at": "2026-07-26T14:21:44.902117Z"
}

Errors

GET /api/translations/{job_id}/golden

Download the published translation as a file.

Auth: optional. This endpoint uses the optional identity resolver so that plain browser navigations from the review UI (which cannot send headers) work. When credentials are supplied, normal tenant scoping applies and another tenant's job returns 404.

Path parameters

Query parameters

Response

200 OK with the file as an attachment.

<stem> is <sanitized source name>-<target_lang>. The source name comes from request.metadata.source_document.name when the job came from an upload, otherwise it is source_document — e.g. source_document-es.txt, handbook-fr.docx. Non-alphanumeric characters are replaced with _.

Example

curl -OJ "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d/golden?format=docx&api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

Errors

DELETE /api/translations/{job_id}

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

Auth: admin only — the global_administrator role of the job's own tenant, or the platform operator API key. A non-admin member gets 403; an admin of another tenant gets 404 (deletion never confirms a foreign job id exists). Only the operator key crosses tenants.

The delete cascades. Removed along with the job record:

• the golden system-of-record record(s) the job wrote on approval/publish (platform store, and the tenant's own BYOS golden store when one is bound),
• the translation-memory pair the job fed into the tenant's golden-approved-<src>-<tgt> set, matched by normalized source hash. Only that pair is removed — sibling pairs and client TMX imports are never touched. A job that never fed the TM (unapproved, rejected, or published via a TM/glossary fast path that replayed an existing pair) removes no pairs.

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

Learning rows: the response always reports learning_rows_removed: 0 for text jobs. Persisted learning rows carry no job id and the storage is not tenant-keyed, so no row can be tied to a deleted text job with certainty; rather than risk a wrong cross-tenant delete, nothing is removed there.

After deletion, GET /api/translations/{job_id} and the public golden download link GET /api/translations/{job_id}/golden both return 404. Deletion is permanent — there is no undo.

Path parameters

Response

200 OK. Counts report what was actually removed:

{
  "deleted": true,
  "job_id": "9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d",
  "golden_record_deleted": true,
  "tm_pairs_removed": 1,
  "learning_rows_removed": 0
}

Example

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

Errors

Schemas

TranslationJob

Returned by POST /api/translations (single or in an array), GET /api/translations, GET /api/translations/{job_id}, and POST /api/translations/{job_id}/review.

Two response shapes. A platform operator (the operator API key, or a designated operator session) gets the stored job exactly as written. Every other caller — tenant API keys and sessions alike, including a per-tenant global_administrator — gets the tenant shape, in which the pipeline's execution telemetry is absent, not null:

• no model and no usage on quality_assessment, refinement or verification; their score, issues[], reasoning, created_at — and refined_translation, passed, checks, risk_flags — are unchanged;
• no metadata object anywhere under agent_run — not on the run, its steps[], their tool_calls[], or their decisions[] — while the narrative those carry (names, statuses, input/output summaries, decision rationale, timestamps) stays;
• agent_run.quality_gate.metadata keeps assessment_score, verification_score, verification_passed, risk_flags, trigger_codes, terminology_gate, repaired and fast_path, but not the operator-only execution trace;
• no candidate_models echoed back in request.metadata.

Content, reviews, learning signals, scores and reasoning are identical in both shapes, and nothing withheld is billing data: billing is metered on source characters, weighted per language pair (see Limits), never on the token counts these fields carry. The tenant shape is the one /openapi.json publishes for these routes, and every example on this page shows it. See Who sees the token ledger.

Two nested objects matter most when deciding what to do next:

• agent_run.quality_gate (QualityGate) — decision is pass, needs_human, or fail; score and threshold are the numbers the decision was made on; triggers[] lists everything the gate raised and reasons[] is their messages, one per trigger and in the same order. Both are stamped whatever the decision was, so they are not a review signal: a pass gate can carry a non-empty reasons[] and triggers[] — only a blocking trigger forces review, while a warning one (terminology_uncertainty, risk_flag) rides along on a job that publishes autonomously, and a fast-path pass carries a one-line reasons[] with triggers[] empty. Branch on decision and on status, never on whether these arrays are empty. metadata carries assessment_score, verification_score, verification_passed, risk_flags, trigger_codes, terminology_gate, repaired, fast_path when a fast path served the job, and — for an operator only — the execution trace.
• agent_run.human_review_task (HumanReviewTask) — present when a human is required.

HumanReviewTask

Human-review trigger codes (HumanReviewTrigger.code, each with severity of info, warning, or blocking): policy_required, low_quality_score, critical_issue, terminology_uncertainty, terminology_noncompliant, sensitive_content, high_repair_delta, verification_failed, risk_flag.

QualityIssue

Appears as quality_assessment.issues[], refinement.issues[], and verification.issues[]. Both enums are load-bearing: the autonomous-publish gate refuses to ship a candidate carrying any issue with severity: "critical".

AgentStep, ToolTrace, AgentDecision

agent_run.steps[] is the workflow trace — one AgentStep per node the run executed. Read it for observability; do not branch product logic on step names, which are not part of the compatibility contract.

AgentStep:

ToolTrace: id, tool_name, status (same five values as AgentStep.status, default completed), input_summary, output_summary, error, started_at, completed_at, plus metadata (operator only).

AgentDecision: id, label, outcome, rationale (string | null), confidence (number 0–1 | null), created_at, plus metadata (operator only). The fast-path outcomes named elsewhere on this page — glossary_exact_held, tm_exact_noncompliant, tm_exact_held — appear here as outcome values.

Request metadata

metadata is an open object, but the pipeline reads a specific set of keys. Anything else round-trips untouched.

The same forced-review behavior is triggered by domain values finance, financial, healthcare, legal, medical, pharma.

Keys the pipeline writes back into request.metadata on the returned job — treat them as read-only:

Supported languages

source_lang and target_lang are validated against a fixed allowlist at the API boundary and again on the model. 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.

en, es, fr, de, it, pt-BR, pt-PT, nl, zh-Hans, zh-Hant, ja, ko, ar, ru, hi, tr, vi, th, id

Batch submission

A JSON body containing inputs is parsed as a batch. One TranslationRequest is created per (input × target) pair, each is submitted through the full pipeline, and the endpoint responds with a JSON array of TranslationJob objects in submission order. The batch request body is not part of the generated OpenAPI schema — the endpoint accepts an untyped body and dispatches on its contents, so inputs and everything under it is documented here and nowhere else. The batch response is declared: the 200 schema for POST /api/translations is anyOf a single job and an array of jobs, so a generated client already has the array case.

These map onto the identically named TranslationRequest fields and carry the same functional/inert split — TextType, Tone and Gender steer the baseline; the other three are accepted for wire compatibility and ignored.

Batch bodies do not carry domain or metadata; per-request metadata knobs (min_quality_score, candidate_models, …) are only available on the single-text shape.

curl -X POST "https://trueidiom.com/api/translations?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-notes-2026-07" \
  -d '{
    "inputs": [
      {
        "Text": "Two-factor authentication is now required for all admins.",
        "Language": "en",
        "TextType": "Plain",
        "Targets": [
          { "Language": "fr" },
          { "Language": "de" }
        ]
      },
      {
        "Text": "Export your invoices from the billing page.",
        "Language": "en",
        "Targets": [{ "Language": "ja" }]
      }
    ]
  }'

The example creates three jobs. Language validation for batch payloads happens when the batch expands into individual requests: an unsupported code returns 422 with the underlying validation error text.

With an Idempotency-Key header, each expanded request gets <header value>:<index> (release-notes-2026-07:0, :1, :2) so a retried batch collapses onto the same three jobs.

Idempotency

Set Idempotency-Key: <value> on POST /api/translations, or send idempotency_key in the body (the header only fills in a body field that is absent). A submission whose key already belongs to a job returns that existing job unchanged, with no new pipeline work and nothing further metered or billed. Keys are stored per job and enforced atomically — with the Postgres job store, by a partial unique index shared across app instances.

A replay is still admission-checked. The subscription/trial gate and the character-budget gates run on the way in, before the key is looked up, and they weigh the replayed payload as if it were new work. Close to your monthly allowance or your remaining trial balance, a replay can therefore come back 429 or 402 even though serving it from the stored job would have cost nothing — and a subscription that lapsed between the first call and the retry refuses the retry outright. Nothing is metered when that happens and the stored job is untouched: the same key returns it once there is headroom again.

Limits

These are the documented constraints on a submission.

Dense-script weighting. The two character budgets above are not raw counts. On a language pair where either side is zh-Hans, zh-Hant, ja, ko, th or hi, each source character counts as 3.5 by default; every other pair counts 1:1. That weighted number is what draws down the monthly allowance and the trial grant, what your recorded usage shows, and what the 429 and 402 gates evaluate before any work starts — so a 10,000-character English-to-Japanese submission is admitted, metered and reported as 35,000. A batch weighs each (input, target) pair on its own, so one submission can mix weighted and unweighted destinations. The MAX_SOURCE_CHARS ceiling in the first row is the exception: it bounds the raw length of the text you send, unweighted. Tenants & billing carries the full treatment.

Quality score

Every non-fast-path job is scored 0–100 for translation quality. The score you read on the job is quality_assessment.score; the score the gate acted on is agent_run.quality_gate.score, and the bar it was compared against is agent_run.quality_gate.threshold.

How the gate decides.

1. The baseline is scored once, together with a deterministic glossary-compliance check.
2. Pass — score ≥ threshold, terminology compliant, no critical issue — the translation ships as-is. No repair, no verification.
3. Fail — the translation is automatically repaired against the assessment and the tenant's terminology and translation-memory guidance, then scored again. This repeats up to the retry limit, and the best-scoring candidate wins, so a repair can never ship a regression. refinement is populated.
4. A candidate that went through repair is checked once more before the review gate runs. verification is populated.

Autonomous publish (quality_gate.decision == "pass", job goes straight to published) requires: score ≥ threshold, terminology compliant, no critical issue, no blocking trigger, and the request not marked sensitive/regulated. If a repair happened, it additionally requires verification.passed, verification.score ≥ threshold, and that the repaired text did not diverge drastically from the baseline. Otherwise the job lands in awaiting_review with a HumanReviewTask explaining why.

What a caller can set per request.

Raising min_quality_score makes autonomous publication less likely and human review more likely; lowering it does the opposite.

Two deterministic fast paths skip scoring entirely. When the whole source segment is itself a glossary entry (fast_path: "glossary_exact"), or when a 100% translation-memory match is terminology-compliant (fast_path: "tm_exact"), the stored target is returned verbatim, with no new translation work: status is published, quality_gate.score is 100.0, metadata.provenance.fast_path records which path fired, and nothing is written to the golden store or TM (the pair already lives there). A request marked sensitive/regulated never takes a fast path — it falls through to the gated pipeline and human review.

End-to-end example

1. Submit

curl -X POST "https://trueidiom.com/api/translations?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kb-article-338-fr" \
  -d '{
    "source_text": "Contact support before disabling two-factor authentication.",
    "source_lang": "en",
    "target_lang": "fr",
    "domain": "software",
    "metadata": { "min_quality_score": 92 }
  }'

The response is the completed job. Read status and agent_run.quality_gate.decision:

{
  "id": "e05b7d1c93af4266b8d5c0a17e42f9b3",
  "status": "awaiting_review",
  "baseline_translation": "Contactez l'assistance avant de désactiver l'authentification à deux facteurs.",
  "final_translation": "Contactez le support avant de désactiver l'authentification à deux facteurs.",
  "agent_run": {
    "status": "waiting_for_human",
    "quality_gate": {
      "decision": "needs_human",
      "score": 88.0,
      "threshold": 92.0,
      "reasons": ["Quality score is below the review threshold."],
      "triggers": [
        {
          "code": "low_quality_score",
          "severity": "warning",
          "message": "Quality score is below the review threshold.",
          "evidence": { "score": 88.0, "threshold": 92.0 }
        }
      ]
    },
    "human_review_task": {
      "status": "open",
      "reason": "Human review requested: 1 warning trigger(s).",
      "question": "Should this fr translation be approved as-is, edited before publishing, or rejected?",
      "requested_actions": ["save", "approve", "modify", "reject"]
    }
  }
}

The low_quality_score trigger here is warning severity, and a warning does not by itself force review — what sent this job to a human is the score sitting below the threshold the request asked for. A gate that published autonomously can carry warning triggers and their reasons in exactly this shape, so read decision and status rather than testing whether the arrays are empty.

2. Re-read the job (any time, from any process)

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

Or pull the whole review queue:

curl -G "https://trueidiom.com/api/translations?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  --data-urlencode "status=awaiting_review"

3. Review

curl -X POST "https://trueidiom.com/api/translations/e05b7d1c93af4266b8d5c0a17e42f9b3/review?api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "modify",
    "reviewer": "jean.dupont@acme.example",
    "final_translation": "Contactez l'\''assistance avant de désactiver l'\''authentification à deux facteurs.",
    "notes": "House style uses \"assistance\", not \"support\"."
  }'

The response comes back with "status": "human_edited", "review_action": "modify", a golden_uri in request.metadata, and a reviewer_edit entry in learning_signals.

4. Fetch the golden translation

curl "https://trueidiom.com/api/translations/e05b7d1c93af4266b8d5c0a17e42f9b3/golden?format=txt&api-version=2026-09-01" \
  -H "X-API-Key: $TRUEIDIOM_API_KEY"

Contactez l'assistance avant de désactiver l'authentification à deux facteurs.

The same corrected pair is now in the tenant's golden translation memory, where later jobs reuse it verbatim on an exact match and draw on it for close ones. Export it with GET /api/tm/export/golden.

Error reference

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

Standard HTTPException responses carry {"detail": "<message>"}. Errors raised inside the pipeline carry {"detail", "error_code", "request_id"}, where request_id echoes the X-Request-ID request header when one was sent.