> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolk.every-day.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Imports and exports through the API

> Upload files, fetch export profiles with an ETag and follow jobs.

## Jobs

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

```json theme={null}
{
  "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 |

```bash theme={null}
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](/guide/importing#importing-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](/guide/exporting). `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.

```bash theme={null}
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.

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


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