> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Strings, screenshots, and key jobs API

> Tag strings, upload screenshots, run batch review, and manage key jobs on native projects with a personal access token.

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](https://hyperlocalise.dev/platform/translation/jobs.md). Everything on this page, including creating, completing and cancelling jobs, uses the public API host.

## Base URL and authentication

```
https://public-api.hyperlocalise.com/v1
```

Send the same [personal access token](https://hyperlocalise.dev/platform/settings.md#personal-access-tokens) as Projects and Queries:

```
x-api-key: <secret>
```

External TMS projects return `409` with `project_not_native` for string and translation writes.

## Permissions

| Task | Effective permission |
| - | - |
| List or read strings, translations, and screenshots | `strings:read` (included with `files:read`) |
| Create or edit strings, upload screenshots, mark keys, send translations to review | `strings:write` (included with `files:write` for roles other than member) |
| Add or remove tags and design links | `strings:write`, and the token owner must be an admin, localization manager, or developer |
| Approve translations in bulk | `translations:approve` (included with `files:write` for admins, localization managers, and reviewers) |
| Manage key job strings and locales, read job lists, update jobs one at a time or in bulk, complete or cancel jobs | `jobs:read` / `jobs:write` |

A token never grants more than its owner's role allows. See [Roles and permissions](https://hyperlocalise.dev/platform/workspace/roles.md).

The [interactive reference](https://public-api.hyperlocalise.com/docs) and [OpenAPI document](https://public-api.hyperlocalise.com/openapi.yaml) list every field and error code.

## Pick strings in bulk

Bulk routes take **one** selector:

| Field | Meaning |
| - | - |
| `stringIds` | Up to 1,000 string UUIDs |
| `keys` | Up to 1,000 key names (any file) |
| `tags` | Up to 10 tags; a string must carry **every** tag listed |

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 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:

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/strings/bulk-update" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "keys": ["checkout.title", "checkout.pay"],
    "addTags": ["release-7"],
    "designUrl": "https://www.figma.com/file/example/frame"
  }'
```

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.

```bash theme={null}
curl --fail-with-body -X PATCH "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/strings/$STRING_ID" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"customMetadata": {"ticket": "WX-1042", "legacyId": null}}'
```

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:

| Field | Meaning |
| - | - |
| `keys` | Up to 1,000 exact key names |
| `keyPrefix` | Keys that start with this text, matched literally and case-sensitively |
| `search` | Case-insensitive match on key or source text |
| `filePath` | Strings from one source file |
| `tags` | Up to 10 tags; a string must carry every tag |
| `includeHidden` | Include hidden strings (default `false`) |
| `limit`, `offset` | Page size 1–1,000 (default 100) and start |

```bash theme={null}
curl --fail-with-body \
  -X POST "https://api.hyperlocalise.com/v1/projects/$PROJECT_ID/strings/search" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "keys": ["checkout.title", "checkout.pay", "checkout.old"], "limit": 1000 }'
```

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.

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/screenshots" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "filename": "checkout.png",
    "contentType": "image/png",
    "byteSize": 128,
    "name": "Checkout",
    "markers": [
      {
        "key": "checkout.pay",
        "marker": { "left": 10, "top": 20, "width": 30, "height": 15 }
      }
    ]
  }'
```

PUT the file to `upload.url` with `upload.headers`, then:

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/screenshots/$SCREENSHOT_ID/finalize" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

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](https://hyperlocalise.dev/platform/connections/figma.md) 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.

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/figma-attachments" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "url": "https://www.figma.com/design/AbC123/Futures?node-id=12-345" }'

curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/figma-attachments/AbC123.12-345/strings" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "keys": ["futures.title", "futures.cta"] }'
```

`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](https://hyperlocalise.dev/platform/connections/figma.md).

## Batch review

**Approve** waiting translations and drafts that have text:

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/translations/approve" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "tags": ["release-7"],
    "locales": ["fr-FR", "de-DE"]
  }'
```

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:

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/translations/send-to-review" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "keys": ["checkout.title"] }'
```

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.

```bash theme={null}
curl --fail-with-body -X POST "https://public-api.hyperlocalise.com/v1/jobs" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: request-1042-fr" \
  -d '{
    "type": "keys",
    "projectId": "'$PROJECT_ID'",
    "title": "REQ-1042 Futures page",
    "dueAt": "2026-12-01T09:00:00Z",
    "keysInput": { "sourceLocale": "en", "targetLocales": ["fr"], "tags": ["req-1042"] }
  }'
```

The body and errors match `POST /api/v1/jobs` on the [Files and jobs API](https://hyperlocalise.dev/platform/api.md#create-a-job), 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

```bash theme={null}
# Strings in the job (hidden strings included)
curl --fail-with-body \
  "https://public-api.hyperlocalise.com/v1/jobs/$JOB_ID/strings?limit=50" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY"
```

Add visible strings (hidden strings and strings in no file are skipped):

```bash theme={null}
curl --fail-with-body \
  -X POST "https://public-api.hyperlocalise.com/v1/jobs/$JOB_ID/strings" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "tags": ["release-7"] }'
```

Remove strings with `DELETE` on the same path and a selection body. A job must keep at least one string.

### Locales and progress

```bash theme={null}
curl --fail-with-body \
  "https://public-api.hyperlocalise.com/v1/jobs/$JOB_ID/locales" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY"
```

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:

```bash theme={null}
curl --fail-with-body \
  -X POST "https://api.hyperlocalise.com/v1/jobs/bulk-update" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "jobIds": ["'$JOB_ID_1'", "'$JOB_ID_2'"],
    "dueAt": "2026-12-01T09:00:00Z"
  }'
```

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.

```bash theme={null}
curl --fail-with-body -X POST "https://public-api.hyperlocalise.com/v1/jobs/$JOB_ID/complete" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY"
```

* `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`):

```bash theme={null}
curl --fail-with-body -OJ "https://public-api.hyperlocalise.com/v1/files/$FILE_ID/download" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY"
```

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:

```bash theme={null}
curl --fail-with-body -OJ -G "https://public-api.hyperlocalise.com/v1/projects/$PROJECT_ID/translations/download" \
  --data-urlencode "sourcePath=locales/en.json" --data-urlencode "locale=fr" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY"
```

## Related editor behavior

Tags, design links, screenshots, and key jobs mirror the [Content Editor](https://hyperlocalise.dev/platform/cat.md) and [Jobs](https://hyperlocalise.dev/platform/translation/jobs.md) UI. For source-text edits through the API, see [Update source content safely](https://hyperlocalise.dev/platform/guides/update-source-content.md).

## Next

* [Choose an API](https://hyperlocalise.dev/platform/developers/api-overview.md)
* [Files and jobs](https://hyperlocalise.dev/platform/api.md)
* [Projects and Queries](https://hyperlocalise.dev/platform/developers/projects-and-queries.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.