# Localize.io

> Agentic localization pipelines at scale.

A translation and proofreading API. You send an order — our schema, a file in your own format, or plain text — and collect the finished work. What shapes a translation is material you supply: a glossary, a translation memory, a style guide, screenshots. What kind of file it is is read from its contents, not from where you put it or what you call it; which languages it is for is read from its contents, its name and its folders, and kept exactly as written.

## Authentication

Every call takes `authorization: Bearer <token>`. Keys are minted in your cabinet, one per integration, so one can be turned off without the rest going dark. A key is shown once and stored only as a digest.

## A job, end to end

```
curl -X POST https://t.localize.io/v1/jobs \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"requester":"ci","content_type":"ui","source_lang":"en","target_langs":["de","fr"],"segments":[{"id":"greeting","text":"Hello"}]}'

curl https://t.localize.io/v1/jobs/$JOB_ID        -H "authorization: Bearer $TOKEN"  # status
curl https://t.localize.io/v1/jobs/$JOB_ID/result -H "authorization: Bearer $TOKEN"  # the work
curl https://t.localize.io/v1/jobs/$JOB_ID/trace  -H "authorization: Bearer $TOKEN"  # how it was made
```

`requester` (who asked) and `content_type` (one your configuration declares) are required; read what you may order from `/v1/config`.

A job is queued, worked, and finished. Poll the status or the listing; there is no callback yet. A job submitted as a file comes back as that same file from `/v1/jobs/{job_id}/file`.

## MCP

The same work as MCP tools, at `https://t.localize.io/mcp` (streamable HTTP), with the same bearer token: get_config, list_projects, translate, job_status, wait_for_job, get_result, explain_job, list_jobs, list_assets, upload_asset, attach_screenshot. `translate` returns a job id at once; wait_for_job holds up to 50 seconds per call.

## Endpoints

### assets

- `GET /v1/assets` — Material that belongs to you rather than to one project.
- `GET /v1/assets/versions` — Every version of your assets, kept for good.
- `GET /v1/assets/versions/{ref}` — One kept version, byte for byte: by its SHA-256, or the twelve characters of
- `POST /v1/assets/versions/{ref}/restore` — Put a kept version back as the file now: `{"path": "glossary.csv"}`, with
- `GET /v1/assets/{rel}` — Take one of your own files back, byte for byte as you sent it.
- `PUT /v1/assets/{rel}` — Put a file where it applies to every project.
- `DELETE /v1/assets/{rel}` — Remove one of your files. Jobs after this stop seeing it.
- `GET /v1/projects` — The projects this client has, and what each one is routed to.
- `POST /v1/projects` — A project is a name your orders can carry so they get their own glossary, memory and voice. Material uploaded to a project applies only there; material uploaded to you applies everywhere.
- `GET /v1/projects/{project}/assets` — Everything you have given this project, and what the service made of it.
- `GET /v1/projects/{project}/assets/{rel}` — Take a project's file back, byte for byte as you sent it.
- `PUT /v1/projects/{project}/assets/{rel}` — Put a file into the project. Anything at all: it is read for what it is.
- `DELETE /v1/projects/{project}/assets/{rel}` — Remove a file from a project. Jobs after this stop seeing it.
- `POST /v1/uploads` — Attach a screenshot to the job you are about to order.
- `GET /v1/uploads` — Every screenshot you have attached and not deleted.
- `GET /v1/uploads/{handle}` — One of your own attachments, as you sent it.
- `DELETE /v1/uploads/{handle}` — Delete one of your attachments. Delivered jobs that used it keep their record,

### configuration

- `GET /v1/config` — Your `config.json`, as it is.
- `PUT /v1/config` — Replace your `config.json` with the body, as it is.
- `GET /v1/config/history` — The versions of your `config.json` that were replaced, newest first.
- `GET /v1/config/history/{version}` — One kept version of your `config.json`, as it was.
- `POST /v1/config/restore` — Put a kept version back: `{"version": "<from the history>"}`. The one it
- `GET /v1/models` — The models an order may name in `models`, for each thing it may name one for.
- `PUT /v1/projects/{project}/config` — Replace one project's `config.json` — see `PUT /v1/config`.
- `GET /v1/projects/{project}/config` — One project's `config.json`, as it is — see `/v1/config`.
- `GET /v1/projects/{project}/config/history` — The versions of this project's `config.json` that were replaced, newest first.
- `GET /v1/projects/{project}/config/history/{version}` — One kept version of this project's `config.json`, as it was.
- `POST /v1/projects/{project}/config/restore` — Put a kept version of this project's `config.json` back — see `/v1/config/restore`.

### costs

- `GET /v1/budget` — Your monthly budget, if you set one, and this month against it: the price of
- `PUT /v1/budget` — `{"monthly_usd": 500}` caps what a month may be charged; `null` removes the
- `GET /v1/costs` — One month of your work, by the job: every delivered job's characters, its model usage by kind (translation, choosing terms and screens, the terminology check, memory search, reading your material) and its price; totals by project and by API key; and what was spent outside any job (screenshots described as they were uploaded). A job counts in the month it was delivered, in UTC. `month` is `YYYY-MM`, this month when left out; `months` lists every month with anything in it.
- `GET /v1/costs.csv` — The job lines of `GET /v1/costs`, one row a job, for a spreadsheet.
- `GET /v1/credit` — For a prepaid account: credit added, what delivered jobs have drawn from it,

### files

- `GET /v1/jobs/{job_id}/file` — Collect the result as the file you sent, with the translations in it.

### jobs

- `POST /v1/jobs` — Send work to be translated or proofread. The body can be an order in this API's own schema, a file exported from your own tooling, or `text/plain` — one endpoint, because a job is one thing whatever shape it arrives in.
- `GET /v1/jobs` — Your jobs, newest first, each described rather than merely named: status, project, the models that worked it, how many segments, what it cost and how many warnings it carries — enough to decide whether you care about that job without a request per job. Narrow it with `status`, `project` and `limit`.
- `GET /v1/jobs/{job_id}` — Where one job is, which pass it is on, and which models have worked it.
- `GET /v1/jobs/{job_id}/result` — The finished work: every segment with its translation, together with the order it came from. `409` while the job is still running, `422` if it failed — with the reason.
- `GET /v1/jobs/{job_id}/trace` — Everything that happened to one job, in order: how it was routed and why, which model answered, the exact context that was sent to it, the glossary terms and memory matches that went in, every check that ran and what it found, and what each call cost.
- `GET /v1/log` — The same records a trace shows for one job, across all of them, plus what belongs to no job: material stored or removed, keys minted or revoked.

### ops

- `GET /health` — Answers `{"status": "ok"}` while the service is running.

## Reference

- [API reference](https://t.localize.io/docs): the whole surface, rendered.
- [openapi.json](https://t.localize.io/openapi.json): the same thing as a machine-readable description, generated from the running service.
- [SKILL.md](https://t.localize.io/skill.md): how to do the work with it, step by step, as a skill an agent can load.