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. POST /api/translations declares no request body at all, so the single, batch and upload shapes documented here appear nowhere in it; 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:

Two endpoints differ. GET /api/translations/{job_id}/golden also accepts the browser session cookie (ll_session), which is what the review page's download links carry. DELETE /api/translations/{job_id} takes an administrator's access token or session cookie, or the platform operator key — never a tenant API key. See each endpoint.

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}, POST /api/translations/{job_id}/review, GET /api/translations/{job_id}/golden and DELETE /api/translations/{job_id} 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
    }
  }'

import os
import requests

resp = requests.post(
    "https://trueidiom.com/api/translations?api-version=2026-09-01",
    headers={
        "X-API-Key": os.environ["TRUEIDIOM_API_KEY"],
        "Idempotency-Key": "order-confirm-7741-es",
    },
    json={
        "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},
    },
    timeout=180,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])

// Node 18+
const res = await fetch("https://trueidiom.com/api/translations?api-version=2026-09-01", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TRUEIDIOM_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-confirm-7741-es",
  },
  body: JSON.stringify({
    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 },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const job = await res.json();
console.log(job.id, job.status);

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 (upstream translation capacity is saturated — retry after a pause), 503 transient_error (the model provider was unavailable — retry), 422 content_filtered (the model provider's content policy refused the text — the same text is refused again on every retry), and 404 not_found when the job was deleted while its pipeline ran (see DELETE /api/translations/{job_id}). A layout-document upload with wait set runs the document pipeline inline and can also return its errors, among them 429 quota_exceeded and 504 stage_timeout — see Documents. Any other failure is an unexpected internal one: 500 with {"detail": "internal error", "error_code": "internal_error", "request_id": "<id>"} and the same id in the X-Request-ID header. A job whose pipeline raised is saved with status: "failed" and can still be read with GET /api/translations/{job_id}; resending its Idempotency-Key re-runs it.

Order of checks. The translation switch (503), the declared body size of a JSON or raw-body submission (413), credentials (401), then the body itself — 400 for JSON that does not parse or is not an object, 422 for an unsupported source_lang or target_lang (a batch's languages are checked with the rest of the batch, below) — come first, so a malformed request is told so even by a tenant that could not pay for it. A keyed retry of work that already exists is answered next (Idempotency). Then billing (402), the monthly allowance (429) and the tenant's own storage (409/503); the remaining payload checks — source length and batch size (413), blank text (400), the request model (422) — run after those.

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": null
}

output_file is always null: no output file is written, and the key stays only so the response shape does not change within this API version. To retrieve translated content, read each id in job_ids with GET /api/translations/{job_id} or download it from GET /api/translations/{job_id}/golden.

Pages run in order, and each is billed as it completes. If a page fails, the request returns that page's error; the pages before it are kept, billed and readable. With an Idempotency-Key — or, on the JSON metadata.source_document shape, an idempotency_key in the body, which takes precedence — page n is keyed <value>:n (counting from 1), so a retry with the same key returns the finished pages and runs the rest.

413 document exceeds MAX_BATCH_ITEMS when split into pages is returned when the page count exceeds 50; 400 source_document has no textual content when an upload yields no text (a blank source_text on the JSON metadata.source_document shape gets 400 source_document has no translatable content).

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"

import os
import requests

resp = requests.get(
    "https://trueidiom.com/api/translations?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    params={"status": "awaiting_review"},
    timeout=60,
)
resp.raise_for_status()
for job in resp.json():
    print(job["id"], job["status"])

// Node 18+
const url = new URL("https://trueidiom.com/api/translations?api-version=2026-09-01");
url.searchParams.set("status", "awaiting_review");

const res = await fetch(url, {
  headers: { "X-API-Key": process.env.TRUEIDIOM_API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
for (const job of await res.json()) {
  console.log(job.id, job.status);
}

[
  {
    "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"

import os
import requests

resp = requests.get(
    "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job["status"], job["final_translation"])

// Node 18+
const res = await fetch(
  "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d?api-version=2026-09-01",
  { headers: { "X-API-Key": process.env.TRUEIDIOM_API_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const job = await res.json();
console.log(job.status, job.final_translation);

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); it publishes on its own once storage is healthy again — see persistence_failed.
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, or an approve that published a reviewer's text), 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."
  }'

import os
import requests

resp = requests.post(
    "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d/review?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    json={
        "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.",
    },
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job["status"], job["review_action"])

// Node 18+
const res = await fetch(
  "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d/review?api-version=2026-09-01",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TRUEIDIOM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      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.",
    }),
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const job = await res.json();
console.log(job.status, job.review_action);

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: required — tenant credentials (a tenant API key or a bearer access token), or the browser session cookie (ll_session), which is what the review page's download links carry. With none of these the request is refused with 401 missing or invalid tenant credentials before the job is looked up, so an anonymous caller learns nothing about which ids exist; credentials that are sent but do not resolve (a bad token, or an X-Tenant-ID the credential does not belong to) are refused the same way. Another tenant's job returns 404. Only the platform operator crosses tenants.

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. Sanitizing drops the name's extension and replaces each run of characters other than ASCII letters, digits, ., _ and - with a single _; a name with nothing left becomes source_document.

For an Arabic, Persian or Urdu target, the docx paragraphs are set right to left.

Example

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

import os
import requests

resp = requests.get(
    "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d/golden?format=docx&api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"]},
    timeout=120,
)
resp.raise_for_status()
# curl -OJ saves under the server-supplied filename; name it yourself here.
with open("translation.docx", "wb") as handle:
    handle.write(resp.content)

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

const res = await fetch(
  "https://trueidiom.com/api/translations/9c2f41b0a7d84e5b8c1d3e6f0a2b4c8d/golden?format=docx&api-version=2026-09-01",
  { headers: { "X-API-Key": process.env.TRUEIDIOM_API_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
// curl -OJ saves under the server-supplied filename; name it yourself here.
await writeFile("translation.docx", Buffer.from(await res.arrayBuffer()));

Errors

DELETE /api/translations/{job_id}

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

Auth: admin only — a signed-in global_administrator of the job's own tenant (bearer access token or the ll_session cookie), or the platform operator API key. A tenant API key cannot delete (401). A non-admin member gets 403; an admin of another tenant gets 404 (deletion never confirms a foreign job id exists). Ownership is judged against the signed-in admin's own tenant — X-Tenant-ID plays no part. Only the platform operator 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.

A job that is still running. A delete that lands while the job's pipeline — or a review of it — is still running is honoured: the job is not re-created when that run finishes, whatever the run wrote to the golden store and translation memory in the meantime is removed as well, and the in-flight POST /api/translations (or POST /api/translations/{job_id}/review) returns 404 with error_code: not_found — translation job <id> was deleted while it was processing (or … was deleted during review). A job deleted while its own POST /api/translations was still running is not billed — unless its golden record had already reached the tenant's own storage (Bring Your Own Storage) before the delete: the customer then holds the translation in their account, so it is billed like any delivered translation, even though the request answered 404. On platform storage the delete removes the only copy, and nothing is billed.

After deletion, GET /api/translations/{job_id} and the golden download 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 $TRUEIDIOM_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 or primary_model 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). A code that is not in the list is rejected by design, regional tags and bare variant bases included — en-US, fr-FR, bare zh, and bare pt all fail. fr is French as written in France and fr-CA is Canadian French.

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

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" }]
      }
    ]
  }'

import os
import requests

batch = {
    "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"}]},
    ]
}
resp = requests.post(
    "https://trueidiom.com/api/translations?api-version=2026-09-01",
    headers={"X-API-Key": os.environ["TRUEIDIOM_API_KEY"],
             "Idempotency-Key": "release-notes-2026-07"},
    json=batch,
    timeout=300,
)
resp.raise_for_status()
for job in resp.json():
    print(job["id"], job["request"]["target_lang"])

// Node 18+
const batch = {
  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" }] },
  ],
};
const res = await fetch("https://trueidiom.com/api/translations?api-version=2026-09-01", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TRUEIDIOM_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "release-notes-2026-07",
  },
  body: JSON.stringify(batch),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
for (const job of await res.json()) {
  console.log(job.id, job.request.target_lang);
}

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.

The expanded requests run in order, and each is billed as it completes. If one fails, the request returns that item's error: the items before it are kept, billed and readable through GET /api/translations, and the items after it never run. A retry with the same key returns the finished items unchanged and runs the rest, re-running the one that failed.

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). Keys are scoped to your tenant: the same value sent by another tenant is a different key and never returns your job. A submission whose key already belongs to one of your jobs returns that job as it stands now — still pending while the original request is running, or further along, such as human_edited after a review — with no new pipeline work and nothing further metered or billed. Two cases re-run the job instead, under the same id: a job that ended failed, and a job left pending for 10 minutes or more because the process running it stopped. Concurrent retries run it once, and it is billed once, when it completes. Keys are enforced atomically, across app instances.

On the batch shape the header is expanded per translation (Batch submission); on a text document, page n is keyed <value>:n, counting from 1 — the header's value, or the body's idempotency_key on the JSON metadata.source_document shape.

A replay that starts no work is answered before the gates. When every job the request names already exists and none of them ended failed or was left stale pending, the stored jobs are returned before the subscription/trial gate, the character-budget gates and the storage-binding check — so a retry is never refused with 402, 429 or 409 for work that has already happened (the retry of a request that took the month's last characters gets its job back). Nothing is metered again. A replay that has to re-run a job — a failed one, or a stale pending one — is new work and passes every gate first, like any submission; refused there, nothing is metered and the stored job is untouched. Malformed bodies and unsupported languages are reported before either.

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, hi, mr or ne, 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 — that input's Language against that target — so one submission can mix weighted and unweighted pairs. 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 text it repaired (the baseline, or the chosen candidate on the multi-candidate path). 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 with no new translation work — verbatim, except that a glossary target follows the segment's casing unless its entry is case-sensitive (an ALL-CAPS segment gets an ALL-CAPS target, and a capitalised segment capitalises a target stored in lowercase), and the whole-segment glossary comparison counts accents and tone marks: 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 is the same id as the X-Request-ID response header — the one you sent, or the generated one — and is never null.