Endpoint reference¶

Everything relative to the base URL (see 02-authentication.md). All requests carry the bearer token and Content-Type: application/json.

The bodies below are taken from the published OpenAPI spec (v2.0.0). The spec documents success responses only — it defines no error schemas, so see 09-error-handling.md for how errors are handled in practice.

There's a parallel file workflow (/project/{id}/file_item, for uploading XLIFF/XML/PDF/HTML and downloading the translated file) that this kit doesn't cover — it sticks to the JSON item flow. The endpoints are listed at the bottom for reference.

Create a project¶

POST /project → 201

type is order (commission the translation) or quote (get a price estimate first). url is an optional webhook. textmodules is optional and, if you send it, its name must be one of [system], [systemversion], [plugin], [pluginversion].

{
  "type": "order",
  "name": "Translate Products 2021-08-14",
  "description": "Spring catalogue",
  "url": "https://my.app/api/webhook"
}

curl -s -X POST https://stage.api.eurotext.de/api/v2/project \
  -H "Authorization: Bearer $EUROTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"order","name":"Translate Products 2021-08-14"}'

Response (201) echoes the project back with its id and a status (a fresh project starts at default; url is "" when you didn't pass one):

{
  "id": 42,
  "type": "order",
  "name": "Translate Products 2021-08-14",
  "status": "default",
  "url": "",
  "description": "Spring catalogue",
  "textmodules": []
}

Add an item¶

POST /project/{id}/item → 201

body is a free-form object of your field names to source text. __meta is an optional reserved key for data that must not be translated — this is where you put your own identifiers (see 07-metadata-roundtrip.md).

{
  "sourceLanguage": "de-de",
  "targetLanguage": "en-us",
  "textType": "product",
  "body": {
    "name": "Roter Bürostuhl",
    "description": "Ergonomischer Stuhl mit verstellbarer Lehne.",
    "__meta": { "id_in_your_system": 132, "locale": "en_US" }
  }
}

Response (201) — status starts at default, and translation comes back as an empty array ([]) until the item is actually translated (don't expect it to mirror body up front):

{
  "id": 132,
  "status": "default",
  "sourceLanguage": "de-de",
  "targetLanguage": "en-us",
  "textType": "product",
  "body": {
    "name": "Roter Bürostuhl",
    "description": "Ergonomischer Stuhl mit verstellbarer Lehne.",
    "__meta": { "id_in_your_system": 132, "locale": "en_US" }
  },
  "translation": []
}

Watch the language codes — Eurotext's own, not de-DE (05-language-codes.md) — and textType is a fixed set (06-text-types.md).

An item can only be edited (PATCH) while its status is default, and a PATCH replaces body, it doesn't merge. Get it right before you start the project.

Start translation¶

PATCH /transition/project/{id} → 204

status is new (start) or trash (cancel). Transitioning to new locks the project: from here on no items can be added and existing items can't be edited. Add every item first.

{ "status": "new" }

curl -s -X PATCH https://stage.api.eurotext.de/api/v2/transition/project/42 \
  -H "Authorization: Bearer $EUROTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"new"}'

Returns 204, no body.

Read a project (poll)¶

GET /project/{id} → 200

You get the same top-level fields as on create (type, name, status, url, description, textmodules) plus elementStatuses and elements. Items are grouped by status under elements; each group has an items array and may have a files array — don't assume files is always present.

Real shape, captured on stage right after submitting one item (the project's top-level status flips to locked once transitioned, and the item sits in the new group until work starts):

{
  "id": 42,
  "type": "order",
  "name": "Translate Products 2021-08-14",
  "status": "locked",
  "url": "",
  "elementStatuses": ["new"],
  "elements": {
    "new": { "items": [11694] }
  }
}

As work progresses, items move between groups (in-progress, finished, error, …). Done means every item sits in finished; a failure shows up in error. How to collapse this into one status: 08-status-model.md.

Read an item (fetch result)¶

GET /project/{id}/item/{itemId} → 200

Source stays under body. Until the item is translated, translation is [] (see the create response above). Once it's finished, translation holds the translated fields plus the __meta you sent, so you know where each value belongs.

A delivered item — translation holds the translated fields under the same keys as body, and carries back the __meta you sent:

{
  "id": 132,
  "status": "finished",
  "sourceLanguage": "de-de",
  "targetLanguage": "en-us",
  "textType": "product",
  "body": {
    "name": "Roter Bürostuhl",
    "__meta": { "id_in_your_system": 132, "locale": "en_US" }
  },
  "translation": {
    "name": "Red office chair",
    "__meta": { "id_in_your_system": 132, "locale": "en_US" }
  }
}

Delete a project¶

DELETE /project/{id} → 204

Cleanup when a push fails partway. Only possible before the project's items reach in-progress — a draft or a freshly-transitioned project can be deleted, but once work has started the API rejects the delete. There's also DELETE /project/{id}/item/{itemId} for a single item (same draft-only rule).

curl -s -X DELETE https://stage.api.eurotext.de/api/v2/project/42 \
  -H "Authorization: Bearer $EUROTEXT_API_KEY"

Info endpoints¶

GET /info/languages → the authoritative language list. GET /info/text-types → the authoritative textType list. Use it instead of hardcoding — the set includes ai-01/ai-02/ai-03 and can grow.

Both return a flat JSON array of code strings (not objects), captured on stage:

curl -s https://stage.api.eurotext.de/api/v2/info/text-types \
  -H "Authorization: Bearer $EUROTEXT_API_KEY"

["specialized-text","product","term","marketing","template","software","ai-01","ai-02","ai-03"]

// GET /info/languages — 93 codes
["alb","ar","azf","aze","bg","zh-cn","nl-be","zh-tw","da","de-de","de-ch","en-gb","en-us", "..."]

Also in the API (not covered here)¶

GET /project and GET /project/{id}/item — paginated lists (page query param; totals come back in Total-Objects / Total-Pages / Objects-Per-Page / Current-Page response headers).
PATCH /project/{id} — update a project (note: textmodules is replaced, not merged).
The file_item / file endpoints for document-based translation (XLIFF, XML, PDF, HTML) plus accessory reference images.