Base URL and authentication
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 -.
Tags and design links
Strings includetags 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:
{ "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, incustomMetadata. 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.
_, ., 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:
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.- Create a pending screenshot. The response includes a time-limited PUT URL and the headers to send with it.
- PUT the image bytes to that URL.
- Finalize. The screenshot becomes
readyandimageUrlis a time-limited download.
upload.url with upload.headers, then:
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 samedesignUrl 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.
- Get the attachment for a link. The response has its
id, such asAbC123.12-345(the file key, plus the node when the link names one), andstringCount. Nothing is stored; the id is derived from the link. - Link the request’s strings. Pick them with one of
stringIds,keys, ortags(at most 1,000). Linking sets each string’sdesignUrlto the attachment’surland 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: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:
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.
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 withPOST 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
DELETE on the same path and a selection body. A job must keep at least one string.
Locales and progress
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:
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}/completemoves an open proofread or post-edit task for people (waiting_for_review) tosucceeded. Unfinished strings stay as they are. Reviewers, localization managers, and admins can complete any task. Anyone else can complete only tasks they own, and gets403 not_task_assigneefor the rest. Tasks for an agent finish on their own.POST /v1/jobs/{jobId}/cancelmoves aqueued,running, orwaiting_for_reviewjob tocancelledand stops it. A cancelled job can’t be reopened.
409 job_action_unavailable.
Download source and translated files
A job’ssourceFile.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):
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:

