Skip to main content
Use this API on native projects to read and update strings, set tags and design links, attach Figma links, upload screenshots and mark keys on them, approve or unverify translations in bulk, and manage key jobs. Everything on this page, including creating, completing and cancelling jobs, uses the public API host.

Base URL and authentication

Send the same personal access token as Projects and Queries:
External TMS projects return 409 with project_not_native for string and translation writes.

Permissions

A token never grants more than its owner’s role allows. See Roles and permissions. The interactive reference and OpenAPI document list every field and error code.

Pick strings in bulk

Bulk routes take one selector: Tag and design-link updates and batch review refuse selections larger than 1,000 strings (too_many_strings). Adding strings to a key job allows up to 5,000. Tags match the Content Editor: 1–64 characters, letters, digits, _, or -. Strings include tags and designUrl (a link such as a Figma frame). List strings with a repeatable tag query parameter; each value narrows the list (AND). Tag many strings and set a design link in one call:
The response is { "updated": <count> }. Send "designUrl": null to clear the link. Use removeTags to drop tags without adding others. Only the bulk-update route writes tags and links; single-string PATCH, create, and batch upsert do not.

Custom metadata

Keep your own text on a string, such as a ticket or a source system’s ID, in customMetadata. Send it as an object of string values when you create a string. On PATCH /v1/projects/{projectId}/strings/{stringId}, customMetadata is merged: a string sets a key, null removes it, and keys you leave out stay.
Keys are 1–64 letters, digits, _, ., or -, starting with a letter or digit. Values are up to 2,000 characters, and a string holds at most 50 keys. GET /v1/string-metadata-keys lists the keys in use across the projects you can access (add projectId for one project), with how many strings carry each key. Custom metadata is only for API integrations. Linguists and machine translation don’t see it, so put guidance for translators in context.

Search strings

POST /v1/projects/{projectId}/strings/search takes the list filters in a JSON body, so one call can check up to 1,000 key names and return up to 1,000 strings. Filters combine with AND:
The response has strings, pagination, and missingKeys: the requested keys, in request order, that name no string in the project (in any file, hidden or not). Use it to find which keys to create before you add strings to a key job.

Screenshots

Upload a PNG, JPEG, or WebP (1 byte to 10 MB) in three steps. The image is the same visual context the Content Editor shows; markers are percent boxes on that image.
  1. Create a pending screenshot. The response includes a time-limited PUT URL and the headers to send with it.
  2. PUT the image bytes to that URL.
  3. Finalize. The screenshot becomes ready and imageUrl is a time-limited download.
PUT the file to upload.url with upload.headers, then:
Each marker picks a string with stringId, or key (and filePath when the key exists in more than one file). A missing filePath on an ambiguous key returns 400 ambiguous_key. List a screenshot’s markers with GET .../screenshots/{screenshotId}/markers, and add or replace them later with POST on the same path. Delete one marker or the whole screenshot with DELETE. List screenshots with GET .../screenshots. Filter with stringId or key. Figma-synced frames appear here with figmaUrl; this API does not write Figma fields. The Figma plugin still syncs frames on its own. Without object storage the write routes return 503 screenshot_storage_unavailable.

Figma attachments

A Figma attachment is the Figma file or frame that strings’ design links point at. It reads and writes the same designUrl that the Content Editor shows in key details, so linguists see the link with no other step. Links to the same file and node-id group together, however they are spelled. Each string has one design link.
  1. Get the attachment for a link. The response has its id, such as AbC123.12-345 (the file key, plus the node when the link names one), and stringCount. Nothing is stored; the id is derived from the link.
  2. Link the request’s strings. Pick them with one of stringIds, keys, or tags (at most 1,000). Linking sets each string’s designUrl to the attachment’s url and replaces any other link the string had.
linked counts the strings whose link changed. List the project’s attachments with GET .../figma-attachments (add stringId to get the one a string links to), and an attachment’s strings with GET .../figma-attachments/{attachmentId}/strings. DELETE .../strings with the same selection clears the link from those strings. DELETE .../figma-attachments/{attachmentId} clears it from every string. Because the id comes from the link, any well-formed id resolves: an attachment no string links to yet has stringCount 0 and no strings. The list shows only attachments that strings link to. Creating, linking, and deleting take strings:write and the admin, localization manager, or developer role, the same as setting designUrl with a bulk update. A Figma attachment has no image. To show the frame itself, upload a screenshot or sync it with the Figma plugin.

Batch review

Approve waiting translations and drafts that have text:
Requires translations:approve. Blank translations, rejected translations, text over the string’s maximum length, and segments locked in the Content Editor are skipped. Send back to review keeps the current translation text but sets status to needs review:
Requires strings:write. Locked segments are skipped. Both routes return { "updated": <count> }. Omit locales to affect every project target language.

Create a key job

POST /v1/jobs with type: "keys" creates a task for people on the strings you pick, with exactly one of stringIds, keys, or tags. Only visible strings in the project’s files are included, at most 5,000. The job starts as waiting_for_review, ready to work in the editor.
The body and errors match POST /api/v1/jobs on the Files and jobs API, and Idempotency-Key values are shared between the two. string and file jobs are recorded as queued, but the public API does not start AI translation for them. Use the Files and jobs API when you want them translated.

Key jobs after creation

Create a key job with POST https://hyperlocalise.com/api/v1/jobs and type: "keys", then use the public API to inspect and adjust it while the job is open.

List and change membership

Add visible strings (hidden strings and strings in no file are skipped):
Remove strings with DELETE on the same path and a selection body. A job must keep at least one string.

Locales and progress

Each locale row includes total, translated, approved, and needs-review counts over the job’s visible strings. Progress is computed when you ask; sending a translation back to review lowers counts immediately. Add or remove target languages with POST /v1/jobs/{jobId}/locales and DELETE /v1/jobs/{jobId}/locales/{locale} while the job is open. Patch title, description, due date, or owner with PATCH /v1/jobs/{jobId}.

Update many jobs at once

POST /v1/jobs/bulk-update applies one change to up to 100 jobs, such as moving every job of a request to a new due date:
It takes the same fields as PATCH /v1/jobs/{jobId} (title, description, dueAt, ownerEmail; null clears all but title) and returns { "jobs": [...] } in request order. The update is all or nothing: if one job is missing, provider-backed, or cannot take the owner, no job changes and the error’s details.jobId names that job. Each job still sends its own job-changed webhook.

Complete or cancel a job

These work like Mark done and Cancel in the app. Both return { "job": ... } with the new status, and each sends a job-changed webhook.
  • POST /v1/jobs/{jobId}/complete moves an open proofread or post-edit task for people (waiting_for_review) to succeeded. Unfinished strings stay as they are. Reviewers, localization managers, and admins can complete any task. Anyone else can complete only tasks they own, and gets 403 not_task_assignee for the rest. Tasks for an agent finish on their own.
  • POST /v1/jobs/{jobId}/cancel moves a queued, running, or waiting_for_review job to cancelled and stops it. A cancelled job can’t be reopened.
A job that can’t take the action, including a provider-backed job, returns 409 job_action_unavailable.

Download source and translated files

A job’s sourceFile.fileId is its original upload, and a finished file job lists each translated file under outputFiles with its fileId and locale. Download any of them with GET /v1/files/{fileId}/download (needs files:read):
The file comes back as an attachment with its stored name. To wait for a file job, poll GET /v1/jobs/{jobId} until status is succeeded, then download its outputFiles. To get a source file in one language with its current translations, whether or not a job ran, use GET /v1/projects/{projectId}/translations/download?sourcePath=...&locale=... (needs files:read). The file keeps its own format. In structured files, strings without a translation keep their source text:
Tags, design links, screenshots, and key jobs mirror the Content Editor and Jobs UI. For source-text edits through the API, see Update source content safely.

Next