> ## 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.

# Conventions

> Base URL, JSON envelope, errors, conflicts and pagination.

## Base URL and versions

All endpoints live on their own domain, with the version in the path:

```text theme={null}
https://api.tolk.every-day.io/v1
```

A change that breaks existing code only comes in a new version (`/v2`). Within `/v1`, only fields and endpoints are added. So ignore fields you do not know.

## JSON

* Every response is JSON, including an error and an unknown URL. The only exception is the file from `GET /exports/{profileKey}`.
* A single object is wrapped in `{"data": {…}}`. A list is `{"data": […], "meta": {"nextCursor": "…", "limit": 500}}`.
* Fields are camelCase. Dates are ISO 8601 in UTC: `2026-10-07T12:00:00Z`.
* Messages follow the `Accept-Language` header (`nl` or `en`, default `nl`).

## Errors

An error is `{"message": "…"}`. A validation error (`422`) also has `errors` per field. For a list, the index of the item is in the field name:

```json theme={null}
{
  "message": "…",
  "errors": {
    "keys.12.value": ["…"]
  }
}
```

## Conflicts (409)

A `409` means the project is busy for a moment. You can repeat the request:

| `reason` | Meaning |
| - | - |
| `source_language_change` | The source language of the project is being changed |
| `busy` | Another writer holds the project for a moment |

Wait a few seconds and try again, with an increasing delay.

## Pagination

`GET /keys` and `GET /translations/{locale}` use a cursor and are sorted by key:

1. Request the first page, optionally with `limit` (1 to 1000, default 500).
2. As long as `meta.nextCursor` is not `null`, request the next page with `cursor=<meta.nextCursor>` and the same filters.

Never build a cursor yourself. A cursor Tolk cannot read returns a `422` on the `cursor` field.

```bash theme={null}
curl "https://api.tolk.every-day.io/v1/translations/de?limit=1000" \
  -H "Authorization: Bearer $TOLK_TOKEN"
```

## Limits

| What | Maximum |
| - | - |
| Requests per token | 120 per minute |
| Requests per IP address (also with an invalid token) | 600 per minute |
| Lines per import (keys × languages) | 50,000; above that, the job fails with `too_many_lines` |
| Keys per customer | according to the [plan](/guide/plan-and-usage); above that, `422` with `reason: key_limit_reached` |
| Hashes in `POST /keys/diff` | 10,000 |
| Keys in `POST /keys/sync` | 5,000, plus 5,000 in `archive` |
| Translations in `PUT /translations/{locale}` | 1,000 |
| Upload in `POST /imports` | 50 MB |
| Tags per key | 10 |


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