Imports and exports through the API

Jobs

Long-running work runs as a job. A 202 Accepted response contains the job and a Location header with its URL:

{
  "data": {
    "id": 42,
    "type": "import",
    "status": "queued",
    "progress": null,
    "result": null,
    "error": null,
    "createdAt": "2026-10-07T12:00:00Z",
    "startedAt": null,
    "finishedAt": null
  }
}

Request GET /jobs/{jobId} until status is succeeded or failed. A failed job has an error with a fixed code and a message, for example:

`code`	Meaning
`too_many_lines`	The import is larger than 50,000 lines (keys × languages). Split the files, per language or per namespace
`key_limit_reached`	The new keys do not fit within the key limit of the customer’s plan
`needs_mapping`	A spreadsheet without a saved column mapping (preset)
`keys_only_mixed`	A spreadsheet whose preset has no language column (keys only) together with translation files. Import it separately
`zip_slip`	A zip with an unsafe path

Poll calmly, for example every 2 to 5 seconds: every poll counts towards the rate limit.

Importing

POST /imports takes multipart/form-data with files[]: JSON, PHP, PO, MO, CSV, XLSX, XLIFF or a zip of these (at most 50 MB). Tolk detects the format, language and namespace from each path, just like the import dialog, and imports without a preview.

Field	Description
`files[]`	One or more files (required)
`locale`	The language, if it does not follow from the path
`format`	The format, if it does not follow from the extension
`namespace`	The namespace, if it does not follow from the path
`overwrite`	`1` to overwrite existing translations, default `0`
`createUnknownKeys`	`1` (default) to create unknown keys
`tag`	A tag for new keys

curl https://api.tolk.every-day.io/v1/imports \
  -H "Authorization: Bearer $TOLK_TOKEN" \
  -F "files[]=@lang/de.json" \
  -F "overwrite=1"

An unsafe or unreadable file returns a 422 on files.N, and nothing is saved. The number of lines is only known once the files have been read: an import that is too large therefore first returns 202 and then a failed job with too_many_lines, without anything being written. A CSV or XLSX file needs a column mapping saved as a preset in Tolk; without one, the job fails with needs_mapping. A preset without a language column creates keys only, when createUnknownKeys is on. When it is done, Tolk sends the import.finished webhook.

Exporting

GET /exports/{profileKey} returns the file of an export profile. GET /project lists the project’s profiles under exportProfiles.

Parameter	Description
`locales`	A comma-separated list of languages, for example `de,fr`. Defaults to all languages of the profile
`missing`	What Tolk does with a missing translation: `fallback`, `empty` or `omit`

Store the ETag of the response and send it next time as If-None-Match. If the export has not changed, you get a 304 without a body. The ETag is the hash of the bytes: a change that does not alter the file keeps the same ETag.

curl "https://api.tolk.every-day.io/v1/exports/laravel-json?locales=de,fr" \
  -H "Authorization: Bearer $TOLK_TOKEN" \
  -H 'If-None-Match: "<etag of the previous download>"' \
  -o lang.zip

A large export that has not been built yet returns a 202 with a job. Fetch the export again once the job has succeeded.

After a change, Tolk rebuilds exports in the background and stores them. Fetching an export that has not changed therefore costs almost nothing.

​Jobs

​Importing

​Exporting

Jobs

Importing

Exporting