# REST API

> Authentication with scoped tokens, the endpoints for keys and translations, and the public endpoints for signup and trials.

Everything the CLI does goes through a REST API at `https://app.rodarion.com/api`. This page lists the
endpoints you are most likely to need. Prefer the CLI where it covers your use case: it
handles layouts, branches and trial limits for you.

## Authentication

Send an API token as a bearer header:

```bash
curl -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
  https://app.rodarion.com/api/project
```

Tokens are created in the app. Each token is bound to **one project** and a set of
**abilities**, for example `key.read`, `key.create`, `translation.read`,
`translation.edit` or `project.configure`. A token without the right ability gets a 403.

## Main endpoints

| Method and path | Purpose |
| --- | --- |
| `GET /api/project` | The token's project, locales and, for a trial, its limits and usage |
| `POST /api/keys` | Import keys and source texts from a language file |
| `GET /api/translations` | Export translations in the export profile's format (file or ZIP), filterable by namespace, language, key and status |
| `PATCH /api/translations` | Fill missing translations of one language from a file |
| `PATCH /api/translation` and `/api/translation/batch` | Edit one or many translations |
| `POST /api/translations/auto-translate` | Machine-translate every missing slot of the project |
| `GET /api/translations/runs/{run}` | Progress of a machine translation run |
| `GET /api/profiles`, `POST /api/profiles` | List or create export profiles |
| `GET /api/providers`, `GET/POST /api/provider-settings` | Machine translation providers and settings |
| `POST /api/branch/promote`, `DELETE /api/branch` | Promote or discard a branch shadow project |

## Public endpoints

These need no token.

| Method and path | Purpose |
| --- | --- |
| `POST /api/register` | Start a signup: `email`, `first_name`, `last_name`, `company_name`. Sends a verification e-mail; answers 202. |
| `POST /api/trial` | Create a trial project and token in one call. Built for agents, see [https://app.rodarion.com/llms/trial.md](https://app.rodarion.com/llms/trial.md). |
| `POST /api/trial/claim` | With the trial token: turn the trial into a free account (same fields as register). |
| `GET /api/public/locales` | The catalogue of valid locale codes |

Limits for trials and the free plan are listed on [Pricing](/pricing).