{"openapi":"3.0.3","info":{"title":"locize-api","description":"The Locize API: https://www.locize.com/docs/integration/api","version":"3.0.0"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"The `ApiKey` for the corresponding project."}},"schemas":{"def-0":{"type":"object","properties":{"autoPublish":{"type":"boolean","default":false},"cacheControlMaxAge":{"type":"number"}},"propertyNames":{"enum":["autoPublish","cacheControlMaxAge"]},"required":[],"nullable":true,"title":"addVersionPayload"},"def-1":{"type":"object","description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","properties":{"name":{"type":"string","example":"AuthorizationError"},"type":{"type":"string","example":"authorizationError.user.notAuthorized"},"code":{"type":"string"},"more":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"title":"unauthorized"},"def-2":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"The ID.","title":"uuid","example":"a0c79e13-d4a0-402e-b3d0-11793423f745"},"def-3":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","title":"doubleUuid","example":"a0c79e13-d4a0-402e-b3d0-11793423f745-f9eb69a2-9f81-415e-ae6e-a7e92c31f6c9"},"def-4":{"type":"string","oneOf":[{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","examples":["a0c79e13-d4a0-402e-b3d0-11793423f745"],"description":"The ID."},{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","examples":["a0c79e13-d4a0-402e-b3d0-11793423f745-f9eb69a2-9f81-415e-ae6e-a7e92c31f6c9"]},{"type":"string","pattern":"^api:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}:","examples":["api:a0c79e13-d4a0-402e-b3d0-11793423f745:xyz"]}],"title":"someUuid","example":"a0c79e13-d4a0-402e-b3d0-11793423f745"},"def-5":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}-","title":"uuidStart","example":"a0c79e13-d4a0-402e-b3d0-11793423f745-xyz"},"def-6":{"type":"string","pattern":"^api:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}:","title":"apiById","example":"api:a0c79e13-d4a0-402e-b3d0-11793423f745:xyz"},"def-7":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70,"example":"My awesome project"},"company":{"type":"string","nullable":true,"maxLength":70,"example":"Super-Company"},"projectUrl":{"type":"string","pattern":"(https?:\\/\\/)?(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-z]{2,63}\\b([-a-zA-Z0-9@:%_\\+.~#?&//=]*)","maxLength":256,"example":"https://www.my-company-website.com"},"syncWithParent":{"type":"boolean","default":true},"canEditLanguages":{"type":"boolean","default":false},"referenceLanguage":{"type":"string","example":"en"}},"propertyNames":{"enum":["name","company","projectUrl","syncWithParent","canEditLanguages","referenceLanguage","subscribeToParent"]},"required":["name"],"title":"tenantCreationPayload"},"def-8":{"nullable":true,"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70,"example":"My awesome project"},"company":{"type":"string","nullable":true,"maxLength":70,"example":"Super-Company"},"projectUrl":{"type":"string","pattern":"(https?:\\/\\/)?(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-z]{2,63}\\b([-a-zA-Z0-9@:%_\\+.~#?&//=]*)","maxLength":256,"example":"https://www.my-company-website.com"},"slug":{"type":"string","minLength":1,"example":"0nod9b95"},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"The ID.","example":"a0c79e13-d4a0-402e-b3d0-11793423f745"},"subscribedAt":{"type":"number","description":"The date/time in ms when the project was subscribed.","example":1657525881460}},"propertyNames":{"enum":["name","company","projectUrl","slug","id","subscribedAt"]},"required":["name","id"],"title":"tenantWithId"},"def-9":{"type":"object","properties":{"syncWithParent":{"type":"boolean","default":true},"canEditLanguages":{"type":"boolean","default":false}},"propertyNames":{"enum":["syncWithParent","canEditLanguages"]},"required":[],"title":"tenantUpdatePayload"},"def-10":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70,"example":"My awesome project"},"company":{"type":"string","nullable":true,"maxLength":70,"example":"Super-Company"},"projectUrl":{"type":"string","pattern":"(https?:\\/\\/)?(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-z]{2,63}\\b([-a-zA-Z0-9@:%_\\+.~#?&//=]*)","maxLength":256,"example":"https://www.my-company-website.com"},"slug":{"type":"string","minLength":1,"example":"0nod9b95"},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"The ID.","example":"a0c79e13-d4a0-402e-b3d0-11793423f745"},"subscribedAt":{"type":"number","description":"The date/time in ms when the project was subscribed.","example":1657525881460}},"propertyNames":{"enum":["name","company","projectUrl","slug","id","subscribedAt"]},"required":["name","id"]},"title":"tenants"},"def-11":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70,"example":"My awesome project"},"company":{"type":"string","nullable":true,"maxLength":70,"example":"Super-Company"},"projectUrl":{"type":"string","pattern":"(https?:\\/\\/)?(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-z]{2,63}\\b([-a-zA-Z0-9@:%_\\+.~#?&//=]*)","maxLength":256,"example":"https://www.my-company-website.com"},"referenceLanguage":{"type":"string","example":"en"}},"propertyNames":{"enum":["name","company","projectUrl","referenceLanguage"]},"required":[],"title":"branchCreationPayload"},"def-12":{"nullable":true,"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70,"example":"My awesome project"},"version":{"type":"string","minLength":1,"example":"latest"},"slug":{"type":"string","minLength":1,"example":"0nod9b95"},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"The ID.","example":"a0c79e13-d4a0-402e-b3d0-11793423f745"}},"propertyNames":{"enum":["name","version","slug","id"]},"required":["name","id"],"title":"branchWithId"},"def-13":{"type":"object","properties":{"syncWithParent":{"type":"boolean","default":false}},"propertyNames":{"enum":["syncWithParent"]},"required":[],"title":"branchUpdatePayload"},"def-14":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70,"example":"My awesome project"},"version":{"type":"string","minLength":1,"example":"latest"},"slug":{"type":"string","minLength":1,"example":"0nod9b95"},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"The ID.","example":"a0c79e13-d4a0-402e-b3d0-11793423f745"}},"propertyNames":{"enum":["name","version","slug","id"]},"required":["name","id"]},"title":"branches"}}},"paths":{"/language/{projectId}/{language}":{"post":{"summary":"Add a new language to a project","tags":["languages"],"description":"Add a new language to your project.\nBy default, the language will be added to all versions unless you specify the versions in the request body.\n\n**Permissions:** Requires an appropriate API key with admin role. While the project is still empty (no translation content yet), any write-capable key (user role, or a PAT with write scope) may add languages — so a freshly created project can be bootstrapped via locize-cli sync/migrate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"string","example":"latest"}}},"nullable":true}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"example":"en","in":"path","name":"language","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove language","tags":["languages","projects"],"description":"Remove a language from a project.\n\nOptionally, specify in which versions you want to update languages by providing a body with a versions array.\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"string"},"description":"Versions to update languages in."}},"nullable":true}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"example":"en","in":"path","name":"language","required":true,"description":"The language to remove."}],"responses":{"200":{"description":"Default Response"}}}},"/language/{projectId}":{"put":{"summary":"Update languages for a project","tags":["languages"],"description":"Set the languages for your project at once. Languages not passed in the request are removed.\nYou can update all versions at once (by passing an array) or specify languages per version (by passing an object).\n\n**Permissions:** Requires an appropriate API key with admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"examples":[["en","de"]]},{"type":"object","examples":[{"latest":{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"examples":[["en","de"]]}}]}]},"examples":{"example1":{"value":["en","de"]},"example2":{"value":{"latest":["en","de"]}}}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/version/{projectId}/{version}":{"post":{"summary":"Add a new version to a project","tags":["versions"],"description":"Add a new version to your project.\nOptionally, set autoPublish and cacheControlMaxAge in the request body.\n\n**Permissions:** Requires an appropriate API key with admin role.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]+$"},"example":"v1.2.3","in":"path","name":"version","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove a version","tags":["versions"],"description":"Remove a version from your project.\n\n**Hint:**\n- The response body contains a jobId, which you can use to check if asynchronous action has been completed with the [Get async job](/docs/integration/api#get-async-job-status) endpoint.\n- You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"v1.2.3","in":"path","name":"version","required":true}],"responses":{"200":{"description":"Job started for version removal","content":{"application/json":{"schema":{"description":"Job started for version removal","type":"object","properties":{"jobId":{"$ref":"#/components/schemas/def-2"}}}}}}}}},"/copy/{projectId}/version/{fromVersion}/{version}/{language}":{"post":{"summary":"Copy a language from one version to another","tags":["languages","versions"],"description":"Copy (replace) all translations for a specific language from one version to another.\n\n**Permissions:** Requires an appropriate API key with admin or user role with correct scope. A personal access token copies only for a member with the admin, manager or publisher role, as in the app: a plain user member's token answers 401 `authorizationError.user.notAuthorized` (ask a project admin for the role). A personal access token of a member marked translate only (role user or publisher) may not copy, as a copy replaces the target's keys: 401 `authorizationError.user.translateOnly`. A copy replaces every namespace of the language: a key or token restricted to specific namespaces answers 401 `authorizationError.project.wrongNamespaceScope`.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"fromVersion","required":true},{"schema":{"type":"string","minLength":1},"example":"production","in":"path","name":"version","required":true},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true}],"responses":{"200":{"description":"Job started for copy","content":{"application/json":{"schema":{"description":"Job started for copy","type":"object","properties":{"jobId":{"$ref":"#/components/schemas/def-2"}}}}}},"401":{"description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/create/{projectId}/{version}/{language}/{namespace}":{"post":{"summary":"Create a new namespace in a specific language","tags":["namespaces"],"description":"Create a new namespace for a specific language in your project. A body containing initial values is optional.\n\n**Permissions:** Requires an appropriate API key with admin or user role with correct scope.\n\nInitial values containing script-executing markup (`<script>`, `on*=` event handlers, `javascript:`/`data:text/html` URLs, `srcdoc`) are rejected with a 400 (code `DANGEROUS_MARKUP`) while the project setting \"Block dangerous markup\" is enabled (default), see [issue 312](/docs/checks-issues#issue-312---potentially-dangerous-markup).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true},"examples":{"example1":{"value":{}},"example2":{"value":{"key":"value"}},"example3":{"value":{"another":{"value":"new key","context":{"text":"description for this key"}}}}}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true}],"responses":{"401":{"description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/create/{projectId}/{version}/{namespace}":{"post":{"summary":"Create a new namespace in the reference language","tags":["namespaces"],"description":"Create a new namespace in your project reference language. A body containing initial values is optional.\n\n**Permissions:** Requires an appropriate API key with admin or user role with correct scope.\n\nInitial values containing script-executing markup (`<script>`, `on*=` event handlers, `javascript:`/`data:text/html` URLs, `srcdoc`) are rejected with a 400 (code `DANGEROUS_MARKUP`) while the project setting \"Block dangerous markup\" is enabled (default), see [issue 312](/docs/checks-issues#issue-312---potentially-dangerous-markup).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true},"examples":{"example1":{"value":{}},"example2":{"value":{"key":"value"}},"example3":{"value":{"another":{"value":"new key","context":{"text":"description for this key"}}}}}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true}],"responses":{"401":{"description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/copy/{projectId}/version/{fromVersion}/{version}":{"post":{"summary":"Copy all translations from one version to another","tags":["versions"],"description":"Copy (replace) all translations from one version to another. Useful for releasing or merging translation files between versions.\n\n**Permissions:** Requires an appropriate API key with admin or user role with correct scope. A personal access token copies only for a member with the admin, manager or publisher role, as in the app: a plain user member's token answers 401 `authorizationError.user.notAuthorized` (ask a project admin for the role). A personal access token of a member marked translate only (role user or publisher) may not copy, as a copy replaces the target's keys: 401 `authorizationError.user.translateOnly`. A copy replaces the whole version: a key or token restricted to specific languages or namespaces without a version restriction answers 401 (`wrongLanguageScope` or `wrongNamespaceScope`).","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"ignoreIfVersionExists","required":false},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"fromVersion","required":true},{"schema":{"type":"string","minLength":1},"example":"production","in":"path","name":"version","required":true}],"responses":{"200":{"description":"Job started for copy","content":{"application/json":{"schema":{"description":"Job started for copy","type":"object","properties":{"jobId":{"$ref":"#/components/schemas/def-2"}}}}}},"401":{"description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/delete/{projectId}/{version}/{namespace}":{"delete":{"summary":"Delete a namespace from all languages","tags":["namespaces"],"description":"Delete a namespace from all languages in a specific version of your project.\n\nAs it acts on every language, a key restricted to specific languages answers 401 `authorizationError.project.wrongLanguageScope`.\n\nYou can find your projectId and API Key in your project settings under the API Tab.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/branch/{projectId}":{"delete":{"summary":"Delete a branch project","tags":["branches"],"description":"Delete a branch project by its projectId.\n\nThe response body contains a jobId, which you can use to check if the asynchronous action has been completed with the [Get async job](#get-async-job-status) endpoint.\n\nYou can find your projectId and API Key (requires admin role) in your project settings under the API Tab.","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Job started for branch deletion","content":{"application/json":{"schema":{"description":"Job started for branch deletion","type":"object","properties":{"jobId":{"$ref":"#/components/schemas/def-2"}}}}}}}}},"/download/{projectId}":{"get":{"summary":"List all namespace resources (all versions)","tags":["namespaces"],"description":"Get an overview of all published translation files of your project across all versions.\n\nHTTP GET request:\n`/download/{projectId}`\n\n**Advice:**\nBy providing the appropriate API key as bearer token you can also retrieve information about your private namespace resources. (if using the private publishing feature)\n\nYou can find your projectId and API Key in your project settings under the API Tab.\n\n> **You should not use this endpoint in production.** If you need to know the lastModified timestamp of a specific namespace, you should parse the `last-modified` header in the [Fetch namespace resources](/docs/integration/api#fetch-namespace-resources) response.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.** It lists every published file of the requested scope and is comparatively expensive; do not call it in a loop or on every build.","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/download/{projectId}/{version}":{"get":{"summary":"List all namespace resources for a version","tags":["namespaces"],"description":"Get an overview of all published translation files for a specific version of your project.\n\nHTTP GET request:\n`/download/{projectId}/{version}`\n\n**Advice:**\nBy providing the appropriate API key as bearer token you can also retrieve information about your private namespace resources. (if using the private publishing feature)\n\nYou can find your projectId and API Key in your project settings under the API Tab.\n\n> **You should not use this endpoint in production.** If you need to know the lastModified timestamp of a specific namespace, you should parse the `last-modified` header in the [Fetch namespace resources](/docs/integration/api#fetch-namespace-resources) response.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.** It lists every published file of the requested scope and is comparatively expensive; do not call it in a loop or on every build.","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/download/{projectId}/{version}/{language}":{"get":{"summary":"List all namespace resources for a language","tags":["namespaces"],"description":"Get an overview of all published translation files for a specific language in a version of your project.\n\nHTTP GET request:\n`/download/{projectId}/{version}/{language}`\n\n**Advice:**\nBy providing the appropriate API key as bearer token you can also retrieve information about your private namespace resources. (if using the private publishing feature)\n\nYou can find your projectId and API Key in your project settings under the API Tab.\n\n> **You should not use this endpoint in production.** If you need to know the lastModified timestamp of a specific namespace, you should parse the `last-modified` header in the [Fetch namespace resources](/docs/integration/api#fetch-namespace-resources) response.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.** It lists every published file of the requested scope and is comparatively expensive; do not call it in a loop or on every build.","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/download/{projectId}/{version}/{language}/{namespace}":{"get":{"summary":"Get a specific namespace resource","tags":["namespaces"],"description":"Get the published translation file for a specific namespace in a language and version of your project.\n\nHTTP GET request:\n`/download/{projectId}/{version}/{language}/{namespace}`\n\n**Advice:**\nBy providing the appropriate API key as bearer token you can also retrieve information about your private namespace resources. (if using the private publishing feature)\n\nYou can find your projectId and API Key in your project settings under the API Tab.\n\n> **You should not use this endpoint in production.** If you need to know the lastModified timestamp of a specific namespace, you should parse the `last-modified` header in the [Fetch namespace resources](/docs/integration/api#fetch-namespace-resources) response.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.** It lists every published file of the requested scope and is comparatively expensive; do not call it in a loop or on every build.","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/jobs/{projectId}/{jobId}":{"get":{"summary":"Get async job status","tags":["projects"],"description":"To wait for an async action (i.e. [copy](#copy-all-translations-from-one-version-to-another), [copy language](#copy-a-language-from-one-version-to-another), [publish](#publish-a-version), [remove version](#remove-a-version), [merge branch](#merge-a-branch)) to be completed, you can use this endpoint.\n\nPoll this endpoint with an interval of at least 2 seconds until no job object is returned anymore.\nThe job is done as soon as no job object is returned. Depending on how big your project is it may take also several minutes until the job gets finished. (for example for the [copy version job](#copy-all-translations-from-one-version-to-another))","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"jobId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/pull/{projectId}/{version}/{language}/{namespace}":{"get":{"summary":"Fetch/filter the (unpublished) namespace resources","tags":["namespaces"],"description":"Sometimes in your localization process you want to know which are the translations that are approved by your reviewer. Assuming you have defined some tags to mark translations as approved, with this api you're able to filter by these tags.\n\nIt's a simple HTTP GET request with this url pattern:\n`/pull/{projectId}/{version}/{language}/{namespace}`\n\nWith positive tags filter:\n`/pull/{projectId}/{version}/{language}/{namespace}?tags=[0,2]` (you need to pass the tag index)\n\nIn combination with a negative tags filter:\n`/pull/{projectId}/{version}/{language}/{namespace}?tags=[0,2]&!tags=[1]`\n\nAnother use case could be to track the amount of words changed during a time period. To do this, you can pull the translations at period 1, save this state and the current timestamp and later at period 2 you can pull again with an additional filter.\n\ni.e. get all translations updated after 2017-12-06T19:42:18.139Z (UTC):\n`/pull/{projectId}/{version}/{language}/{namespace}?updatedAt=>1512589338139` (number of milliseconds since 1970/01/01)\n\ni.e. get all translations updated before 2017-12-06T19:42:18.139Z (UTC):\n`/pull/{projectId}/{version}/{language}/{namespace}?updatedAt=<1512589338139`\n\nIn the same way there is also the `createdAt` filter.\n\nAdditionally another use case could be to remove unused translations. (This is only possible if you make use of the [Used translations](/docs/guides/find-unused-translations) endpoint) To do this, you can pull the translations with an additional filter.\n\ni.e. get all translations used after 2017-12-06T19:42:18.139Z (UTC):\n`/pull/{projectId}/{version}/{language}/{namespace}?lastUsed=>1512589338139` (number of milliseconds since 1970/01/01)\n\ni.e. get all translations used before 2017-12-06T19:42:18.139Z (UTC):\n`/pull/{projectId}/{version}/{language}/{namespace}?lastUsed=<1512589338139`\n\nYou can also ask for more segment information with the query parameter **raw=true**. On the reference language this includes the character limit (`maxCharacters`) of a key, if one is set. On an AI translation scored by quality estimation or AI review it includes the confidence between 0 and 1 (`qeScore`) and its reason (`qeScoreReason`).\n\n> **You should not use this endpoint in production.** To fetch the translation in production, please use the [Fetch namespaces resources endpoint](/docs/integration/api#fetch-namespace-resources).\n> **Each of these requests counts as a [*private* download](/pricing).** Private downloads are included from the Growth plan on (and metered on the usage-based plan); on plans without them (Free, Starter, Starter-Plus) this endpoint answers with `403 TierLimitExceeded`. Trial projects can use it.","parameters":[{"schema":{"type":"string"},"example":"[0,2]","in":"query","name":"tags","required":false,"description":"Comma-separated tag indices to include."},{"schema":{"type":"string"},"example":"[0,2]","in":"query","name":"!tags","required":false,"description":"Comma-separated tag indices to exclude."},{"schema":{"oneOf":[{"type":"string","examples":[">1512589338139"],"description":"Filter by updatedAt (milliseconds since epoch, use > or <)."},{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2,"description":"Range filter for updatedAt."}]},"in":"query","name":"updatedAt","required":false},{"schema":{"oneOf":[{"type":"string","examples":[">1512589338139"],"description":"Filter by createdAt (milliseconds since epoch, use > or <)."},{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2,"description":"Range filter for createdAt."}]},"in":"query","name":"createdAt","required":false},{"schema":{"oneOf":[{"type":"string","examples":[">1512589338139"],"description":"Filter by lastUsed (milliseconds since epoch, use > or <)."},{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2,"description":"Range filter for lastUsed."}]},"in":"query","name":"lastUsed","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"raw","required":false,"description":"If true, returns detailed segment information."},{"schema":{"type":"string","enum":["json_auto","json_flat","json_nested"]},"in":"query","name":"format","required":false,"description":"Output format."},{"schema":{"type":"string"},"in":"query","name":"next","required":false,"description":"Pagination token for next page."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true,"description":"The version to fetch."},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true,"description":"The language to fetch."},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true,"description":"The namespace to fetch."}],"responses":{"200":{"description":"Namespace translations (filtered, unpublished)","headers":{"X-Next-Page":{"schema":{"schema":{"type":"string"},"required":false},"description":"Base64-encoded pagination token for the next page. Only present when the `next` query parameter is used and more pages are available."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"simple":{"summary":"Simple key-value translations","value":{"app":"Average App","benefits":"Benefits","blog":"Blog","privacy":"privacy policy","terms":"terms of service"}},"raw":{"summary":"Detailed segment information","value":{"app":{"value":"Average App","tags":[null,true],"context":{"text":"This text is placed..."},"quality":"MT","maxCharacters":20,"updatedAt":1610004393330}}}}}}}}}},"/branches/{projectId}":{"get":{"summary":"List all branches of project","tags":["branches"],"description":"List all branches of a project.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.**\n> **There should be no need to fetch this information in a live-system. The information returned by this endpoint should be stored/cached on your side.**\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"List of branches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-14"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"description":"Too Many Requests","type":"object","properties":{"name":{"type":"string","example":"ThrottlingError"},"type":{"type":"string","example":"throttlingError.project.tooManyRequests"},"message":{"type":"string","example":"Too Many Requests: Please review your workflow or contact our support!"}}}}}}}}},"/stats/project/{projectId}":{"get":{"summary":"Statistics: project","tags":["statistics","projects"],"description":"Retrieve project statistics, similar to the overview images in the Locize UI.\n\nPer namespace: translated and untranslated ratios (0-1), segmentsTranslated and segmentsTotal, and the review queue: segmentsNeedsReview (live values marked as needing review) and segmentsPendingReview (proposals waiting for a decision). A count that is zero is omitted.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.**\n\nSend `Accept-Encoding: br` (Node.js `fetch`, browsers and `curl --compressed` do, and decode the answer automatically): for projects with many versions, languages and namespaces the response is then brotli-compressed (`Content-Encoding: br`), because uncompressed it can exceed the maximum response size.\n\n*(You can find your projectId and API Key in your project settings under the API Tab.)*","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Project statistics overview","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"example":{"summary":"Example response","value":{"latest":{"en":{"ns1":{"translated":1,"untranslated":0,"ordered":0,"segmentsTranslated":10,"segmentsTotal":10,"segmentsNeedsReview":2,"segmentsPendingReview":1},"anotherNamespace":{"translated":1,"untranslated":0,"ordered":0,"segmentsTranslated":1,"segmentsTotal":1}},"de":{"ns1":{"translated":0.7,"untranslated":0.3,"ordered":0,"segmentsTranslated":7,"segmentsTotal":10},"anotherNamespace":{"translated":1,"untranslated":0,"ordered":0,"segmentsTranslated":1,"segmentsTotal":1}}},"prod":{"en":{"ns1":{"translated":1,"untranslated":0,"ordered":0,"segmentsTranslated":5,"segmentsTotal":5},"anotherNamespace":{"translated":1,"untranslated":0,"ordered":0,"segmentsTranslated":1,"segmentsTotal":1}},"de":{"ns1":{"translated":1,"untranslated":0,"ordered":0,"segmentsTranslated":5,"segmentsTotal":5},"anotherNamespace":{"translated":0.71,"untranslated":0.28,"ordered":0,"segmentsTranslated":5,"segmentsTotal":7}}}}}}}}}}}},"/tags/{projectId}":{"get":{"summary":"Fetch configured project tags","tags":["projects"],"description":"Fetch the tags configured for a project, e.g. to mark translations as approved.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.**\n\n*(You can find your projectId and API Key in your project settings under the API Tab.)*","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"List of project tags","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","nullable":true}},"examples":{"example":{"summary":"Example response","value":["translated",null,"reviewed","approved"]}}}}}}}},"/tenants/{projectId}":{"get":{"summary":"List all tenants of project","tags":["tenants","projects"],"description":"List all tenants of a project.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.**\n> **There should be no need to fetch this information in a live-system. The information returned by this endpoint should be stored/cached on your side.**\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"List of tenants","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-10"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"description":"Too Many Requests","type":"object","properties":{"name":{"type":"string","example":"ThrottlingError"},"type":{"type":"string","example":"throttlingError.project.tooManyRequests"},"message":{"type":"string","example":"Too Many Requests: Please review your workflow or contact our support!"}}}}}}}}},"/stats/user-translation/{projectId}/{userId}":{"get":{"summary":"Statistics: user","tags":["statistics","users","projects"],"description":"Retrieve statistics for a specific user in a project.\n\nTo retrieve another amount of months than the last 12, set the query parameter `months` with the appropriate value.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.**\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","parameters":[{"schema":{"type":"number","maximum":37},"in":"query","name":"months","required":false,"description":"Amount of months to look back (default: 12, capped by the plan's stats history)"},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"userId","required":true,"description":"The user ID."}],"responses":{"200":{"description":"Statistics for the user in the project","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}},"examples":{"example":{"summary":"Example response","value":[{"userId":"ba175147-c7a3-45d2-9b24-739ae2ed948c","year":2026,"month":2,"period":"2026-03","savedWords":23,"modifications":6,"modificationsSave":5,"modificationsDelete":1,"translatedHT":2,"translatedMT":1,"translatedTM":1,"translatedAI":1,"aiTokens":123,"mtChars":20,"updatedAt":1514926256221}]}}}}}}}},"/users/{projectId}":{"get":{"summary":"Fetch users","tags":["users","projects"],"description":"Retrieve all users of a project.\n\n> **You should use this endpoint sparingly. A few (1-10) requests per hour.**\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"List of users for the project","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}},"examples":{"example":{"summary":"Example response","value":[{"id":"ba175147-c7a3-45d2-9b24-739ae2ed948c","firstname":"George","lastname":"Winston","username":"gg.win","email":"george.user@somewhere-in-the-universe.com","role":"user","scope":{"languages":["en","de"],"versions":["latest","preprod"]}}]}}}}}}}},"/invite/{projectId}":{"post":{"summary":"Invite new users","tags":["users","projects"],"description":"Invite a new user to a project.\n\nThe body contains:\n- **email** the user's email address\n- **role** can be \"user\" or \"publisher\" or \"manager\" (default: \"user\") — admin and accountant are organization-level roles since the organization release and are granted there\n- **scope** is an object describing a scope restriction (default: empty arrays for versions, languages and namespaces)\n\nTo skip sending the email automatically set the query parameter `send` to false. This will not send any email. This way you can send the invitation mail by your own, if you want to.\n\nA personal access token of a member restricted to specific versions, languages or namespaces invites only inside that restriction (the invitation's scope must stay within it): otherwise 401 `authorizationError.user.grantBeyondOwnPermission`, as in the app.\n\nOn a project without a subscription, at most 10 invitation emails per hour are sent (an API key counts for its project, a personal access token for its user, shared with the invitations sent in the app); further ones answer 429. Invitations with `send=false` mail nothing and do not count.\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"The user's email address."},"role":{"type":"string","enum":["admin","user","publisher","manager","accountant"],"description":"User role (default: user). For projects that belong to an organization, admin/accountant are organization-level roles and are granted there."},"scope":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"string"},"description":"Scope restriction for versions."},"languages":{"type":"array","items":{"type":"string"},"description":"Scope restriction for languages."},"namespaces":{"type":"array","items":{"type":"string"},"description":"Scope restriction for namespaces."}},"description":"Scope restriction object."}}}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"send","required":false,"description":"Set to false to skip sending the email."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Invitation created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"example":{"summary":"Example response","value":{"code":"LL4mHDzyxKn4cKYP","role":"user","email":"new.user@somewhere-in-the-universe.com","scope":{"languages":["en","de"],"versions":["latest","preprod"]},"link":"https://www.locize.app/register?invitation=LL4mHDzyxKn4cKYP"}}}}}}}}},"/branch/merge/{projectId}":{"post":{"summary":"Merge a branch","tags":["branches","projects"],"description":"Merge a branch into its parent project.\n\nMerging writes into the parent project, so use the parent project's API key (a key created on the branch itself is refused) or a personal access token of an admin or manager of the parent project. A blocked or paused parent project takes no merge.\n\n***Hint:***\n- The response body contains a jobId, which you can use to check if asynchronous action has been completed with the *Get async job* endpoint.\n\n*(You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.)*","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"delete","required":false,"description":"Set to true to delete the branch after merging."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Job started for branch merge","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"The job ID for the async merge operation."}},"required":["jobId"]},"examples":{"example":{"summary":"Example response","value":{"jobId":"16a6631d-6439-4e4c-bbd3-3196d87dfdf8"}}}}}}}}},"/publish/{projectId}/{version}":{"post":{"summary":"Publish a version","tags":["versions"],"description":"If you want to fully automate your CI/CD pipeline by publishing a version exactly at the same time when you deploy a new version of your product this API call is exactly what you are looking for.\n\nFor parent projects in a [multi-tenant](/docs/multi-tenant) setup, you can optionally pass the query parameter `?tenants=true` to automatically publish also all tenant projects.\nFor parent projects with [branches](/docs/general-questions/should-i-use-versions-or-branches), you can optionally pass the query parameter `?branches=true` to automatically publish also all branched projects.\n\n**Hint:**\n- The response body contains a jobId, which you can use to check if asynchronous action has been completed with the [Get async job](/docs/integration/api#get-async-job-status) endpoint.\n- You can find your projectId and API Key in your project settings under the API Tab. Keep in mind to use the API Key for the correct `{version}`.\n- Publishing acts on the whole version: a key or token restricted to specific languages or namespaces without a version restriction answers 401 (`authorizationError.project.wrongLanguageScope` or `wrongNamespaceScope`), as in the app.\n- A personal access token publishes only for a member with the admin, manager or publisher role, as in the app: a plain user member's token answers 401 `authorizationError.user.notAuthorized` (ask a project admin for the role).","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"tenants","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"branches","required":false},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true}],"responses":{"200":{"description":"Job started for version publish","content":{"application/json":{"schema":{"description":"Job started for version publish","type":"object","properties":{"jobId":{"$ref":"#/components/schemas/def-2"}}}}}},"401":{"description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/missing/{projectId}/{version}/{language}/{namespace}":{"post":{"summary":"Missing translations","tags":["translations"],"description":"Report missing translations to Locize. This does not replace existing translations.\n\nAdvice:\n- You should post missing translation to the reference language first!\n- If you send more than 1000 keys, you have to page your request. This means you have to create multiple requests and send a maximum of 1000 keys per request.\n- Do NOT send concurrent/parallel requests for the same namespace. Send them sequentially (await each request before sending the next). Parallel requests to the same namespace contend on the same storage partition, slow each other down, and may be rejected with a 429.\n- If you get a 412 status code, this means it was an unnecessary request and nothing was missing. If the publishing mode for the requested version is set to manual, you may want to set it to auto publish.\n- If you get a 400 status code with code `DANGEROUS_MARKUP`, a changed value contains script-executing markup (`<script>`, `on*=` event handlers, `javascript:`/`data:text/html` URLs, `srcdoc`) and the project setting \"Block dangerous markup\" is enabled (default). Remove the markup or disable the setting, see [issue 312](/docs/checks-issues#issue-312---potentially-dangerous-markup).\n- This request does not generate modification costs in contrast to the update request.\n\n> **You should not use this endpoint in production.** Read [this guide](/docs/guides/going-to-production) before you're going to production.\n\n*(You can find your projectId and API Key in your project settings under the API Tab.)*","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"example1":{"value":{"summary":"Simple missing keys","value":{"new.key":"default value","another.new.key":"another default value"}}},"example2":{"value":{"summary":"Missing keys with context","value":{"new.key":{"value":"default value","context":{"text":"description for this key"}},"another.new.key":"another default value"}}},"example3":{"value":{"summary":"Missing keys with tags","value":{"new.key":{"value":"default value","tags":[true,false]},"another.new.key":"another default value"}}}}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"autotranslate","required":false,"description":"If false, suppress automatic translation for new keys (overrides project setting). If omitted, default behavior applies (new keys auto-translated if project setting is enabled)."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"autotranslatereview","required":false,"description":"If true, automatic translations arrive as review proposals (for languages that have review proposals enabled) instead of being written directly."},{"schema":{"type":"string"},"in":"query","name":"autotranslatelanguages","required":false,"description":"Comma-separated list of target languages to restrict auto-translation to (e.g. \"de,fr\"). Only effective when auto-translation is triggered and the updated language is the reference language. If omitted, all non-reference languages are auto-translated."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true,"description":"The version to report missing translations for."},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true,"description":"The language to report missing translations for."},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true,"description":"The namespace to report missing translations for."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","additionalProperties":true}}}},"400":{"description":"Bad Request (invalid body, or a changed value contains potentially dangerous markup while \"Block dangerous markup\" is enabled)","content":{"application/json":{"schema":{"description":"Bad Request (invalid body, or a changed value contains potentially dangerous markup while \"Block dangerous markup\" is enabled)","type":"object","properties":{"name":{"type":"string","example":"ValidationError"},"code":{"type":"string","example":"DANGEROUS_MARKUP"},"type":{"type":"string","example":"validationError.namespace.dangerousMarkup"},"more":{"type":"array","items":{"type":"string"},"example":["search.nothingFound"]},"message":{"type":"string","example":"Bad Request: key \"search.nothingFound\" contains potentially dangerous markup (eventHandler: <img src=x onerror=\"…\">). Script-executing markup (<script> tags, on*= event handlers, javascript:/data:text/html URLs, srcdoc) is rejected while \"Block dangerous markup\" is enabled in the project settings. Remove the markup or disable the setting. Docs: https://www.locize.com/docs/checks-issues#issue-312---potentially-dangerous-markup"}}}}}},"412":{"description":"Unnecessary Request","content":{"application/json":{"schema":{"description":"Unnecessary Request","type":"object","properties":{"name":{"type":"string","example":"ValidationError"},"type":{"type":"string","example":"validationError.namespace.nothingMissing"},"message":{"type":"string","example":"Unnecessary Request: Nothing was missing!"}}}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"description":"Too Many Requests","type":"object","properties":{"name":{"type":"string","example":"ThrottlingError"},"type":{"type":"string","example":"throttlingError.project.tooManyRequests"},"message":{"type":"string","example":"Too Many Requests: Please review your workflow or contact our support!"}}}}}}}}},"/rename/{projectId}/{version}/{namespace}/{toNamespace}":{"post":{"summary":"Rename a namespace in all languages","tags":["namespaces","projects"],"description":"Rename a namespace in all languages for a given project and version.\n\nAs it acts on every language, a key restricted to specific languages answers 401 `authorizationError.project.wrongLanguageScope`.\n\n*(You can find your projectId and API Key in your project settings under the API Tab.)*","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"cascade","required":false,"description":"If set to true, it will execute this also on all tenants."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true,"description":"The version."},{"schema":{"type":"string","minLength":1},"example":"translation","in":"path","name":"namespace","required":true,"description":"The namespace to rename."},{"schema":{"type":"string","minLength":1},"example":"renamed-translation","in":"path","name":"toNamespace","required":true,"description":"The new namespace name."}],"responses":{"200":{"description":"Default Response"}}}},"/tenant/create/{projectId}":{"post":{"summary":"Create a new tenant project","tags":["tenants"],"description":"Creates a new tenant project for the given project. The body must contain the tenant project's name. Optional fields: company, projectUrl, syncWithParent (default: true), canEditLanguages (default: false), referenceLanguage. On a subscribed parent project the tenant is billed together with the parent from the moment it is created (the deprecated subscribeToParent field is ignored). The tenant also joins the parent project's organization. The response will include the tenant id, which can be used in other API endpoints. You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-7"}}}},"parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-8"}}}}}}},"/tenant/update/{projectId}/{tenantProjectId}":{"put":{"summary":"Update tenant project settings","tags":["tenants"],"description":"Updates the syncWithParent and canEditLanguages properties of a tenant project. Only accessible to admin users. The response will include the tenant id, which can be used in other API endpoints. You can find your projectId and API Key (requires admin role) in your project settings under the API Tab.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-9"}}}},"parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"tenantProjectId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-8"}}}}}}},"/branch/create/{projectId}/{version}":{"post":{"summary":"Create a new branched project","tags":["branches"],"description":"Creates a new branch for the given project. The body may contain the branch's name; without one the branch is named after its parent project and the date. The response will include the branch id, which can be used in other API endpoints. You can find your projectId and API Key (requires admin role) in your project settings under the API Tab. The branch follows its parent project's organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-11"}}}},"parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"examples":{"v1.2.3":{"value":"v1.2.3"},"latest":{"value":"latest"}},"in":"path","name":"version","required":true,"description":"The version to branch from."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-12"}}}}}}},"/update/{projectId}/{version}/{language}/{namespace}":{"post":{"summary":"Update or remove translations","tags":["translations"],"description":"Update or delete translations. Useful for integrating with other systems.\n\n---\n\nTo completely replace a namespace, set the query parameter `replace` to `true`. This will remove all the keys in that namespace that are not included in your body. **If you have more than 1000 keys in a namespace, we recommend NOT using the `replace` parameter, as this will probably delete more keys than you want to.**\n\nIf you need to change or remove multiple keys, please do not create a single HTTP request per key, but put them together in batches of maximum 1000 keys.\n\n---\n\n#### Example\n\n```bash\nbody=$(cat << EOF\n{\n  \"new.key\": \"default value\",\n  \"another.existing.key\": \"another changed value\",\n  \"a.key.to.delete\": null\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/landingpage\n# or (Be aware, using the replace=true parameter will delete all non passed keys!):\n# curl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/landingpage?replace=true\n```\n\n---\n\n#### Optional context\nAdd context information for a specific translation.\n\n```bash\nbody=$(cat << EOF\n{\n  \"new.key\": {\n    \"value\": \"default value\",\n    \"context\": {\n      \"text\": \"description for this key\"\n    }\n  },\n  \"another.existing.key\": \"another changed value\",\n  \"a.key.to.delete\": null\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/landingpage\n```\n\n---\n\n#### Optional tags\nAdd tags for a specific translation.\n\n```bash\nbody=$(cat << EOF\n{\n  \"new.key\": {\n    \"value\": \"default value\",\n    \"tags\": [true, false]\n  },\n  \"another.new.key\": \"another default value\"\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/landingpage\n```\n\n---\n\n#### Optional quality (the source of the text)\nWho produced the text: HT = a human, TM = translation memory, MT = machine translation, AI = generative AI. It is a record, not a judgement; MT and AI values are marked as needing review according to the project rule for machine output (all, low confidence only, or off) (see needsReview below).\n\n```bash\nbody=$(cat << EOF\n{\n  \"new.key\": {\n    \"value\": \"default value\",\n    \"quality\": \"MT\" // MT = Machine Translation, AI = generative AI, TM = Translation Memory, HT = Human Translation\n  },\n  \"another.new.key\": \"another default value\"\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/landingpage\n```\n\n---\n\n#### Optional needsReview\nMark a translation as needing a human look, or confirm it. The value stays live and published either way; marked segments show up in the editor's \"needs review\" queue and in the per-language counts. Values pushed with quality `MT` or `AI` follow the project's rule for machine output (marked by default, and a later change of the rule reaches them too); a boolean in the payload always wins. A value pushed without the field confirms that key. Confirming a marked key without changing its text (`needsReview: false`) is the review step: with a personal access token of a member with the user role, it needs the review right in the project, as in the editor (401 otherwise).\n\n```bash\nbody=$(cat << EOF\n{\n  \"new.key\": {\n    \"value\": \"Willkommen\",\n    \"quality\": \"AI\",\n    \"needsReview\": true\n  },\n  \"another.existing.key\": {\n    \"needsReview\": false\n  }\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/de/landingpage\n```\n\n---\n\n#### Optional review\nCreate review proposals instead of writing the values (the language needs review proposals enabled). Only keys whose text changes become proposals. Context and tags are not saved with a proposal: send them on their own, without the text, in a push without review. A quality sent with a value travels with the proposal and becomes the value's quality once accepted; the accept is the human check, so the value is not marked as needing review.\n\n```bash\nbody=$(cat << EOF\n{\n  \"a.key\": \"esto se añadirá automáticamente\",\n  \"meal\": \"me gusta comer pan\"\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/es/common?review=true\n```\n\n---\n\n#### Optional autotranslate\nBy default, new keys get automatically translated. To trigger automatic translation for existing keys, use this option.\n\n```bash\nbody=$(cat << EOF\n{\n  \"an.existing.key\": \"This will get automatically translated\",\n  \"a.new.key\": \"And this will get automatically translated anyway\"\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/common?autotranslate=true\n```\n\n---\n\n#### Optional autotranslatereview\nWhen automatic translation is triggered, the results arrive as review proposals instead of being written directly. Only effective for target languages that have review proposals enabled.\n\n```bash\nbody=$(cat << EOF\n{\n  \"a.new.key\": \"This will get automatically translated and sent to review\"\n}\nEOF\n)\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer <API_KEY>\" -d \"$body\" https://api.locize.app/update/3d0aa5aa-4660-4154-b6d9-907dbef10bb2/latest/en/common?autotranslate=true&autotranslatereview=true\n```\n\n---\n\n#### Advice\n\n- You should post translation to the reference language first!\n- If you send more than 1000 keys, you have to page your request. This means you have to create multiple requests and send a maximum of 1000 keys per request. If this is the case, please do not use the `replace` query parameter.\n- Do NOT create a single request per individual key, but include up to 1000 keys in a single request.\n- Do NOT send concurrent/parallel requests for the same namespace. Send them sequentially (await each request before sending the next). Parallel updates to the same namespace contend on the same storage partition, slow each other down, and may be rejected with a 429.\n- If you get a 429 status code, this means you are sending too many requests for the same namespace and should slow down to send requests and/or make sure you're NOT creating a single request per key.\n- If you get a 412 status code, this means it was an unnecessary request and nothing did change. If the publishing mode for the requested version is set to manual, you may want to set it to auto publish.\n- If you get a 400 status code with code `DANGEROUS_MARKUP`, a changed value contains script-executing markup (`<script>`, `on*=` event handlers, `javascript:`/`data:text/html` URLs, `srcdoc`) and the project setting \"Block dangerous markup\" is enabled (default). Remove the markup or disable the setting, see [issue 312](/docs/checks-issues#issue-312---potentially-dangerous-markup).\n- Do not use the review option in combination with the replace option.\n- A personal access token of a member marked translate only (role user or publisher) may not delete keys: a key sent as `null`, an object with `value: null` or `toDelete`, a deletion proposal and `replace=true` answer 401 `authorizationError.user.translateOnly`.\n- You can find your projectId and API Key in your project settings under the API Tab.\n\n> **You should not use this endpoint in production.** Read [this guide](/docs/guides/going-to-production) before you're going to production.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"examples":{"example1":{"value":{"new.key":"default value","another.existing.key":"another changed value","a.key.to.delete":null}},"example2":{"value":{"new.key":{"value":"default value","context":{"text":"description for this key"}},"another.existing.key":"another changed value","a.key.to.delete":null}},"example3":{"value":{"new.key":{"value":"default value","tags":[true,false]},"another.new.key":"another default value"}},"example4":{"value":{"new.key":{"value":"default value","quality":"MT"},"another.new.key":"another default value"}},"example5":{"value":{"new.key":{"value":"Willkommen","quality":"AI","needsReview":true},"another.existing.key":{"needsReview":false}}}}}}},"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"replace","required":false,"description":"If true, completely replace the namespace."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"review","required":false,"description":"If true, create review proposals instead of writing the values."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"autotranslate","required":false,"description":"If true, trigger automatic translation for existing keys. If false, suppress automatic translation even for new keys (overrides project setting). If omitted, default behavior applies (new keys auto-translated if project setting is enabled)."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"autotranslatereview","required":false,"description":"If true, automatic translations arrive as review proposals (for languages that have review proposals enabled) instead of being written directly. Only effective when auto-translation is triggered."},{"schema":{"type":"string"},"in":"query","name":"autotranslatelanguages","required":false,"description":"Comma-separated list of target languages to restrict auto-translation to (e.g. \"de,fr\"). Only effective when auto-translation is triggered and the updated language is the reference language. If omitted, all non-reference languages are auto-translated."},{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]+$"},"example":"latest","in":"path","name":"version","required":true,"description":"The version to update."},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true,"description":"The language to update."},{"schema":{"type":"string","minLength":1},"example":"landingpage","in":"path","name":"namespace","required":true,"description":"The namespace to update."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","additionalProperties":true}}}},"400":{"description":"Bad Request (invalid body, or a changed value contains potentially dangerous markup while \"Block dangerous markup\" is enabled)","content":{"application/json":{"schema":{"description":"Bad Request (invalid body, or a changed value contains potentially dangerous markup while \"Block dangerous markup\" is enabled)","type":"object","properties":{"name":{"type":"string","example":"ValidationError"},"code":{"type":"string","example":"DANGEROUS_MARKUP"},"type":{"type":"string","example":"validationError.namespace.dangerousMarkup"},"more":{"type":"array","items":{"type":"string"},"example":["search.nothingFound"]},"message":{"type":"string","example":"Bad Request: key \"search.nothingFound\" contains potentially dangerous markup (eventHandler: <img src=x onerror=\"…\">). Script-executing markup (<script> tags, on*= event handlers, javascript:/data:text/html URLs, srcdoc) is rejected while \"Block dangerous markup\" is enabled in the project settings. Remove the markup or disable the setting. Docs: https://www.locize.com/docs/checks-issues#issue-312---potentially-dangerous-markup"}}}}}},"401":{"description":"Unauthorized: the credential, its role, its restriction or the member behind a personal access token (the route description names the cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}},"412":{"description":"Unnecessary Request","content":{"application/json":{"schema":{"description":"Unnecessary Request","type":"object","properties":{"name":{"type":"string","example":"ValidationError"},"type":{"type":"string","example":"validationError.namespace.nothingChanged"},"message":{"type":"string","example":"Unnecessary Request: Nothing changed!"}}}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"description":"Too Many Requests","type":"object","properties":{"name":{"type":"string","example":"ThrottlingError"},"type":{"type":"string","example":"throttlingError.project.tooManyRequests"},"message":{"type":"string","example":"Too Many Requests: Please review your workflow or contact our support!"}}}}}}}}},"/used/{projectId}/{version}/{language}/{namespace}":{"post":{"summary":"Report used translations","tags":["translations"],"description":"Report which translations are used. Locize will remember when translations were last used.\n\n**Advice:** To best work with the \"not used for\" filter in the UI, you may do this request for your reference language. If you send more than 1000 keys, you have to page your request (max 1000 keys per request). **You should not use this endpoint in production.** Read [this guide](/docs/guides/going-to-production) before you're going to production.\n\nYou can find your projectId and API Key in your project settings under the API Tab.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"string","description":"Translation key."}},"example":["new.key","another.new.key"]}}},"parameters":[{"schema":{"$ref":"#/components/schemas/def-2"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string","minLength":1},"example":"latest","in":"path","name":"version","required":true,"description":"The version to report usage for."},{"schema":{"type":"string","minLength":1},"example":"en","in":"path","name":"language","required":true,"description":"The language to report usage for."},{"schema":{"type":"string","minLength":1},"example":"landingpage","in":"path","name":"namespace","required":true,"description":"The namespace to report usage for."}],"responses":{"200":{"description":"Default Response"}}}},"/{projectId}/{version}/{language}/{namespace}":{"get":{"tags":["cdn","translations","namespaces"],"summary":"Fetch namespace resources","description":"Retrieve all translations for a given namespace, version, and language.\n\nEach of these requests counts as [download](/pricing) for your next invoice.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"example":"a0c79e13-d4a0-402e-b3d0-11793423f745","description":"The unique identifier of the project."},{"name":"version","in":"path","required":true,"schema":{"type":"string"},"example":"latest","description":"The version of the translations to fetch."},{"name":"language","in":"path","required":true,"schema":{"type":"string"},"example":"en","description":"The language code for the translations."},{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"example":"translation","description":"The namespace to fetch translations for."}],"security":[],"responses":{"200":{"description":"Namespace translations","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}},"examples":{"example":{"value":{"app":"Average App","benefits":"Benefits","blog":"Blog","privacy":"privacy policy","terms":"terms of service"}}}}}}}}},"/private/{projectId}/{version}/{language}/{namespace}":{"get":{"tags":["cdn","translations","namespaces"],"summary":"Fetch private namespace resources","description":"Retrieve translations from a private namespace, protected by an API key.\n\nEach of these requests counts as [*private* download](/pricing) for your next invoice.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"example":"a0c79e13-d4a0-402e-b3d0-11793423f745","description":"The unique identifier of the project."},{"name":"version","in":"path","required":true,"schema":{"type":"string"},"example":"latest","description":"The version of the translations to fetch."},{"name":"language","in":"path","required":true,"schema":{"type":"string"},"example":"en","description":"The language code for the translations."},{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"example":"translation","description":"The namespace to fetch translations for."}],"responses":{"200":{"description":"Private namespace translations","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}},"examples":{"example":{"value":{"app":"Average App","benefits":"Benefits","blog":"Blog","privacy":"privacy policy","terms":"terms of service"}}}}}}}}},"/languages/{projectId}":{"get":{"tags":["cdn","languages"],"summary":"Fetch the available languages","description":"Retrieve all languages available for a project, useful for dynamic language selectors.\n\nThis request has a minimum cache duration of 1 hour.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"example":"a0c79e13-d4a0-402e-b3d0-11793423f745","description":"The unique identifier of the project."}],"security":[],"responses":{"200":{"description":"Available languages","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"nativeName":{"type":"string"},"isReferenceLanguage":{"type":"boolean"},"region":{"type":"string"},"translated":{"type":"object","additionalProperties":{"type":"number"}}}}},"examples":{"example":{"value":{"en":{"name":"English","nativeName":"English","isReferenceLanguage":true,"translated":{"latest":1,"production":1}},"de-CH":{"name":"German","nativeName":"Deutsch","region":"CH","isReferenceLanguage":false,"translated":{"latest":1,"production":0.521}},"it":{"name":"Italian","nativeName":"Italiano","isReferenceLanguage":false,"translated":{"latest":1,"production":1}}}}}}}}}}}},"servers":[{"url":"https://api.locize.app"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"cdn","description":"Endpoints for CDN resource fetching."},{"name":"translations","description":"Fetch, update, report missing/used translations, and manage translation content."},{"name":"namespaces","description":"Manage translation namespaces: create, rename, delete, and fetch namespace resources."},{"name":"languages","description":"Manage project languages: add, remove, update, and list available languages."},{"name":"versions","description":"Versioning: copy, publish, add, remove, and manage translation versions."},{"name":"users","description":"User and invitation management for projects."},{"name":"tenants","description":"Multi-tenant project management."},{"name":"branches","description":"Branching and branch management for projects."},{"name":"statistics","description":"Project and user statistics endpoints."},{"name":"projects","description":"Other project related stuff."}]}