{"openapi":"3.1.0","info":{"title":"TextSetu API","version":"1.2.0","description":"Public REST API for TextSetu. Authenticate with a Personal Access Token (tsu_pat_…) or a project token (tsu_proj_…) via the `Authorization: Bearer <token>` header.\n\n**Authorization is permission-based.** Every token carries an explicit allow-list of RBAC permission keys (e.g. `translation_read`), and each endpoint declares the permission it requires (`x-permission`). A token's effective access is its underlying authority ∩ its allow-list — a PAT is further bounded by its owner's role-based permissions, so it can only narrow, never exceed, what the owner already has. A project token is bound to a single project. There are no coarse read/write/manage scopes.\n\n**Response envelope.** Every endpoint returns `{ \"success\": true, \"data\": … }` on success and `{ \"success\": false, \"error\": { \"code\", \"message\" } }` on failure.\n\n**Rate limit.** 600 requests/minute, keyed by token (or by IP when unauthenticated). Exceeding it returns 429 with the standard error envelope."},"servers":[{"url":"http://api.textsetu.com/api/v1","description":"This server"},{"url":"https://api.textsetu.com/api/v1","description":"Production"},{"url":"/api/v1","description":"This server (self-hosted / same-origin)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Projects","description":"Read project metadata — settings, key separator, and the approval/branching flags that shape how the other endpoints behave."},{"name":"Languages","description":"List and manage a project's target languages. Each language is referenced by its BCP-47 code; the source language is flagged separately."},{"name":"Keys","description":"Create, read, update, and delete translation keys — the identifiers your app looks up. Keys carry metadata (description, tags, screenshot) and hold one value per language."},{"name":"Values","description":"Set the translated string for a single key in a single language. Honors the project's approval workflow — non-approver writes land as `pending_review`."},{"name":"Stats","description":"Per-language completeness and approval progress for a project — the numbers behind the dashboard."},{"name":"Import/Export","description":"Bulk-load source files into a project or export the current translations. Supports the same file formats as the web app."},{"name":"Branches","description":"Work on translations in isolation and merge them back. Branch reads/writes mirror the main endpoints but stage changes as a diff until merge. See the [branching guide](/docs/guides/branches)."},{"name":"Glossary","description":"Manage term bases — approved terminology and its translations — and check a string against them. See the [glossary guide](/docs/guides/glossary)."},{"name":"Translation Memory","description":"Reusable translation stores. Fuzzy-match and concordance-search prior translations to reuse them. See the [translation memory guide](/docs/guides/translation-memory)."},{"name":"Meta","description":"Service-level and cross-cutting endpoints."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token: tsu_pat_… (PAT) or tsu_proj_… (project token). The token's granted RBAC permissions determine access; see each operation's `x-permission`."}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/formats":{"get":{"tags":["Meta"],"summary":"List supported formats","description":"List every import/export file format the platform supports, with its id, name, file extensions, and whether it can carry multiple languages in one file. Use the returned `id` as the `format` in import/export calls — see the [file formats reference](/docs/reference/file-formats). Requires the `read` scope; PATs always qualify.","responses":{"200":{"description":"The catalog of supported file formats.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"formats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Format identifier used in import/export `?format=` params.","examples":["json-nested"]},"name":{"type":"string","description":"Human-readable format name.","examples":["JSON (nested)"]},"extensions":{"type":"array","items":{"type":"string"},"description":"File extensions associated with this format.","examples":[[".json"]]},"multiLanguage":{"type":"boolean","description":"True if a single file of this format can hold multiple languages.","examples":[false]}},"required":["id","name","extensions","multiLanguage"],"additionalProperties":false}}},"required":["formats"],"additionalProperties":false}}}}}}}}},"/projects/{projectId}":{"get":{"tags":["Projects"],"summary":"Get project metadata","description":"Fetch a project's core settings — name, source language, key separator, and whether approval is required. Useful for resolving the key separator before creating keys, or the source language before exporting.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The project's metadata.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","description":"Unique project id.","examples":["proj_9f8e7d6c"]},"name":{"type":"string","description":"Project display name.","examples":["Marketing Site"]},"sourceLanguage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47 code of the source language, or `null` if none is set.","examples":["en"]},"keySeparator":{"type":"string","description":"Delimiter that splits a key into namespace segments.","examples":["."]},"approvalRequired":{"type":"boolean","description":"True if values require approval before they're considered final.","examples":[false]}},"required":["id","name","sourceLanguage","keySeparator","approvalRequired"],"additionalProperties":false}},"required":["project"],"additionalProperties":false}}}}}},"404":{"description":"Project not found."}}}},"/projects/{projectId}/languages":{"get":{"tags":["Languages"],"summary":"List project languages","description":"List the languages configured on the project, including which one is the source language. Each entry resolves its display label from the org language catalog.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The project's configured languages.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique id of this project-language row (UUID).","examples":["pl_1a2b3c4d"]},"projectId":{"type":"string","description":"Id of the project this language belongs to.","examples":["proj_9f8e7d6c"]},"languageCode":{"type":"string","description":"BCP-47 language code, e.g. `en` or `fr`.","examples":["fr"]},"label":{"type":"string","description":"Human-readable language name, resolved from the org language catalog.","examples":["French"]},"isSource":{"type":"boolean","description":"True if this is the project's source (reference) language.","examples":[false]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","projectId","languageCode","label","isSource","createdAt","updatedAt"],"additionalProperties":false}}},"required":["languages"],"additionalProperties":false}}}}}}}},"post":{"tags":["Languages"],"summary":"Add a language (manage)","description":"Add a language to the project. Standard codes resolve to the shared global language; a non-standard code is created as an org custom language. Requires the `manage` scope — adding a language is a project-management operation, above ordinary `write`. PATs need the PROJECT_MANAGE permission — see [roles & permissions](/docs/guides/roles-and-permissions).","x-permission":"project_manage","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"languageCode":{"type":"string","minLength":2,"maxLength":10,"description":"BCP-47 language code to add to the project.","examples":["fr"]},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Display name for the language.","examples":["French"]},"isSource":{"description":"Mark this as the project's source language (only one may be the source).","type":"boolean"}},"required":["languageCode","label"]}}}},"responses":{"201":{"description":"The newly added project language.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"language":{"type":"object","properties":{"id":{"type":"string","description":"Unique id of this project-language row (UUID).","examples":["pl_1a2b3c4d"]},"projectId":{"type":"string","description":"Id of the project this language belongs to.","examples":["proj_9f8e7d6c"]},"languageCode":{"type":"string","description":"BCP-47 language code, e.g. `en` or `fr`.","examples":["fr"]},"label":{"type":"string","description":"Human-readable language name, resolved from the org language catalog.","examples":["French"]},"isSource":{"type":"boolean","description":"True if this is the project's source (reference) language.","examples":[false]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","projectId","languageCode","label","isSource","createdAt","updatedAt"],"additionalProperties":false}},"required":["language"],"additionalProperties":false}}}}}},"500":{"description":"Failed to add the language."}}}},"/projects/{projectId}/stats":{"get":{"tags":["Stats"],"summary":"Per-language completeness","description":"Return the project's total key count plus, for each language, how many keys are translated, missing, and the completion percentage. Pass `?branch=` to compute the stats against a branch overlay instead of main — see the [branching guide](/docs/guides/branches).","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"responses":{"200":{"description":"Total key count and per-language completeness.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"totalKeys":{"type":"integer","description":"Total number of keys in the project (or branch overlay).","examples":[150]},"languages":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code these stats are for.","examples":["fr"]},"label":{"type":"string","description":"Human-readable language name.","examples":["French"]},"translated":{"type":"integer","description":"Number of keys with a value in this language.","examples":[128]},"total":{"type":"integer","description":"Total number of keys in the project.","examples":[150]},"missing":{"type":"integer","description":"Keys with no value in this language (`total` − `translated`).","examples":[22]},"percentage":{"type":"integer","description":"Completion percentage for this language (0–100).","examples":[85]}},"required":["languageCode","label","translated","total","missing","percentage"],"additionalProperties":false},"description":"Per-language completeness breakdown."}},"required":["totalKeys","languages"],"additionalProperties":false}}}}}},"400":{"description":"The target branch is not valid for this project."},"404":{"description":"Project not found."}}}},"/projects/{projectId}/keys":{"get":{"tags":["Keys"],"summary":"List / search keys (paginated)","description":"Return a paginated page of a project's translation keys, each with its values across every language. Combine the query params to search by name or source text, filter by tag / status / outdated, and sort. Pass `?branch=` to read a branch's overlay instead of main — see the [branching guide](/docs/guides/branches).","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"page","in":"query","description":"1-based page number.","schema":{"default":1,"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Page size (1–200).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"search","in":"query","description":"Substring match on key name.","schema":{"type":"string"}},{"name":"scope","in":"query","description":"Key-namespace prefix filter.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Filter by one or more tags.","schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},{"name":"language","in":"query","description":"Restrict value-based filters to this language.","schema":{"type":"string"}},{"name":"sourceSearch","in":"query","description":"Substring match on the source-language value.","schema":{"type":"string"}},{"name":"outdated","in":"query","description":"Only keys with at least one outdated value.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},{"name":"status","in":"query","description":"Only keys with at least one value in this approval status.","schema":{"type":"string","enum":["approved","pending_review","draft"]}},{"name":"sort","in":"query","description":"Field to sort by.","schema":{"default":"key","type":"string","enum":["key","createdAt","updatedAt"]}},{"name":"order","in":"query","description":"Sort direction.","schema":{"default":"asc","type":"string","enum":["asc","desc"]}},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"responses":{"200":{"description":"A page of keys with their per-language values.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique key id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this key belongs to.","examples":["proj_9f8e7d6c"]},"key":{"type":"string","description":"The lookup identifier your app resolves, e.g. `home.hero.title`.","examples":["home.hero.title"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional note giving translators context for this key.","examples":["Headline shown on the landing page hero."]},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels for filtering and organizing keys.","examples":[["marketing","landing"]]},"isPlural":{"type":"boolean","description":"True when the key holds CLDR plural forms rather than a single string.","examples":[false]},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of an attached screenshot showing the key in context, if any.","examples":[null]},"screenshotFileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Storage id of the attached screenshot, if any.","examples":[null]},"keySource":{"type":"string","enum":["main","branch"],"description":"Whether the effective row comes from `main` or a branch overlay.","examples":["main"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"values":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this value is written in.","examples":["fr"]},"value":{"type":"string","description":"The translated string for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`. Branch overrides are always `draft`.","examples":["approved"]},"pluralForm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CLDR plural category (`one`, `other`, …) for plural keys on main; `null` for singular keys and all branch values.","examples":[null]},"isOutdated":{"type":"boolean","description":"True when the source string changed after this value was last set.","examples":[false]}},"required":["languageCode","value","status","pluralForm","isOutdated"],"additionalProperties":false}}},"required":["id","projectId","key","description","tags","isPlural","screenshotUrl","screenshotFileId","keySource","createdAt","updatedAt","values"],"additionalProperties":false}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}},"required":["keys","total","page","limit"],"additionalProperties":false}}}}}}}},"post":{"tags":["Keys"],"summary":"Create a key (write)","description":"Add a new key to the project. You may seed its values in one call via the `values` map. On a protected main branch, target a branch with `?branch=` instead — direct main writes are rejected.\n\n**Constraints:**\n- The key must be well-formed: each segment (split on the project's key separator) may contain only letters, digits, `_` and `-`.\n- Creating a key that already exists returns 409.","x-permission":"translation_create","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":500,"description":"Lookup identifier. Segments (split on the project separator) may contain only letters, digits, `_` and `-`.","examples":["home.hero.title"]},"description":{"description":"Optional translator-facing context for the key.","examples":["Headline shown on the landing page hero."],"type":"string","maxLength":1000},"tags":{"description":"Up to 20 labels for filtering and organizing keys.","examples":[["marketing","landing"]],"maxItems":20,"type":"array","items":{"type":"string","maxLength":50}},"isPlural":{"description":"Set true to make this a plural key (values are keyed by CLDR plural form).","type":"boolean"},"values":{"description":"Optional initial values, keyed by language code. Singular: `{ \"fr\": \"…\" }`; plural: `{ \"fr\": { \"one\": \"…\", \"other\": \"…\" } }`.","examples":[{"en":"Welcome","fr":"Bienvenue"}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","propertyNames":{"type":"string","enum":["zero","one","two","few","many","other"]},"additionalProperties":{"type":"string"},"required":["zero","one","two","few","many","other"]}]}}},"required":["key"]}}}},"responses":{"201":{"description":"The created key's metadata.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","description":"Unique key id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this key belongs to.","examples":["proj_9f8e7d6c"]},"key":{"type":"string","description":"The lookup identifier your app resolves, e.g. `home.hero.title`.","examples":["home.hero.title"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional note giving translators context for this key.","examples":["Headline shown on the landing page hero."]},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels for filtering and organizing keys.","examples":[["marketing","landing"]]},"isPlural":{"type":"boolean","description":"True when the key holds CLDR plural forms rather than a single string.","examples":[false]},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of an attached screenshot showing the key in context, if any.","examples":[null]},"screenshotFileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Storage id of the attached screenshot, if any.","examples":[null]},"keySource":{"type":"string","enum":["main","branch"],"description":"Whether the effective row comes from `main` or a branch overlay.","examples":["main"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","projectId","key","description","tags","isPlural","screenshotUrl","screenshotFileId","keySource","createdAt","updatedAt"],"additionalProperties":false}},"required":["key"],"additionalProperties":false}}}}}},"400":{"description":"Malformed key or invalid body."},"403":{"description":"Direct edits to a protected main branch are blocked — target a branch."},"404":{"description":"Project not found."},"409":{"description":"A key with this name already exists."}}}},"/projects/{projectId}/keys/{keyId}":{"get":{"tags":["Keys"],"summary":"Get a key","description":"Fetch a single key by id, with its values across all languages. With `?branch=` the branch overlay is returned and keys deleted on the branch are reported as not found.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation key id (UUID)."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"responses":{"200":{"description":"The key and its per-language values.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","description":"Unique key id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this key belongs to.","examples":["proj_9f8e7d6c"]},"key":{"type":"string","description":"The lookup identifier your app resolves, e.g. `home.hero.title`.","examples":["home.hero.title"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional note giving translators context for this key.","examples":["Headline shown on the landing page hero."]},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels for filtering and organizing keys.","examples":[["marketing","landing"]]},"isPlural":{"type":"boolean","description":"True when the key holds CLDR plural forms rather than a single string.","examples":[false]},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of an attached screenshot showing the key in context, if any.","examples":[null]},"screenshotFileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Storage id of the attached screenshot, if any.","examples":[null]},"keySource":{"type":"string","enum":["main","branch"],"description":"Whether the effective row comes from `main` or a branch overlay.","examples":["main"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"values":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this value is written in.","examples":["fr"]},"value":{"type":"string","description":"The translated string for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`. Branch overrides are always `draft`.","examples":["approved"]},"pluralForm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CLDR plural category (`one`, `other`, …) for plural keys on main; `null` for singular keys and all branch values.","examples":[null]},"isOutdated":{"type":"boolean","description":"True when the source string changed after this value was last set.","examples":[false]}},"required":["languageCode","value","status","pluralForm","isOutdated"],"additionalProperties":false}}},"required":["id","projectId","key","description","tags","isPlural","screenshotUrl","screenshotFileId","keySource","createdAt","updatedAt","values"],"additionalProperties":false}},"required":["key"],"additionalProperties":false}}}}}},"404":{"description":"Key not found (or hidden on the target branch)."}}},"patch":{"tags":["Keys"],"summary":"Update a key (write)","description":"Partial update — omitted fields are left unchanged. On a branch (`?branch=`) the change is staged as a metadata delta rather than applied to main.","x-permission":"translation_update","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation key id (UUID)."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"New key name. Same segment rules as on create.","examples":["home.hero.headline"],"type":"string","minLength":1,"maxLength":500},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Replace the translator-facing context; `null` clears it."},"tags":{"description":"Replace the key's tags.","maxItems":20,"type":"array","items":{"type":"string","maxLength":50}},"isPlural":{"description":"Toggle plural handling for the key.","type":"boolean"},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of a context screenshot; `null` removes it."},"screenshotFileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Storage id of a context screenshot; `null` removes it."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","description":"Unique key id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this key belongs to.","examples":["proj_9f8e7d6c"]},"key":{"type":"string","description":"The lookup identifier your app resolves, e.g. `home.hero.title`.","examples":["home.hero.title"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional note giving translators context for this key.","examples":["Headline shown on the landing page hero."]},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels for filtering and organizing keys.","examples":[["marketing","landing"]]},"isPlural":{"type":"boolean","description":"True when the key holds CLDR plural forms rather than a single string.","examples":[false]},"screenshotUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public URL of an attached screenshot showing the key in context, if any.","examples":[null]},"screenshotFileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Storage id of the attached screenshot, if any.","examples":[null]},"keySource":{"type":"string","enum":["main","branch"],"description":"Whether the effective row comes from `main` or a branch overlay.","examples":["main"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","projectId","key","description","tags","isPlural","screenshotUrl","screenshotFileId","keySource","createdAt","updatedAt"],"additionalProperties":false}},"required":["key"],"additionalProperties":false}}}}}},"403":{"description":"Forbidden / main branch protected"},"404":{"description":"Not found"}}},"delete":{"tags":["Keys"],"summary":"Delete a key (write)","description":"Permanently remove a key and all of its values. On a branch (`?branch=`) the deletion is staged as part of the branch diff and only takes effect on merge. On a protected main branch, direct deletes are rejected — target a branch.","x-permission":"translation_delete","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation key id (UUID)."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"responses":{"200":{"description":"Confirmation message.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation of the action.","examples":["Key deleted"]}},"required":["message"],"additionalProperties":false}}}}}},"403":{"description":"Direct edits to a protected main branch are blocked — target a branch."},"404":{"description":"Key not found."}}}},"/projects/{projectId}/keys/{keyId}/values/{lang}":{"put":{"tags":["Values"],"summary":"Upsert a translation value (write)","description":"Set the translation for one key in one language, creating the value if it doesn't exist. If the project requires approval, a write by a non-approver lands as `pending_review`; approvers' writes are auto-approved — see the [approval workflow](/docs/guides/approval-workflow). Pass `?branch=` to stage the change on a branch.\n\n**Constraints:**\n- For a Translator-scoped token, the target language must be within the token owner's assigned languages, or the request is rejected with 403.\n- For a plural key, pass `pluralForm` (`one`, `other`, …) to target a specific form.","x-permission":"translation_update","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation key id (UUID)."},{"name":"lang","in":"path","required":true,"schema":{"type":"string"},"description":"Language code, optionally with a file extension (`fr` or `fr.json`)."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"The translated string to store.","examples":["Bienvenue"]},"pluralForm":{"description":"For plural keys, the CLDR plural form this value targets (`one`, `other`, …).","examples":["other"],"type":"string","enum":["zero","one","two","few","many","other"]}},"required":["value"]}}}},"responses":{"200":{"description":"The upserted value.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"value":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this value is written in.","examples":["fr"]},"value":{"type":"string","description":"The translated string for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`. Branch overrides are always `draft`.","examples":["approved"]},"pluralForm":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CLDR plural category (`one`, `other`, …) for plural keys on main; `null` for singular keys and all branch values.","examples":[null]},"isOutdated":{"type":"boolean","description":"True when the source string changed after this value was last set.","examples":[false]}},"required":["languageCode","value","status","pluralForm","isOutdated"],"additionalProperties":false}},"required":["value"],"additionalProperties":false}}}}}},"403":{"description":"Language out of scope, or direct edits to a protected main branch are blocked."},"404":{"description":"Project or key not found."}}}},"/projects/{projectId}/sources":{"post":{"tags":["Import/Export"],"summary":"Import source/translation files (write)","description":"Additive import of parsed files. With `?branch=`, values are staged on the branch (no approval workflow) and plural forms are flattened to their `other` form (branch values are single-string).\n\nThe request body is capped at 10 MB (`bodyLimit`); a larger payload is rejected with 413. Split the files across several calls.","x-permission":"translation_create","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","minLength":1},"files":{"minItems":1,"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1},"languageCode":{"type":"string","minLength":1},"contentBase64":{"type":"string"}},"required":["path","languageCode","contentBase64"]}}},"required":["format","files"]}}}},"responses":{"200":{"description":"Counts of what the import added, updated, and skipped.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"keysAdded":{"type":"integer","description":"New keys created by this import.","examples":[12]},"valuesAdded":{"type":"integer","description":"New translation values written.","examples":[40]},"valuesUpdated":{"type":"integer","description":"Existing values overwritten with a new string.","examples":[8]},"valuesSkipped":{"type":"integer","description":"Values left unchanged (identical to what was already stored).","examples":[3]},"keysDeleted":{"description":"Keys removed because they were absent from the import (main imports only).","examples":[0],"type":"integer"},"valuesReverted":{"description":"Branch overrides dropped because they converged back onto main (branch imports only).","examples":[1],"type":"integer"},"branchId":{"description":"The branch the import targeted, echoed back (present only for branch imports).","examples":["br_5c1a9e2f"],"type":"string"},"pluralFormsFlattened":{"description":"Plural maps collapsed to their `other` form because branch values are single-string (branch imports only).","examples":[2],"type":"integer"}},"required":["keysAdded","valuesAdded","valuesUpdated","valuesSkipped"],"additionalProperties":false}}}}}},"400":{"description":"Invalid format / file / base64"},"403":{"description":"Forbidden / main branch protected"},"404":{"description":"Not found"},"413":{"description":"Request body exceeds the 10 MB limit"}}}},"/projects/{projectId}/translations":{"get":{"tags":["Import/Export"],"summary":"Export translations as per-language files","description":"Render the project's translations to files in the chosen format — one file per language, with each file's contents base64-encoded in `contentBase64`. Use `?languages=` to export a subset and `?status=approved` to ship only approved strings; `?branch=` exports a branch's overlay. See the [import/export guide](/docs/guides/import-export) and the supported [file formats](/docs/reference/file-formats).\n\n**Constraints:**\n- One file is emitted per target language, so the response shape is uniform across single- and multi-language formats.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"format","in":"query","required":true,"description":"Target format id, e.g. `json-nested`. See `GET /projects/{projectId}/formats`.","schema":{"type":"string","minLength":1}},{"name":"languages","in":"query","description":"Comma-separated language codes, e.g. `fr,de`. Omitted = all project languages.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Only include values in this approval status (e.g. `approved`).","schema":{"default":"approved","type":"string","enum":["all","approved","pending_review","draft"]}},{"name":"branch","in":"query","schema":{"type":"string"},"description":"Target an open translation branch instead of main. Required when the project's main branch is protected."}],"responses":{"200":{"description":"One rendered file per language, base64-encoded.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Suggested file path/name for this language's output.","examples":["fr.json"]},"languageCode":{"type":"string","description":"BCP-47 code of the language this file contains.","examples":["fr"]},"contentBase64":{"type":"string","description":"The rendered file contents, base64-encoded (decode to get the raw file).","examples":["eyJob21lIjp7InRpdGxlIjoiQmllbnZlbnVlIn19"]}},"required":["path","languageCode","contentBase64"],"additionalProperties":false}}},"required":["files"],"additionalProperties":false}}}}}},"400":{"description":"Unknown or unsupported format id."},"404":{"description":"Project or branch not found."}}}},"/projects/{projectId}/branches":{"get":{"tags":["Branches"],"summary":"List branches","description":"List the project's translation branches, each with a diff summary against main. Requires branching to be enabled on the project — see the [branching guide](/docs/guides/branches).","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"status","in":"query","description":"Filter by branch status (`active` or `merged`). Omitted = all.","schema":{"examples":["active"],"type":"string","enum":["active","merged"]}}],"responses":{"200":{"description":"The project's branches with their diff summaries.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"branches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique branch id (UUID).","examples":["b1a2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this branch belongs to.","examples":["proj_9f8e7d6c"]},"name":{"type":"string","description":"Human-readable branch name, unique within the project.","examples":["feature/checkout-copy"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text note describing the branch's purpose.","examples":["Reworked checkout wording for the Q1 launch."]},"status":{"type":"string","description":"Lifecycle state: `active` while open, `merged` once merged into main.","examples":["active"]},"isApproved":{"type":"boolean","description":"True once the merge has been approved (set when merge approval is granted).","examples":[false]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"mergedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the branch was merged into main (ISO 8601); `null` until merged.","examples":[null]},"stats":{"type":"object","properties":{"keysAdded":{"type":"integer","description":"Number of keys created on the branch that don't exist on main.","examples":[4]},"keysDeleted":{"type":"integer","description":"Number of main keys staged for deletion by the branch.","examples":[1]},"valuesModified":{"type":"integer","description":"Number of translation values the branch overrides relative to main.","examples":[12]},"languagesAdded":{"type":"integer","description":"Number of languages added on the branch but not present on main.","examples":[1]},"languagesDeleted":{"type":"integer","description":"Number of main languages staged for removal by the branch.","examples":[0]}},"required":["keysAdded","keysDeleted","valuesModified","languagesAdded","languagesDeleted"],"additionalProperties":false,"description":"Diff summary of the branch against main."}},"required":["id","projectId","name","description","status","isApproved","createdAt","mergedAt","stats"],"additionalProperties":false}}},"required":["branches"],"additionalProperties":false}}}}}},"400":{"description":"Branching is not enabled for this project."}}},"post":{"tags":["Branches"],"summary":"Create a branch (write)","description":"Create a new branch off main. Branch edits are staged as an overlay and only reach main on merge — see the [branching guide](/docs/guides/branches).\n\n**Constraints:**\n- Requires branching to be enabled on the project.\n- The branch name must be unique in the project and match the allowed name pattern.","x-permission":"translation_create","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9][a-z0-9-]*$"},"description":{"type":"string","maxLength":500}},"required":["name"]}}}},"responses":{"201":{"description":"The created branch (with zero diff stats).","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"branch":{"type":"object","properties":{"id":{"type":"string","description":"Unique branch id (UUID).","examples":["b1a2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this branch belongs to.","examples":["proj_9f8e7d6c"]},"name":{"type":"string","description":"Human-readable branch name, unique within the project.","examples":["feature/checkout-copy"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text note describing the branch's purpose.","examples":["Reworked checkout wording for the Q1 launch."]},"status":{"type":"string","description":"Lifecycle state: `active` while open, `merged` once merged into main.","examples":["active"]},"isApproved":{"type":"boolean","description":"True once the merge has been approved (set when merge approval is granted).","examples":[false]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"mergedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the branch was merged into main (ISO 8601); `null` until merged.","examples":[null]},"stats":{"type":"object","properties":{"keysAdded":{"type":"integer","description":"Number of keys created on the branch that don't exist on main.","examples":[4]},"keysDeleted":{"type":"integer","description":"Number of main keys staged for deletion by the branch.","examples":[1]},"valuesModified":{"type":"integer","description":"Number of translation values the branch overrides relative to main.","examples":[12]},"languagesAdded":{"type":"integer","description":"Number of languages added on the branch but not present on main.","examples":[1]},"languagesDeleted":{"type":"integer","description":"Number of main languages staged for removal by the branch.","examples":[0]}},"required":["keysAdded","keysDeleted","valuesModified","languagesAdded","languagesDeleted"],"additionalProperties":false,"description":"Diff summary of the branch against main."}},"required":["id","projectId","name","description","status","isApproved","createdAt","mergedAt","stats"],"additionalProperties":false}},"required":["branch"],"additionalProperties":false}}}}}},"400":{"description":"Branching is not enabled for this project."},"403":{"description":"Token has no associated user for attribution."}}}},"/projects/{projectId}/branches/{branchId}":{"get":{"tags":["Branches"],"summary":"Get a branch (with diff summary)","description":"Fetch a single branch by id, including its computed diff summary (keys added/deleted, values modified, languages added/deleted) against main.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branchId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation branch id (UUID)."}],"responses":{"200":{"description":"The branch and its diff summary.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"branch":{"type":"object","properties":{"id":{"type":"string","description":"Unique branch id (UUID).","examples":["b1a2c3d4-0000-4000-8000-000000000001"]},"projectId":{"type":"string","description":"Id of the project this branch belongs to.","examples":["proj_9f8e7d6c"]},"name":{"type":"string","description":"Human-readable branch name, unique within the project.","examples":["feature/checkout-copy"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text note describing the branch's purpose.","examples":["Reworked checkout wording for the Q1 launch."]},"status":{"type":"string","description":"Lifecycle state: `active` while open, `merged` once merged into main.","examples":["active"]},"isApproved":{"type":"boolean","description":"True once the merge has been approved (set when merge approval is granted).","examples":[false]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"mergedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the branch was merged into main (ISO 8601); `null` until merged.","examples":[null]},"stats":{"type":"object","properties":{"keysAdded":{"type":"integer","description":"Number of keys created on the branch that don't exist on main.","examples":[4]},"keysDeleted":{"type":"integer","description":"Number of main keys staged for deletion by the branch.","examples":[1]},"valuesModified":{"type":"integer","description":"Number of translation values the branch overrides relative to main.","examples":[12]},"languagesAdded":{"type":"integer","description":"Number of languages added on the branch but not present on main.","examples":[1]},"languagesDeleted":{"type":"integer","description":"Number of main languages staged for removal by the branch.","examples":[0]}},"required":["keysAdded","keysDeleted","valuesModified","languagesAdded","languagesDeleted"],"additionalProperties":false,"description":"Diff summary of the branch against main."}},"required":["id","projectId","name","description","status","isApproved","createdAt","mergedAt","stats"],"additionalProperties":false}},"required":["branch"],"additionalProperties":false}}}}}},"400":{"description":"Branch does not belong to this project."},"404":{"description":"Project or branch not found."}}},"delete":{"tags":["Branches"],"summary":"Delete a branch (write)","description":"Permanently delete a branch and discard all of its staged (unmerged) changes. This is a hard delete and cannot be undone; main is unaffected.","x-permission":"translation_delete","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branchId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation branch id (UUID)."}],"responses":{"200":{"description":"Confirmation message.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation message.","examples":["Branch deleted"]}},"required":["message"],"additionalProperties":false}}}}}},"400":{"description":"Branch does not belong to this project."},"404":{"description":"Project or branch not found."}}}},"/projects/{projectId}/branches/{branchId}/conflicts":{"get":{"tags":["Branches"],"summary":"List merge conflicts on a branch","description":"List the merge conflicts recorded for a branch. Conflicts are populated by [starting a merge](/docs/guides/branches); an unresolved conflict blocks completing the merge.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branchId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation branch id (UUID)."}],"responses":{"200":{"description":"The branch's recorded conflicts (empty if none).","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"conflicts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique conflict id (UUID) — pass this to the resolve endpoint.","examples":["c1a2b3d4-0000-4000-8000-000000000009"]},"branchId":{"type":"string","description":"Id of the branch this conflict belongs to.","examples":["b1a2c3d4-0000-4000-8000-000000000001"]},"conflictType":{"type":"string","description":"Kind of conflict: `value` (both sides changed the same value), `key_deleted_on_main` (branch edits a key deleted on main), or `key_name_collision` (branch adds a key name that now exists on main).","examples":["value"]},"keySnapshot":{"type":"string","description":"The key name captured at conflict-detection time.","examples":["checkout.summary.total"]},"languageCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language of the conflicting value; `null` for key-level conflicts.","examples":["fr"]},"baseValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The common-ancestor value both sides diverged from, if known.","examples":["Total"]},"mainValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The current value on main.","examples":["Total amount"]},"branchValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value proposed by the branch.","examples":["Montant total"]},"resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chosen resolution: `main`, `branch`, or `custom`; `null` until resolved.","examples":[null]},"resolvedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The final value once resolved (the `customValue` when resolution is `custom`).","examples":[null]}},"required":["id","branchId","conflictType","keySnapshot","languageCode","baseValue","mainValue","branchValue","resolution","resolvedValue"],"additionalProperties":false}}},"required":["conflicts"],"additionalProperties":false}}}}}},"400":{"description":"Branch does not belong to this project."},"404":{"description":"Project or branch not found."}}}},"/projects/{projectId}/branches/{branchId}/conflicts/resolve":{"post":{"tags":["Branches"],"summary":"Resolve merge conflicts (write)","description":"Record a resolution for one or more conflicts on this branch. Each resolution picks `main`, `branch`, or a `custom` value. Resolutions are scoped to this branch — a conflict id from another branch is rejected. `customValue` is used only when `resolution` is `custom` (an omitted customValue resolves to an empty string). See the [branching guide](/docs/guides/branches).","x-permission":"translation_update","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branchId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation branch id (UUID)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resolutions":{"minItems":1,"type":"array","items":{"type":"object","properties":{"conflictId":{"type":"string","minLength":1,"description":"Id of the conflict to resolve (from the conflicts list).","examples":["c1a2b3d4-0000-4000-8000-000000000009"]},"resolution":{"type":"string","enum":["main","branch","custom"],"description":"Which side wins: `main` keeps main's value, `branch` takes the branch's value, `custom` uses `customValue`.","examples":["branch"]},"customValue":{"description":"The value to store when `resolution` is `custom` (ignored otherwise).","examples":["Montant total"],"type":"string"}},"required":["conflictId","resolution"]},"description":"One or more conflict resolutions to apply (at least one required)."}},"required":["resolutions"]}}}},"responses":{"200":{"description":"The number of conflicts resolved.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"resolved":{"type":"integer","description":"Number of conflicts updated by the request.","examples":[3]}},"required":["resolved"],"additionalProperties":false}}}}}},"400":{"description":"Branch does not belong to this project."},"403":{"description":"Token has no associated user for attribution."},"404":{"description":"A referenced conflict does not belong to this branch."}}}},"/projects/{projectId}/branches/{branchId}/merge/start":{"post":{"tags":["Branches"],"summary":"Start a merge — detect conflicts (write)","description":"Begin merging the branch into main. This recomputes and records conflicts against main's current state and reports how many changes will auto-merge. Resolve any returned conflicts, then call merge/complete — see the [branching guide](/docs/guides/branches).\n\n**Constraints:**\n- When the project requires merge approval, personal tokens need the approve permission and machine (project) tokens are rejected.","x-permission":"translation_update","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branchId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation branch id (UUID)."}],"responses":{"200":{"description":"Detected conflicts plus the auto-mergeable count.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"conflicts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique conflict id (UUID) — pass this to the resolve endpoint.","examples":["c1a2b3d4-0000-4000-8000-000000000009"]},"branchId":{"type":"string","description":"Id of the branch this conflict belongs to.","examples":["b1a2c3d4-0000-4000-8000-000000000001"]},"conflictType":{"type":"string","description":"Kind of conflict: `value` (both sides changed the same value), `key_deleted_on_main` (branch edits a key deleted on main), or `key_name_collision` (branch adds a key name that now exists on main).","examples":["value"]},"keySnapshot":{"type":"string","description":"The key name captured at conflict-detection time.","examples":["checkout.summary.total"]},"languageCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language of the conflicting value; `null` for key-level conflicts.","examples":["fr"]},"baseValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The common-ancestor value both sides diverged from, if known.","examples":["Total"]},"mainValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The current value on main.","examples":["Total amount"]},"branchValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value proposed by the branch.","examples":["Montant total"]},"resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chosen resolution: `main`, `branch`, or `custom`; `null` until resolved.","examples":[null]},"resolvedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The final value once resolved (the `customValue` when resolution is `custom`).","examples":[null]}},"required":["id","branchId","conflictType","keySnapshot","languageCode","baseValue","mainValue","branchValue","resolution","resolvedValue"],"additionalProperties":false},"description":"Conflicts that must be resolved before the merge can complete (empty if none)."},"autoMergeableCount":{"type":"integer","description":"Number of changes that will merge cleanly without manual resolution.","examples":[17]}},"required":["conflicts","autoMergeableCount"],"additionalProperties":false}}}}}},"400":{"description":"Branch does not belong to this project."},"403":{"description":"Merge not permitted (missing approval permission or a machine token)."},"404":{"description":"Project or branch not found."}}}},"/projects/{projectId}/branches/{branchId}/merge/complete":{"post":{"tags":["Branches"],"summary":"Complete a merge — apply the branch to main (write)","description":"Apply the branch's changes to main and mark the branch merged. All conflicts must be resolved first — otherwise the request fails with 409. Returns a count of what was written to main. See the [branching guide](/docs/guides/branches).\n\n**Constraints:**\n- When the project requires merge approval, personal tokens need the approve permission and machine (project) tokens are rejected.","x-permission":"translation_update","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"branchId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation branch id (UUID)."}],"responses":{"200":{"description":"Counts of keys added/deleted and values updated on main.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"keysAdded":{"type":"integer","description":"Keys created on main by the merge.","examples":[4]},"keysDeleted":{"type":"integer","description":"Keys removed from main by the merge.","examples":[1]},"valuesUpdated":{"type":"integer","description":"Translation values written to main by the merge.","examples":[12]}},"required":["keysAdded","keysDeleted","valuesUpdated"],"additionalProperties":false}}}}}},"400":{"description":"Branch does not belong to this project."},"403":{"description":"Merge not permitted (missing approval permission or a machine token)."},"409":{"description":"The branch still has unresolved conflicts."}}}},"/projects/{projectId}/glossary/lookup":{"post":{"tags":["Glossary"],"summary":"Look up glossary terms","description":"Find the glossary terms that occur in one or more source strings, with their approved translations. Batched: pass every source string and every target language in one call.\n\nEach match carries `doNotTranslate`, `caseSensitive` and `usageStatus` (`preferred` / `deprecated` / `forbidden`) so a translator — or an agent generating a translation — can honor terminology rules.\n\n**Constraints:**\n- Returns an empty object when the glossary feature is disabled for the org or the project.\n- At most 100 source texts and 50 languages per request.\n- Matching is whole-word where the term has word boundaries, substring otherwise (CJK/Thai).","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceTexts":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"},"description":"Source strings to scan for glossary terms (max 100 per call).","examples":[["Sign in to continue","Reset your password"]]},"languageCodes":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1},"description":"Target language codes to return translations for (max 50 per call).","examples":[["fr","de"]]}},"required":["sourceTexts","languageCodes"]}}}},"responses":{"200":{"description":"Terms keyed by source text, then language code","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"matches":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string","description":"The glossary term found in the source string.","examples":["Sign in"]},"translation":{"type":"string","description":"The approved translation of the term for the requested language.","examples":["Se connecter"]},"glossaryId":{"type":"string","description":"Id of the glossary this term belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"glossaryName":{"type":"string","description":"Name of the glossary this term belongs to.","examples":["Brand Terms"]},"doNotTranslate":{"type":"boolean","description":"True when the term must be left untranslated (brand/product names).","examples":[false]},"caseSensitive":{"type":"boolean","description":"True when matching this term respects its exact casing.","examples":[false]},"usageStatus":{"type":"string","description":"Usage rule for the term: `preferred`, `deprecated`, or `forbidden`.","examples":["preferred"]}},"required":["term","translation","glossaryId","glossaryName","doNotTranslate","caseSensitive","usageStatus"],"additionalProperties":false}}}}},"required":["matches"],"additionalProperties":false}}}}}}}}},"/projects/{projectId}/glossary/check":{"post":{"tags":["Glossary"],"summary":"Check a translation against the glossary","description":"Terminology QA for a proposed translation. Reports where a required term is missing, a forbidden or deprecated term was used, or a do-not-translate term was translated.\n\nSeverity comes from each glossary's own QA settings, so a rule configured as a warning does not read as an error.\n\n**Constraints:**\n- Returns an empty issue list when the glossary feature is disabled for the org or the project.\n- Issue kinds: missing_term, forbidden_term, deprecated_term, dnt_violation.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceText":{"type":"string","description":"The original source string the translation was produced from.","examples":["Sign in to continue"]},"targetText":{"type":"string","description":"The proposed translation to validate against the glossary.","examples":["Se connecter pour continuer"]},"languageCode":{"type":"string","minLength":1,"description":"Language code of the target text.","examples":["fr"]}},"required":["sourceText","targetText","languageCode"]}}}},"responses":{"200":{"description":"Terminology issues (empty when clean)","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"termId":{"type":"string","description":"Id of the glossary term the issue relates to.","examples":["a1b2c3d4-0000-4000-8000-000000000020"]},"term":{"type":"string","description":"The glossary term the issue relates to.","examples":["Sign in"]},"glossaryId":{"type":"string","description":"Id of the glossary that raised the issue.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"glossaryName":{"type":"string","description":"Name of the glossary that raised the issue.","examples":["Brand Terms"]},"severity":{"type":"string","description":"Severity from the glossary's QA settings: `warning` or `error`.","examples":["error"]},"kind":{"type":"string","enum":["missing_term","forbidden_term","deprecated_term","dnt_violation"],"description":"Issue type: `missing_term` (required term absent), `forbidden_term`, `deprecated_term`, or `dnt_violation` (a do-not-translate term was translated).","examples":["missing_term"]},"message":{"type":"string","description":"Human-readable explanation of the issue.","examples":["Expected term \"Se connecter\" for \"Sign in\" was not found."]},"expected":{"description":"The term/translation that was expected, when applicable.","examples":["Se connecter"],"type":"string"},"found":{"description":"The offending text that was actually found, when applicable.","examples":["connectez-vous"],"type":"string"}},"required":["termId","term","glossaryId","glossaryName","severity","kind","message"],"additionalProperties":false}}},"required":["issues"],"additionalProperties":false}}}}}}}}},"/orgs/{orgId}/glossaries":{"get":{"tags":["Glossary"],"summary":"List glossaries","description":"List every glossary in the organization, each with its term and language counts. Use this to discover glossary ids for the management endpoints — see the [glossary guide](/docs/guides/glossary).","x-permission":"glossary_read","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The organization's glossaries with term and language counts.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"glossaries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique glossary id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"orgId":{"type":"string","description":"Id of the organization that owns the glossary.","examples":["org_5a4b3c2d"]},"name":{"type":"string","description":"Human-readable glossary name.","examples":["Brand Terms"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional summary of what the glossary covers.","examples":["Approved product and brand terminology for all UI surfaces."]},"scope":{"type":"string","description":"Project applicability: `all` projects in the org, or only `selected` assigned ones.","examples":["all"]},"approvalRequired":{"type":"boolean","description":"True when term translations require approval before they apply.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"True when admins' edits are auto-approved while approval is required.","examples":[true]},"qaTermConsistency":{"type":"string","description":"Severity for missing-required-term issues: `off`, `warning`, or `error`.","examples":["warning"]},"qaForbiddenTerms":{"type":"string","description":"Severity for forbidden/deprecated-term issues: `off`, `warning`, or `error`.","examples":["error"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"termCount":{"type":"integer","description":"Number of terms in the glossary.","examples":[128]},"languageCount":{"type":"integer","description":"Number of languages configured on the glossary.","examples":[6]}},"required":["id","orgId","name","description","scope","approvalRequired","approvalBypassAdmins","qaTermConsistency","qaForbiddenTerms","createdAt","updatedAt","termCount","languageCount"],"additionalProperties":false}}},"required":["glossaries"],"additionalProperties":false}}}}}}}},"post":{"tags":["Glossary"],"summary":"Create a glossary","description":"Create a new glossary in the organization. Its `scope`, approval workflow, and QA severities can be set here or updated later. Add languages and terms in follow-up calls.","x-permission":"glossary_create","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable glossary name, unique within the organization.","examples":["Brand Terms"]},"description":{"description":"Optional summary of what this glossary covers.","examples":["Approved product and brand terminology for all UI surfaces."],"type":"string","maxLength":500},"scope":{"description":"Which projects the glossary applies to: `all` projects in the org, or only `selected` ones assigned to it. Defaults to `all`.","examples":["all"],"type":"string","enum":["all","selected"]},"approvalRequired":{"description":"When true, term translations from non-approvers are stored as proposals until approved.","examples":[false],"type":"boolean"},"approvalBypassAdmins":{"description":"When true, org/glossary admins' edits are auto-approved even while approval is required.","examples":[true],"type":"boolean"},"qaTermConsistency":{"description":"Severity when a required term is missing from a translation: `off`, `warning`, or `error`. See the [quality checks guide](/docs/guides/quality-checks).","examples":["warning"],"type":"string","enum":["off","warning","error"]},"qaForbiddenTerms":{"description":"Severity when a forbidden or deprecated term is used: `off`, `warning`, or `error`.","examples":["error"],"type":"string","enum":["off","warning","error"]}},"required":["name"]}}}},"responses":{"201":{"description":"The created glossary.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"glossary":{"type":"object","properties":{"id":{"type":"string","description":"Unique glossary id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"orgId":{"type":"string","description":"Id of the organization that owns the glossary.","examples":["org_5a4b3c2d"]},"name":{"type":"string","description":"Human-readable glossary name.","examples":["Brand Terms"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional summary of what the glossary covers.","examples":["Approved product and brand terminology for all UI surfaces."]},"scope":{"type":"string","description":"Project applicability: `all` projects in the org, or only `selected` assigned ones.","examples":["all"]},"approvalRequired":{"type":"boolean","description":"True when term translations require approval before they apply.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"True when admins' edits are auto-approved while approval is required.","examples":[true]},"qaTermConsistency":{"type":"string","description":"Severity for missing-required-term issues: `off`, `warning`, or `error`.","examples":["warning"]},"qaForbiddenTerms":{"type":"string","description":"Severity for forbidden/deprecated-term issues: `off`, `warning`, or `error`.","examples":["error"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","orgId","name","description","scope","approvalRequired","approvalBypassAdmins","qaTermConsistency","qaForbiddenTerms","createdAt","updatedAt"],"additionalProperties":false}},"required":["glossary"],"additionalProperties":false}}}}}},"500":{"description":"The glossary could not be created."}}}},"/glossaries/{glossaryId}":{"get":{"tags":["Glossary"],"summary":"Get a glossary","description":"Fetch a single glossary's settings and metadata by id.","x-permission":"glossary_read","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The glossary's settings and metadata.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"glossary":{"type":"object","properties":{"id":{"type":"string","description":"Unique glossary id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"orgId":{"type":"string","description":"Id of the organization that owns the glossary.","examples":["org_5a4b3c2d"]},"name":{"type":"string","description":"Human-readable glossary name.","examples":["Brand Terms"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional summary of what the glossary covers.","examples":["Approved product and brand terminology for all UI surfaces."]},"scope":{"type":"string","description":"Project applicability: `all` projects in the org, or only `selected` assigned ones.","examples":["all"]},"approvalRequired":{"type":"boolean","description":"True when term translations require approval before they apply.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"True when admins' edits are auto-approved while approval is required.","examples":[true]},"qaTermConsistency":{"type":"string","description":"Severity for missing-required-term issues: `off`, `warning`, or `error`.","examples":["warning"]},"qaForbiddenTerms":{"type":"string","description":"Severity for forbidden/deprecated-term issues: `off`, `warning`, or `error`.","examples":["error"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","orgId","name","description","scope","approvalRequired","approvalBypassAdmins","qaTermConsistency","qaForbiddenTerms","createdAt","updatedAt"],"additionalProperties":false}},"required":["glossary"],"additionalProperties":false}}}}}},"404":{"description":"No glossary with this id exists."}}},"patch":{"tags":["Glossary"],"summary":"Update a glossary","description":"Partial update of a glossary's settings — omitted fields are left unchanged. Disabling `approvalRequired` also clears `approvalBypassAdmins`, which is meaningless without it.","x-permission":"glossary_update","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New glossary name.","examples":["Brand Terms"],"type":"string","minLength":1,"maxLength":100},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"New description; pass `null` to clear it.","examples":["Approved product and brand terminology for all UI surfaces."]},"scope":{"description":"Change project applicability: `all` projects or only `selected` assigned ones.","examples":["selected"],"type":"string","enum":["all","selected"]},"approvalRequired":{"description":"Toggle the term-translation approval workflow.","examples":[true],"type":"boolean"},"approvalBypassAdmins":{"description":"Auto-approve admins' edits while approval is required.","examples":[true],"type":"boolean"},"qaTermConsistency":{"description":"Severity for missing-required-term issues: `off`, `warning`, or `error`.","examples":["warning"],"type":"string","enum":["off","warning","error"]},"qaForbiddenTerms":{"description":"Severity for forbidden/deprecated-term issues: `off`, `warning`, or `error`.","examples":["error"],"type":"string","enum":["off","warning","error"]}}}}}},"responses":{"200":{"description":"The updated glossary.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"glossary":{"type":"object","properties":{"id":{"type":"string","description":"Unique glossary id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"orgId":{"type":"string","description":"Id of the organization that owns the glossary.","examples":["org_5a4b3c2d"]},"name":{"type":"string","description":"Human-readable glossary name.","examples":["Brand Terms"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional summary of what the glossary covers.","examples":["Approved product and brand terminology for all UI surfaces."]},"scope":{"type":"string","description":"Project applicability: `all` projects in the org, or only `selected` assigned ones.","examples":["all"]},"approvalRequired":{"type":"boolean","description":"True when term translations require approval before they apply.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"True when admins' edits are auto-approved while approval is required.","examples":[true]},"qaTermConsistency":{"type":"string","description":"Severity for missing-required-term issues: `off`, `warning`, or `error`.","examples":["warning"]},"qaForbiddenTerms":{"type":"string","description":"Severity for forbidden/deprecated-term issues: `off`, `warning`, or `error`.","examples":["error"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","orgId","name","description","scope","approvalRequired","approvalBypassAdmins","qaTermConsistency","qaForbiddenTerms","createdAt","updatedAt"],"additionalProperties":false}},"required":["glossary"],"additionalProperties":false}}}}}},"404":{"description":"No glossary with this id exists."}}},"delete":{"tags":["Glossary"],"summary":"Delete a glossary","description":"Permanently delete the glossary and all of its terms, translations, and language configuration. This cannot be undone.","x-permission":"glossary_delete","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"Confirmation message.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation message.","examples":["Glossary deleted"]}},"required":["message"],"additionalProperties":false}}}}}}}}},"/glossaries/{glossaryId}/languages":{"get":{"tags":["Glossary"],"summary":"List glossary languages","description":"List the languages configured on the glossary, each with its display label.","x-permission":"glossary_read","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The glossary's configured languages.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique glossary-language row id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000030"]},"glossaryId":{"type":"string","description":"Id of the glossary this language belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"languageCode":{"type":"string","description":"BCP-47 language code.","examples":["fr"]},"label":{"type":"string","description":"Display label for the language, derived from the org catalog.","examples":["French"]}},"required":["id","glossaryId","languageCode","label"],"additionalProperties":false}}},"required":["languages"],"additionalProperties":false}}}}}}}},"post":{"tags":["Glossary"],"summary":"Add a glossary language","description":"Add a target language to the glossary so terms can carry a translation in it. The language code is adopted into the org catalog if it isn't already present.","x-permission":"glossary_update","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"languageCode":{"type":"string","minLength":2,"maxLength":10,"description":"BCP-47 language code to add to the glossary (e.g. `fr`, `pt-BR`).","examples":["fr"]},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Display label for the language column.","examples":["French"]}},"required":["languageCode","label"]}}}},"responses":{"201":{"description":"The added glossary language.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"language":{"type":"object","properties":{"id":{"type":"string","description":"Unique glossary-language row id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000030"]},"glossaryId":{"type":"string","description":"Id of the glossary this language belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"languageCode":{"type":"string","description":"BCP-47 language code.","examples":["fr"]},"label":{"type":"string","description":"Display label for the language, derived from the org catalog.","examples":["French"]}},"required":["id","glossaryId","languageCode","label"],"additionalProperties":false}},"required":["language"],"additionalProperties":false}}}}}},"409":{"description":"This language is already configured on the glossary."}}}},"/glossaries/{glossaryId}/terms":{"get":{"tags":["Glossary"],"summary":"List glossary terms","description":"Return a paginated page of the glossary's terms, each with its per-language translations. Combine the query params to search by text, filter by language, status, or usage, and sort.","x-permission":"glossary_read","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."},{"name":"page","in":"query","description":"1-based page number.","schema":{"default":1,"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Terms per page (max 200).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"search","in":"query","description":"Substring match on the term text.","schema":{"type":"string"}},{"name":"language","in":"query","description":"Only terms having a translation in this language code.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by translation status.","schema":{"type":"string","enum":["approved","pending_review","draft"]}},{"name":"usageStatus","in":"query","description":"Filter by preferred / deprecated / forbidden.","schema":{"type":"string","enum":["preferred","deprecated","forbidden"]}},{"name":"doNotTranslate","in":"query","description":"Only do-not-translate terms when true.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},{"name":"caseSensitive","in":"query","description":"Only case-sensitive terms when true.","schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}},{"name":"sort","in":"query","description":"Sort field.","schema":{"default":"term","type":"string","enum":["term","createdAt","updatedAt"]}},{"name":"order","in":"query","description":"Sort direction.","schema":{"default":"asc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of terms with their per-language translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"terms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique term id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000020"]},"glossaryId":{"type":"string","description":"Id of the glossary this term belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"term":{"type":"string","description":"The source-language term.","examples":["Sign in"]},"doNotTranslate":{"type":"boolean","description":"True when the term must be left untranslated.","examples":[false]},"caseSensitive":{"type":"boolean","description":"True when matching respects the term's exact casing.","examples":[false]},"usageStatus":{"type":"string","description":"Usage rule: `preferred`, `deprecated`, or `forbidden`.","examples":["preferred"]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional translator guidance, or `null`.","examples":["Use the verb form; never capitalize mid-sentence."]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this translation is written in.","examples":["fr"]},"value":{"type":"string","description":"The approved (or current) translation of the term.","examples":["Se connecter"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the translation was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval, or `null` when there is none.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of the term."}},"required":["id","glossaryId","term","doNotTranslate","caseSensitive","usageStatus","notes","createdAt","updatedAt","translations"],"additionalProperties":false}},"total":{"type":"integer","description":"Total number of terms matching the query across all pages.","examples":[128]},"page":{"type":"integer","description":"1-based page number of this result.","examples":[1]},"limit":{"type":"integer","description":"Maximum terms returned per page.","examples":[50]}},"required":["terms","total","page","limit"],"additionalProperties":false}}}}}}}},"post":{"tags":["Glossary"],"summary":"Create a term","description":"Add a term to the glossary. Optionally supply `translations` as a `languageCode -> value` map. When the glossary requires approval, values you cannot approve are recorded as proposals — see the [glossary guide](/docs/guides/glossary).\n\n**Constraints:**\n- Creating a term whose text already exists in the glossary returns 409.","x-permission":"glossary_create","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":500,"description":"The source-language term this entry defines.","examples":["Sign in"]},"doNotTranslate":{"description":"When true, the term must be left untranslated (brand names, product names).","examples":[false],"type":"boolean"},"caseSensitive":{"description":"When true, matching and QA checks respect the term's exact casing.","examples":[false],"type":"boolean"},"usageStatus":{"description":"Whether the term is `preferred`, `deprecated`, or `forbidden`. Defaults to `preferred`.","examples":["preferred"],"type":"string","enum":["preferred","deprecated","forbidden"]},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Optional guidance for translators on how to use the term.","examples":["Use the verb form; never capitalize mid-sentence."]},"translations":{"description":"Optional seed translations as a `languageCode -> value` map.","examples":[{"fr":"Se connecter","de":"Anmelden"}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["term"]}}}},"responses":{"201":{"description":"The created term with its translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"term":{"type":"object","properties":{"id":{"type":"string","description":"Unique term id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000020"]},"glossaryId":{"type":"string","description":"Id of the glossary this term belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"term":{"type":"string","description":"The source-language term.","examples":["Sign in"]},"doNotTranslate":{"type":"boolean","description":"True when the term must be left untranslated.","examples":[false]},"caseSensitive":{"type":"boolean","description":"True when matching respects the term's exact casing.","examples":[false]},"usageStatus":{"type":"string","description":"Usage rule: `preferred`, `deprecated`, or `forbidden`.","examples":["preferred"]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional translator guidance, or `null`.","examples":["Use the verb form; never capitalize mid-sentence."]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this translation is written in.","examples":["fr"]},"value":{"type":"string","description":"The approved (or current) translation of the term.","examples":["Se connecter"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the translation was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval, or `null` when there is none.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of the term."}},"required":["id","glossaryId","term","doNotTranslate","caseSensitive","usageStatus","notes","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["term"],"additionalProperties":false}}}}}},"409":{"description":"A term with this text already exists in the glossary."}}}},"/glossaries/{glossaryId}/terms/{termId}":{"get":{"tags":["Glossary"],"summary":"Get a term","description":"Fetch a single glossary term by id, with its per-language translations.","x-permission":"glossary_read","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."},{"name":"termId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary term id (UUID)."}],"responses":{"200":{"description":"The term and its translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"term":{"type":"object","properties":{"id":{"type":"string","description":"Unique term id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000020"]},"glossaryId":{"type":"string","description":"Id of the glossary this term belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"term":{"type":"string","description":"The source-language term.","examples":["Sign in"]},"doNotTranslate":{"type":"boolean","description":"True when the term must be left untranslated.","examples":[false]},"caseSensitive":{"type":"boolean","description":"True when matching respects the term's exact casing.","examples":[false]},"usageStatus":{"type":"string","description":"Usage rule: `preferred`, `deprecated`, or `forbidden`.","examples":["preferred"]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional translator guidance, or `null`.","examples":["Use the verb form; never capitalize mid-sentence."]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this translation is written in.","examples":["fr"]},"value":{"type":"string","description":"The approved (or current) translation of the term.","examples":["Se connecter"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the translation was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval, or `null` when there is none.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of the term."}},"required":["id","glossaryId","term","doNotTranslate","caseSensitive","usageStatus","notes","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["term"],"additionalProperties":false}}}}}},"404":{"description":"No such term in this glossary."}}},"patch":{"tags":["Glossary"],"summary":"Update a term","description":"Partial update of a term's metadata (text, notes, usage status, flags) — omitted fields are left unchanged. Use the translation endpoint to change values.","x-permission":"glossary_update","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."},{"name":"termId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary term id (UUID)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"term":{"description":"New source-language term text.","examples":["Sign in"],"type":"string","minLength":1,"maxLength":500},"doNotTranslate":{"description":"Toggle the do-not-translate flag.","examples":[false],"type":"boolean"},"caseSensitive":{"description":"Toggle case-sensitive matching.","examples":[false],"type":"boolean"},"usageStatus":{"description":"Change the usage status: `preferred`, `deprecated`, or `forbidden`.","examples":["deprecated"],"type":"string","enum":["preferred","deprecated","forbidden"]},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"New translator notes; pass `null` to clear.","examples":["Use the verb form; never capitalize mid-sentence."]}}}}}},"responses":{"200":{"description":"The updated term.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"term":{"type":"object","properties":{"id":{"type":"string","description":"Unique term id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000020"]},"glossaryId":{"type":"string","description":"Id of the glossary this term belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"term":{"type":"string","description":"The source-language term.","examples":["Sign in"]},"doNotTranslate":{"type":"boolean","description":"True when the term must be left untranslated.","examples":[false]},"caseSensitive":{"type":"boolean","description":"True when matching respects the term's exact casing.","examples":[false]},"usageStatus":{"type":"string","description":"Usage rule: `preferred`, `deprecated`, or `forbidden`.","examples":["preferred"]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional translator guidance, or `null`.","examples":["Use the verb form; never capitalize mid-sentence."]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this translation is written in.","examples":["fr"]},"value":{"type":"string","description":"The approved (or current) translation of the term.","examples":["Se connecter"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the translation was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval, or `null` when there is none.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of the term."}},"required":["id","glossaryId","term","doNotTranslate","caseSensitive","usageStatus","notes","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["term"],"additionalProperties":false}}}}}},"404":{"description":"No such term in this glossary."}}},"delete":{"tags":["Glossary"],"summary":"Delete a term","description":"Permanently remove a term and all of its translations from the glossary.","x-permission":"glossary_delete","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."},{"name":"termId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary term id (UUID)."}],"responses":{"200":{"description":"Confirmation message.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation message.","examples":["Glossary deleted"]}},"required":["message"],"additionalProperties":false}}}}}},"404":{"description":"No such term in this glossary."}}}},"/glossaries/{glossaryId}/terms/{termId}/translations/{lang}":{"put":{"tags":["Glossary"],"summary":"Set a term translation","description":"Upsert the translation of a term in one language, creating it if absent. When the glossary requires approval and you cannot approve, the value is stored as a proposal rather than applied — see the [approval workflow](/docs/guides/approval-workflow).\n\n**Constraints:**\n- For a Translator-scoped token, the target language must be within the token owner's assigned languages, or the request is rejected with 403.","x-permission":"glossary_update","parameters":[{"name":"glossaryId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary id (UUID) or id-embedded path slug."},{"name":"termId","in":"path","required":true,"schema":{"type":"string"},"description":"Glossary term id (UUID)."},{"name":"lang","in":"path","required":true,"schema":{"type":"string"},"description":"Language code, optionally with a file extension (`fr` or `fr.json`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"The translated text for the term in the target language.","examples":["Se connecter"]}},"required":["value"]}}}},"responses":{"200":{"description":"The term with its updated translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"term":{"type":"object","properties":{"id":{"type":"string","description":"Unique term id (UUID).","examples":["a1b2c3d4-0000-4000-8000-000000000020"]},"glossaryId":{"type":"string","description":"Id of the glossary this term belongs to.","examples":["a1b2c3d4-0000-4000-8000-000000000010"]},"term":{"type":"string","description":"The source-language term.","examples":["Sign in"]},"doNotTranslate":{"type":"boolean","description":"True when the term must be left untranslated.","examples":[false]},"caseSensitive":{"type":"boolean","description":"True when matching respects the term's exact casing.","examples":[false]},"usageStatus":{"type":"string","description":"Usage rule: `preferred`, `deprecated`, or `forbidden`.","examples":["preferred"]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional translator guidance, or `null`.","examples":["Use the verb form; never capitalize mid-sentence."]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this translation is written in.","examples":["fr"]},"value":{"type":"string","description":"The approved (or current) translation of the term.","examples":["Se connecter"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the translation was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval, or `null` when there is none.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of the term."}},"required":["id","glossaryId","term","doNotTranslate","caseSensitive","usageStatus","notes","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["term"],"additionalProperties":false}}}}}},"403":{"description":"The target language is outside the token owner's assigned languages."},"404":{"description":"No such term in this glossary."}}}},"/projects/{projectId}/tm/matches":{"post":{"tags":["Translation Memory"],"summary":"Get fuzzy TM matches","description":"Fuzzy-match source strings against the translation memories that apply to this project, returning scored suggestions. Batched: pass every source string and every target language in one call.\n\nEach TM's own `minMatchPercentage` and penalty settings (case / whitespace / trailing punctuation) are applied, so `matchPercentage` is the net score after penalties. See the [translation memory guide](/docs/guides/translation-memory).\n\n**Constraints:**\n- Returns an empty object when translation memory is disabled for the org or the project.\n- At most 100 source texts and 50 languages per request; up to 10 matches per language.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceTexts":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"},"description":"Source strings to fuzzy-match against the applicable TMs (1–100 per call).","examples":[["Welcome","Sign in"]]},"languageCodes":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1},"description":"Target language codes to return suggestions for (1–50 per call).","examples":[["fr","de"]]}},"required":["sourceTexts","languageCodes"]}}}},"responses":{"200":{"description":"A nested map: source text → language code → an array of scored matches (highest score first).","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"matches":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"sourceSegment":{"type":"string","description":"The stored source segment that matched your query string.","examples":["Welcome"]},"translation":{"type":"string","description":"The suggested translation for the requested target language.","examples":["Bienvenue"]},"tmId":{"type":"string","description":"Id of the translation memory this suggestion came from.","examples":["tm_3f2a9b1c"]},"tmName":{"type":"string","description":"Human-readable name of the source translation memory.","examples":["Marketing TM"]},"matchPercentage":{"type":"integer","description":"Net similarity score (0–100) after the TM's configured penalties. 100 is an exact match.","examples":[87]}},"required":["sourceSegment","translation","tmId","tmName","matchPercentage"],"additionalProperties":false}}}}},"required":["matches"],"additionalProperties":false}}}}}}}}},"/projects/{projectId}/tm/search":{"post":{"tags":["Translation Memory"],"summary":"Concordance search","description":"Free-text search across the project's translation memories — *how has this word or phrase been translated before?* — returning the full segments that contain it.\n\nThis answers what `/tm/matches` cannot: fuzzy matching scores WHOLE segment similarity, so a segment that merely contains your phrase but is otherwise different scores far below threshold and never surfaces. Use `searchIn: \"target\"` to find where a translated term was used. See the [translation memory guide](/docs/guides/translation-memory).","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1000,"description":"The word or phrase to search for within stored TM segments.","examples":["welcome"]},"languageCodes":{"description":"Restrict returned translations to these language codes (all languages if omitted).","examples":[["fr","de"]],"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"searchIn":{"default":"both","description":"Where to match: `source` (source text only), `target` (translated text only), or `both`.","examples":["both"],"type":"string","enum":["source","target","both"]},"page":{"default":1,"description":"1-based page number.","examples":[1],"type":"integer","minimum":1},"limit":{"default":50,"description":"Results per page, 1–200.","examples":[50],"type":"integer","minimum":1,"maximum":200}},"required":["query"]}}}},"responses":{"200":{"description":"A paginated list of matching TM segments with their translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string","description":"Id of the TM entry containing the matched segment.","examples":["tme_7b1c4d90"]},"sourceText":{"type":"string","description":"The full source segment that contains your search term.","examples":["Welcome to your account"]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional context note stored with the entry, or `null` if none.","examples":["Shown after login"]},"tmId":{"type":"string","description":"Id of the translation memory the entry belongs to.","examples":["tm_3f2a9b1c"]},"tmName":{"type":"string","description":"Human-readable name of that translation memory.","examples":["Marketing TM"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code this translation is written in.","examples":["fr"]},"value":{"type":"string","description":"The translated text stored for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state of the translation: `approved`, `pending_review`, or `draft`.","examples":["approved"]}},"required":["languageCode","value","status"],"additionalProperties":false},"description":"The entry's translations, filtered to the requested languages."}},"required":["entryId","sourceText","context","tmId","tmName","translations"],"additionalProperties":false}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}},"required":["items","total","page","limit"],"additionalProperties":false}}}}}}}}},"/projects/{projectId}/tm/pretranslate":{"post":{"tags":["Translation Memory"],"summary":"Pre-translate from TM","description":"Apply TM matches to the project's untranslated strings in bulk (leverage). Runs asynchronously — poll the returned `jobId`.\n\nAlready-translated values are skipped. When the project requires approval, written values follow the caller's approval rights exactly as in the app.\n\n**Constraints:**\n- 409 while another import/export/sync job is running on the project.\n- `minMatchPercentage` defaults to each TM's configured minimum.","x-permission":"translation_update","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"minMatchPercentage":{"description":"Only apply matches at or above this score (floor 40). Defaults to the lowest configured minimum across the applicable TMs.","examples":[80],"type":"integer","minimum":40,"maximum":100}}}}}},"responses":{"202":{"description":"The queued job's id and initial status — poll the status endpoint to track it.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"jobId":{"type":"string","description":"Id of the queued pre-translate job. Poll the status endpoint with it.","examples":["job_a1b2c3d4"]},"status":{"type":"string","description":"Initial job state, typically `queued` or `running`.","examples":["queued"]}},"required":["jobId","status"],"additionalProperties":false}}}}}},"400":{"description":"No translation memory applies to this project (feature off or none assigned)."},"401":{"description":"The token has no associated user to attribute writes to."},"409":{"description":"Another import / export / sync job is already running for this project."}}}},"/projects/{projectId}/tm/pretranslate/{jobId}":{"get":{"tags":["Translation Memory"],"summary":"Get pre-translate job status","description":"Poll the progress of a pre-translate job started via `POST /tm/pretranslate`. Reports live progress and, on completion, how many values were written or skipped.","x-permission":"translation_read","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id (UUID) or id-embedded path slug."},{"name":"jobId","in":"path","required":true,"schema":{"type":"string"},"description":"Import/export job id (UUID) returned when the job was created."}],"responses":{"200":{"description":"The job's current status, progress, and result counters.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"jobId":{"type":"string","description":"Id of the pre-translate job.","examples":["job_a1b2c3d4"]},"status":{"type":"string","description":"Current job state: `queued`, `running`, `completed`, or `failed`.","examples":["completed"]},"progress":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Completion percentage (0–100) while running, or `null` if not yet reported.","examples":[100]},"keysCreated":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Number of translation values created by leveraging, or `null` until known.","examples":[0]},"keysUpdated":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Number of translation values written from TM matches, or `null` until known.","examples":[42]},"keysSkipped":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Number of strings left untouched (already translated or no match), or `null`.","examples":[8]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Failure message when `status` is `failed`, otherwise `null`.","examples":[null]}},"required":["jobId","status","progress","keysCreated","keysUpdated","keysSkipped","error"],"additionalProperties":false}}}}}},"404":{"description":"No job with this id belongs to this project."}}}},"/orgs/{orgId}/translation-memories":{"get":{"tags":["Translation Memory"],"summary":"List translation memories","description":"List every translation memory in the organization, each with its entry and language counts. This is a management endpoint — call it with a personal access token; project-scoped tokens are refused.","x-permission":"tm_read","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The organization's translation memories with entry/language counts.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"translationMemories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique translation-memory id (UUID).","examples":["tm_3f2a9b1c"]},"orgId":{"type":"string","description":"Id of the organization that owns this TM.","examples":["org_5d4c3b2a"]},"name":{"type":"string","description":"Human-readable name of the translation memory.","examples":["Marketing TM"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text description, or `null` if none.","examples":["Reusable copy for marketing surfaces."]},"sourceLanguage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47 code of the TM's source language — matches are keyed off it. `null` until set.","examples":["en"]},"scope":{"type":"string","description":"Assignment scope: `all` (every project in the org may leverage it) or `selected` (only assigned projects).","examples":["all"]},"approvalRequired":{"type":"boolean","description":"When true, entry translations by non-approvers are stored as proposals.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"When true, org admins' edits are auto-approved even while approval is required.","examples":[false]},"minMatchPercentage":{"type":"integer","description":"Floor (40–100) below which fuzzy matches from this TM are not surfaced.","examples":[75]},"penalties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Percentage-point deductions applied to near-exact matches, keyed by `caseMismatch`, `whitespace`, `punctuation`.","examples":[{"caseMismatch":1,"whitespace":1,"punctuation":2}]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"entryCount":{"type":"integer","description":"Total number of source entries stored in this TM.","examples":[1280]},"languageCount":{"type":"integer","description":"Number of target languages configured on this TM.","examples":[6]}},"required":["id","orgId","name","description","sourceLanguage","scope","approvalRequired","approvalBypassAdmins","minMatchPercentage","penalties","createdAt","updatedAt","entryCount","languageCount"],"additionalProperties":false}}},"required":["translationMemories"],"additionalProperties":false}}}}}}}},"post":{"tags":["Translation Memory"],"summary":"Create a translation memory","description":"Create a new translation memory in the organization. `minMatchPercentage` (default 75, floor 40) is the threshold below which fuzzy matches from this TM are not surfaced. `penalties` deducts points for case / whitespace / trailing punctuation differences on otherwise-identical sources.","x-permission":"tm_create","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"},"description":"Organization id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable name for the translation memory.","examples":["Marketing TM"]},"description":{"description":"Optional free-text description.","examples":["Reusable copy for marketing surfaces."],"type":"string","maxLength":500},"sourceLanguage":{"description":"BCP-47 code of the TM's source language — matches are keyed off it.","examples":["en"],"type":"string","maxLength":10},"scope":{"description":"`all` = every project may leverage it; `selected` = only assigned projects. Defaults to `all`.","examples":["all"],"type":"string","enum":["all","selected"]},"approvalRequired":{"description":"When true, entry translations by non-approvers are stored as proposals.","examples":[false],"type":"boolean"},"approvalBypassAdmins":{"description":"When true, org admins' edits are auto-approved even while approval is required.","examples":[false],"type":"boolean"},"minMatchPercentage":{"description":"Minimum match % below which fuzzy matches are not surfaced (floor 40, default 75).","examples":[75],"type":"integer","minimum":40,"maximum":100},"penalties":{"description":"Per-difference score deductions applied to near-exact matches.","type":"object","properties":{"caseMismatch":{"description":"Percentage points to deduct when a match differs only in letter case.","examples":[1],"type":"number","minimum":0,"maximum":100},"whitespace":{"description":"Percentage points to deduct when a match differs only in whitespace.","examples":[1],"type":"number","minimum":0,"maximum":100},"punctuation":{"description":"Percentage points to deduct when a match differs only in trailing punctuation.","examples":[2],"type":"number","minimum":0,"maximum":100}}}},"required":["name"]}}}},"responses":{"201":{"description":"The newly created translation memory.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"translationMemory":{"type":"object","properties":{"id":{"type":"string","description":"Unique translation-memory id (UUID).","examples":["tm_3f2a9b1c"]},"orgId":{"type":"string","description":"Id of the organization that owns this TM.","examples":["org_5d4c3b2a"]},"name":{"type":"string","description":"Human-readable name of the translation memory.","examples":["Marketing TM"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text description, or `null` if none.","examples":["Reusable copy for marketing surfaces."]},"sourceLanguage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47 code of the TM's source language — matches are keyed off it. `null` until set.","examples":["en"]},"scope":{"type":"string","description":"Assignment scope: `all` (every project in the org may leverage it) or `selected` (only assigned projects).","examples":["all"]},"approvalRequired":{"type":"boolean","description":"When true, entry translations by non-approvers are stored as proposals.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"When true, org admins' edits are auto-approved even while approval is required.","examples":[false]},"minMatchPercentage":{"type":"integer","description":"Floor (40–100) below which fuzzy matches from this TM are not surfaced.","examples":[75]},"penalties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Percentage-point deductions applied to near-exact matches, keyed by `caseMismatch`, `whitespace`, `punctuation`.","examples":[{"caseMismatch":1,"whitespace":1,"punctuation":2}]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","orgId","name","description","sourceLanguage","scope","approvalRequired","approvalBypassAdmins","minMatchPercentage","penalties","createdAt","updatedAt"],"additionalProperties":false}},"required":["translationMemory"],"additionalProperties":false}}}}}},"500":{"description":"The translation memory could not be created."}}}},"/translation-memories/{tmId}":{"get":{"tags":["Translation Memory"],"summary":"Get a translation memory","description":"Fetch a single translation memory by id, including its match settings and penalties.","x-permission":"tm_read","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The requested translation memory.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"translationMemory":{"type":"object","properties":{"id":{"type":"string","description":"Unique translation-memory id (UUID).","examples":["tm_3f2a9b1c"]},"orgId":{"type":"string","description":"Id of the organization that owns this TM.","examples":["org_5d4c3b2a"]},"name":{"type":"string","description":"Human-readable name of the translation memory.","examples":["Marketing TM"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text description, or `null` if none.","examples":["Reusable copy for marketing surfaces."]},"sourceLanguage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47 code of the TM's source language — matches are keyed off it. `null` until set.","examples":["en"]},"scope":{"type":"string","description":"Assignment scope: `all` (every project in the org may leverage it) or `selected` (only assigned projects).","examples":["all"]},"approvalRequired":{"type":"boolean","description":"When true, entry translations by non-approvers are stored as proposals.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"When true, org admins' edits are auto-approved even while approval is required.","examples":[false]},"minMatchPercentage":{"type":"integer","description":"Floor (40–100) below which fuzzy matches from this TM are not surfaced.","examples":[75]},"penalties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Percentage-point deductions applied to near-exact matches, keyed by `caseMismatch`, `whitespace`, `punctuation`.","examples":[{"caseMismatch":1,"whitespace":1,"punctuation":2}]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","orgId","name","description","sourceLanguage","scope","approvalRequired","approvalBypassAdmins","minMatchPercentage","penalties","createdAt","updatedAt"],"additionalProperties":false}},"required":["translationMemory"],"additionalProperties":false}}}}}},"404":{"description":"No translation memory with this id exists."}}},"patch":{"tags":["Translation Memory"],"summary":"Update a translation memory","description":"Partial update — omitted fields are left unchanged. Set `rebaseSourceData: true` when changing `sourceLanguage` to also move existing entry data onto the new source.\n\n**Constraints:**\n- `approvalBypassAdmins` is meaningless without `approvalRequired` and is forced off when approval is disabled.","x-permission":"tm_update","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name for the translation memory.","examples":["Marketing TM"],"type":"string","minLength":1,"maxLength":100},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"New description, or `null` to clear it.","examples":["Reusable copy for marketing surfaces."]},"sourceLanguage":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"New source-language code, or `null` to clear it. Pair with `rebaseSourceData` to migrate entries.","examples":["en"]},"scope":{"description":"`all` = every project may leverage it; `selected` = only assigned projects.","examples":["all"],"type":"string","enum":["all","selected"]},"approvalRequired":{"description":"When true, entry translations by non-approvers are stored as proposals.","examples":[false],"type":"boolean"},"approvalBypassAdmins":{"description":"When true, org admins' edits are auto-approved even while approval is required.","examples":[false],"type":"boolean"},"minMatchPercentage":{"description":"Minimum match % below which fuzzy matches are not surfaced (floor 40).","examples":[75],"type":"integer","minimum":40,"maximum":100},"penalties":{"description":"Per-difference score deductions applied to near-exact matches.","type":"object","properties":{"caseMismatch":{"description":"Percentage points to deduct when a match differs only in letter case.","examples":[1],"type":"number","minimum":0,"maximum":100},"whitespace":{"description":"Percentage points to deduct when a match differs only in whitespace.","examples":[1],"type":"number","minimum":0,"maximum":100},"punctuation":{"description":"Percentage points to deduct when a match differs only in trailing punctuation.","examples":[2],"type":"number","minimum":0,"maximum":100}}},"rebaseSourceData":{"description":"When changing `sourceLanguage`, also move existing entry data to the new source (rebase). Not persisted.","examples":[false],"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated translation memory.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"translationMemory":{"type":"object","properties":{"id":{"type":"string","description":"Unique translation-memory id (UUID).","examples":["tm_3f2a9b1c"]},"orgId":{"type":"string","description":"Id of the organization that owns this TM.","examples":["org_5d4c3b2a"]},"name":{"type":"string","description":"Human-readable name of the translation memory.","examples":["Marketing TM"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional free-text description, or `null` if none.","examples":["Reusable copy for marketing surfaces."]},"sourceLanguage":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47 code of the TM's source language — matches are keyed off it. `null` until set.","examples":["en"]},"scope":{"type":"string","description":"Assignment scope: `all` (every project in the org may leverage it) or `selected` (only assigned projects).","examples":["all"]},"approvalRequired":{"type":"boolean","description":"When true, entry translations by non-approvers are stored as proposals.","examples":[false]},"approvalBypassAdmins":{"type":"boolean","description":"When true, org admins' edits are auto-approved even while approval is required.","examples":[false]},"minMatchPercentage":{"type":"integer","description":"Floor (40–100) below which fuzzy matches from this TM are not surfaced.","examples":[75]},"penalties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Percentage-point deductions applied to near-exact matches, keyed by `caseMismatch`, `whitespace`, `punctuation`.","examples":[{"caseMismatch":1,"whitespace":1,"punctuation":2}]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]}},"required":["id","orgId","name","description","sourceLanguage","scope","approvalRequired","approvalBypassAdmins","minMatchPercentage","penalties","createdAt","updatedAt"],"additionalProperties":false}},"required":["translationMemory"],"additionalProperties":false}}}}}},"404":{"description":"No translation memory with this id exists."}}},"delete":{"tags":["Translation Memory"],"summary":"Delete a translation memory","description":"Permanently delete the TM together with all of its entries, translations, and project assignments. This cannot be undone.","x-permission":"tm_delete","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"A confirmation message.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation of the action.","examples":["Translation memory deleted"]}},"required":["message"],"additionalProperties":false}}}}}}}}},"/translation-memories/{tmId}/languages":{"get":{"tags":["Translation Memory"],"summary":"List TM languages","description":"List the target languages configured on this translation memory.","x-permission":"tm_read","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."}],"responses":{"200":{"description":"The TM's configured languages.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM-language row id (UUID).","examples":["tml_9a8b7c6d"]},"tmId":{"type":"string","description":"Id of the translation memory this language belongs to.","examples":["tm_3f2a9b1c"]},"languageCode":{"type":"string","description":"BCP-47 language code.","examples":["fr"]},"label":{"type":"string","description":"Display label for the language, derived from the org language catalog.","examples":["French"]}},"required":["id","tmId","languageCode","label"],"additionalProperties":false}}},"required":["languages"],"additionalProperties":false}}}}}}}},"post":{"tags":["Translation Memory"],"summary":"Add a TM language","description":"Add a target language to the translation memory so entries can store translations in it.","x-permission":"tm_update","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"languageCode":{"type":"string","minLength":2,"maxLength":10,"description":"BCP-47 code of the target language to add.","examples":["fr"]},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Display label for the language.","examples":["French"]}},"required":["languageCode","label"]}}}},"responses":{"201":{"description":"The newly added TM language.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"language":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM-language row id (UUID).","examples":["tml_9a8b7c6d"]},"tmId":{"type":"string","description":"Id of the translation memory this language belongs to.","examples":["tm_3f2a9b1c"]},"languageCode":{"type":"string","description":"BCP-47 language code.","examples":["fr"]},"label":{"type":"string","description":"Display label for the language, derived from the org language catalog.","examples":["French"]}},"required":["id","tmId","languageCode","label"],"additionalProperties":false}},"required":["language"],"additionalProperties":false}}}}}},"409":{"description":"This language already exists in the translation memory."}}}},"/translation-memories/{tmId}/entries":{"get":{"tags":["Translation Memory"],"summary":"List TM entries","description":"Return a paginated page of the TM's source entries, each with its per-language translations. Filter by source text, language, or translation status and sort as needed.","x-permission":"tm_read","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."},{"name":"page","in":"query","description":"1-based page number (default 1).","schema":{"default":1,"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Entries per page, 1–200 (default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"search","in":"query","description":"Substring match on the entry's source text.","schema":{"type":"string"}},{"name":"language","in":"query","description":"Only entries that have a translation in this language code.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Keep only entries with a translation in this status (`approved`, `pending_review`, `draft`).","schema":{"type":"string","enum":["approved","pending_review","draft"]}},{"name":"sort","in":"query","description":"Sort field: `sourceText`, `createdAt`, or `updatedAt` (default `sourceText`).","schema":{"default":"sourceText","type":"string","enum":["sourceText","createdAt","updatedAt"]}},{"name":"order","in":"query","description":"Sort direction: `asc` or `desc` (default `asc`).","schema":{"default":"asc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"A page of TM entries with their translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM entry id (UUID).","examples":["tme_7b1c4d90"]},"tmId":{"type":"string","description":"Id of the translation memory this entry belongs to.","examples":["tm_3f2a9b1c"]},"sourceText":{"type":"string","description":"The source-language segment this entry stores translations for.","examples":["Welcome"]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional context note disambiguating this entry, or `null`.","examples":["Greeting on the home page"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code of this translation.","examples":["fr"]},"value":{"type":"string","description":"The current (approved or draft) translated text for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the value was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval that has not yet replaced `value`, or `null` when none is pending.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of this entry."}},"required":["id","tmId","sourceText","context","createdAt","updatedAt","translations"],"additionalProperties":false}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}},"required":["entries","total","page","limit"],"additionalProperties":false}}}}}}}},"post":{"tags":["Translation Memory"],"summary":"Create a TM entry","description":"Add a source entry to the TM. Optionally supply `translations` as a `languageCode -> value` map to seed translations in one call. When the TM requires approval, values you cannot approve are recorded as proposals.","x-permission":"tm_create","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceText":{"type":"string","minLength":1,"maxLength":5000,"description":"The source-language segment this entry stores translations for.","examples":["Welcome"]},"context":{"description":"Optional context note disambiguating this entry.","examples":["Greeting on the home page"],"type":"string","maxLength":1000},"translations":{"description":"Optional seed translations as a `languageCode -> value` map.","examples":[{"fr":"Bienvenue","de":"Willkommen"}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["sourceText"]}}}},"responses":{"201":{"description":"The created entry with its (possibly seeded) translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM entry id (UUID).","examples":["tme_7b1c4d90"]},"tmId":{"type":"string","description":"Id of the translation memory this entry belongs to.","examples":["tm_3f2a9b1c"]},"sourceText":{"type":"string","description":"The source-language segment this entry stores translations for.","examples":["Welcome"]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional context note disambiguating this entry, or `null`.","examples":["Greeting on the home page"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code of this translation.","examples":["fr"]},"value":{"type":"string","description":"The current (approved or draft) translated text for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the value was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval that has not yet replaced `value`, or `null` when none is pending.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of this entry."}},"required":["id","tmId","sourceText","context","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["entry"],"additionalProperties":false}}}}}},"409":{"description":"An entry with this source text already exists in the TM."}}}},"/translation-memories/{tmId}/entries/{entryId}":{"get":{"tags":["Translation Memory"],"summary":"Get a TM entry","description":"Fetch a single TM entry by id, with its translations across all languages.","x-permission":"tm_read","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."},{"name":"entryId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation-memory entry id (UUID)."}],"responses":{"200":{"description":"The requested entry and its translations.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM entry id (UUID).","examples":["tme_7b1c4d90"]},"tmId":{"type":"string","description":"Id of the translation memory this entry belongs to.","examples":["tm_3f2a9b1c"]},"sourceText":{"type":"string","description":"The source-language segment this entry stores translations for.","examples":["Welcome"]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional context note disambiguating this entry, or `null`.","examples":["Greeting on the home page"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code of this translation.","examples":["fr"]},"value":{"type":"string","description":"The current (approved or draft) translated text for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the value was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval that has not yet replaced `value`, or `null` when none is pending.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of this entry."}},"required":["id","tmId","sourceText","context","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["entry"],"additionalProperties":false}}}}}},"404":{"description":"No entry with this id belongs to this TM."}}},"patch":{"tags":["Translation Memory"],"summary":"Update a TM entry","description":"Update an entry's source text and/or context. Partial — omitted fields are left unchanged. To edit a translation value, use the entry-translation endpoint instead.","x-permission":"tm_update","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."},{"name":"entryId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation-memory entry id (UUID)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceText":{"description":"New source text for the entry.","examples":["Welcome"],"type":"string","minLength":1,"maxLength":5000},"context":{"description":"New context note for the entry.","examples":["Greeting on the home page"],"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"The updated entry.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM entry id (UUID).","examples":["tme_7b1c4d90"]},"tmId":{"type":"string","description":"Id of the translation memory this entry belongs to.","examples":["tm_3f2a9b1c"]},"sourceText":{"type":"string","description":"The source-language segment this entry stores translations for.","examples":["Welcome"]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional context note disambiguating this entry, or `null`.","examples":["Greeting on the home page"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code of this translation.","examples":["fr"]},"value":{"type":"string","description":"The current (approved or draft) translated text for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the value was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval that has not yet replaced `value`, or `null` when none is pending.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of this entry."}},"required":["id","tmId","sourceText","context","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["entry"],"additionalProperties":false}}}}}},"404":{"description":"No entry with this id belongs to this TM."}}},"delete":{"tags":["Translation Memory"],"summary":"Delete a TM entry","description":"Permanently remove a TM entry and all of its translations.","x-permission":"tm_delete","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."},{"name":"entryId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation-memory entry id (UUID)."}],"responses":{"200":{"description":"A confirmation message.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable confirmation of the action.","examples":["Translation memory deleted"]}},"required":["message"],"additionalProperties":false}}}}}},"404":{"description":"No entry with this id belongs to this TM."}}}},"/translation-memories/{tmId}/entries/{entryId}/translations/{lang}":{"put":{"tags":["Translation Memory"],"summary":"Set a TM entry translation","description":"Upsert the translation of an entry in one language, creating it if absent. When the TM requires approval and you cannot approve, the value is stored as a proposal on `proposedValue` rather than replacing the live value.\n\n**Constraints:**\n- For a Translator-scoped token, the target language must be within the token owner's assigned languages, or the request is rejected with 403.","x-permission":"tm_update","parameters":[{"name":"tmId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation memory id (UUID) or id-embedded path slug."},{"name":"entryId","in":"path","required":true,"schema":{"type":"string"},"description":"Translation-memory entry id (UUID)."},{"name":"lang","in":"path","required":true,"schema":{"type":"string"},"description":"Language code, optionally with a file extension (`fr` or `fr.json`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"The translated text to store for the target language in the path.","examples":["Bienvenue"]}},"required":["value"]}}}},"responses":{"200":{"description":"The entry with its translations after the upsert.","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","description":"Unique TM entry id (UUID).","examples":["tme_7b1c4d90"]},"tmId":{"type":"string","description":"Id of the translation memory this entry belongs to.","examples":["tm_3f2a9b1c"]},"sourceText":{"type":"string","description":"The source-language segment this entry stores translations for.","examples":["Welcome"]},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional context note disambiguating this entry, or `null`.","examples":["Greeting on the home page"]},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601).","examples":["2026-01-15T09:24:00.000Z"]},"updatedAt":{"type":"string","description":"Last-update timestamp (ISO 8601).","examples":["2026-02-02T14:05:00.000Z"]},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string","description":"BCP-47 language code of this translation.","examples":["fr"]},"value":{"type":"string","description":"The current (approved or draft) translated text for this language.","examples":["Bienvenue"]},"status":{"type":"string","description":"Review state: `approved`, `pending_review`, or `draft`.","examples":["approved"]},"approvedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp the value was approved (ISO 8601), or `null` if not approved.","examples":["2026-01-16T11:00:00.000Z"]},"proposedValue":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A pending proposal awaiting approval that has not yet replaced `value`, or `null` when none is pending.","examples":[null]}},"required":["languageCode","value","status","approvedAt","proposedValue"],"additionalProperties":false},"description":"Per-language translations of this entry."}},"required":["id","tmId","sourceText","context","createdAt","updatedAt","translations"],"additionalProperties":false}},"required":["entry"],"additionalProperties":false}}}}}},"403":{"description":"The target language is outside the token owner's assigned languages."},"404":{"description":"No entry with this id belongs to this TM."}}}}}}