API reference

The Taia API lets your own software do what you would do in the app: upload files, start a translation, check progress and download the result. It is a JSON API over HTTPS.

This page lists what the API does today. To create a key, see Create an API key. For a worked example, see Submit a translation via API.

Base URL

https://api.taia.io/api/public/v1

All paths below are relative to it. translate.taia.io is the web app, not the API, so requests sent there won't reach it.

Authentication

Send your API key in the Authorization header, using the Api-Key scheme (not Bearer):

Authorization: Api-Key taia_pk_live_YOUR_KEY

Keys are created in the app, under Profile → Manage Your API Keys, or by an organization manager on the API keys tab of Manage Organization. If you aren't part of an organization or team, you can create a personal key from your profile. API access needs the Pro plan. See Create an API key.

A request with a missing header, the wrong scheme, a key that doesn't start with taia_pk_live_, or a revoked or unknown key gets a 401 with a JSON body such as {"error": "Invalid API key"}.

Only GET /languages and GET /supported-files work without a key. Everything else on this page needs one.

Read and Write scopes

A key records whether it is Read, Write or both, but the API doesn't check the scope on a request yet. Treat every key as able to read and write.

Which projects a key can reach

A team key belongs to a team. Projects created with it are attached to that team, and the team's billing account pays for them. A personal key belongs to you, and its projects are billed to your own plan.

Most endpoints let a key act on any project attached to its team, whoever created it. A few are stricter and only answer for projects created by the person who created the key: GET /projects/{id}, GET /projects/{id}/status and POST /projects/{id}/instant-mt. What you get back for a project outside that reach depends on the endpoint. GET /projects/{id} and /status return 403, while instant-mt returns 404, the same as for a project that doesn't exist.

Responses and errors

Errors come back as JSON with an error field, and often a message that says what to fix. The status code tells you the kind of problem: 400 for a bad request, 401 for authentication, 403 for a project or resource the key can't reach, 404 for something that doesn't exist.

Successful responses vary by endpoint, so check the table for the one you call:

• The project list, GET /projects/{id}, GET /projects/{id}/status, and the glossary and translation memory lists are wrapped in data.
• GET /orders returns orders and pagination.
• GET /projects/{id}/quote returns message and quote. PATCH /projects/{id}/quote and PATCH /projects/{id}/quote/delivery-date return the quote object itself, unwrapped.
• GET /projects/{id}/delivery-dates returns project_id and delivery_options.
• GET /orders/{order_id} returns the order object unwrapped.
• GET /languages returns a plain list. GET /translation-models returns default, rates and models.

Running out of credits is reported differently by the two translation endpoints. POST /instant-translate returns 402. POST /projects/{id}/instant-mt returns 400 with "error": "Not enough credits for translation" (in the error field, not message).

Reference data

Method	Path	What it returns
GET	/languages	Every language, as a plain list, with its value (the code to use, such as en-US or de-DE), label and base_code. No key needed.
GET	/supported-files	The supported file types, grouped by category. No key needed.
GET	/translation-models	The translation engines you can pass as translation_engine, with credits per word.
GET	/glossaries	The glossaries the key can use: id, name, languages.
GET	/translation-memories	The translation memories the key can use: id, name, description.

Language codes are the full codes from /languages, for example en-US, not en.

The engines are basic (shown in the app as Standard, the default, 1 credit per word), claude-sonnet (Advanced, 2 credits per word) and claude-opus (Premium, 4 credits per word). /translation-models lists them with their rates. An older name that Taia has retired, such as claude-haiku, is treated as its replacement (claude-sonnet). Any other value is rejected with a 400 that lists the allowed ones.

Projects

Method	Path	What it does
POST	/projects	Create a project and upload its files. Returns 202 with project_id and a status_url.
GET	/projects	List the key's projects, newest first: id, name, status, created_at. Under data.
GET	/projects/{id}	One project: its jobs (one per target language), total_words, engine, style guide and credit quota. Under data.
GET	/projects/{id}/status	The project's status. Under data.
POST	/projects/{id}/instant-mt	Start AI translation. The project must be converted. Returns 202.
GET	/projects/{id}/final-files	Download links for the AI-translated files. Check the status first (see below).
POST	/projects/{id}/convert	Deprecated. Conversion starts by itself when you create a project.

Create a project

POST /projects takes multipart/form-data:

Field	Required	Notes
project_name	Yes
source_language	Yes	A code from /languages.
target_languages	Yes	Comma-separated codes, for example de-DE,fr-FR. Can't include the source language.
files[]	Yes	One field per file. Up to 100 files and just under 100 MB in total, in a supported format.
translation_engine	No	Defaults to basic.
glossaries[]	No	Glossary IDs from /glossaries.
translation_memories[]	No	Translation memory IDs from /translation-memories.
style_guide_id	No	A published style guide the key's team can use.
comment	No	Instructions for linguists and project managers. Stored as a message on the project. Also accepted as instructions.

Conversion starts on its own once the files are uploaded. Poll the status until it reads converted.

Statuses

pending, created, converting, converted, translating, in_progress, completed, translations-updated, human-edited and failed. An AI-translated project ends at completed.

Start AI translation

POST /projects/{id}/instant-mt takes an optional JSON body:

• translation_engine to change the engine for this run. It is saved on the project.
• protect_bracket_placeholders, true or false, to override your organization's setting for this project. See Protect placeholders.

If the project isn't converted yet, you get a 400 with current_status.

Download AI translations

GET /projects/{id}/final-files returns 200 with final_files, a list of id, name and file_path. The file_path is a temporary download link, so fetch it soon after you ask for it. A 202 means the file is still being rebuilt after edits: ask again in a moment.

Check the project's status first, and only ask for files once it is completed. A 200 without final_files (it carries a message saying no final files are available) means they aren't ready yet, so it isn't a success. The endpoint can also return 409 with error_code REBUILD_FAILED when an updated file couldn't be built (contact support), or 404.

Professional translation

Ordering professional translation is a sequence on a converted project.

Method	Path	What it does
GET	/projects/{id}/quote	Get the quote. The first call starts the word count analysis and returns 202. Call it again until it returns 200 with the quote.
PATCH	/projects/{id}/quote	Choose a service level per language. Body: selections, a list of job_id and service_code (essential, enhanced or ultimate).
GET	/projects/{id}/delivery-dates	The delivery options, under delivery_options, each with a type, delivery_date and price_multiplier.
PATCH	/projects/{id}/quote/delivery-date	Choose one. Body: delivery_type, a type from the previous step or one of the shortcuts described below. Returns the updated quote.
POST	/projects/{id}/order	Place the order. Body: payment_method and an optional notes. Returns 201 with order_id, order_url and status.
GET	/orders	List orders, newest first. Filter with status and project_id, and page with limit (default 50, at most 100) and offset.
GET	/orders/{order_id}	One order: status, dates and status history.
GET	/orders/{project_id}/translated-files	Download links for the delivered files, plus a ZIP when there are several. Note that the path takes the project's ID.

Delivery types

GET /delivery-dates returns the options available for this project, and their type values are technical names: recommended (1.0x), fast_25 (1.25x), fast_50 (1.5x) and, when there is room, late_1 to late_4 (1.0x). Which ones appear depends on the project's size and the calendar.

PATCH /quote/delivery-date accepts those exact type values. It also accepts three shortcuts: standard (same as recommended, 1.0x), fast (same as fast_25, 1.25x) and urgent (same as fast_50, 1.5x). If the type you ask for isn't in the list for this project, you get a 400. The safe route is to pick a type straight from the GET reply.

Two things to know about ordering:

• payment_method must be invoice. The API also accepts balance as a value, but then refuses the order with a 400. To pay from your balance, place the order in the app.
• You must choose a delivery date first. An order without one gets a 400. A quote can only be ordered once.

GET /orders/{project_id}/translated-files returns 202 while the order is still in progress, and 200 once it is delivered or completed.

Instant text translation

POST /instant-translate translates a short piece of text straight away, with no project or file. Send JSON with text, source_language and target_language, and optionally glossary_ids and tm_ids. It returns translated_text, credits_used and word_count. Today translated_text is an object rather than a string: the translation itself is at translated_text.translations[0].translation. Check for that path rather than assuming a string, because we plan to simplify it.

It only supports the basic engine. Asking for an advanced one returns 501: use a project and instant-mt instead. It uses your credits, and returns 402 when there aren't enough. POST /projects/{id}/instant-mt reports this differently: see Responses and errors.

Webhooks

Instead of polling, you can have Taia call your server when a project changes. Webhooks are managed under /webhooks, and the events they send are described in Webhook events.

Interactive reference

Taia publishes a Postman collection of these endpoints. It is linked as View API Docs on the API product page.

Related

• Create an API key
• Submit a translation via API
• Webhook events
• Subscription plans matrix (API access needs the Pro plan)
• API product page on taia.io