Automation API · Reference

API reference

Every operation of /api/v1, with its scope, parameters, bodies, answers and error codes, generated from the OpenAPI description that ships with Libris. Load the same file in any OpenAPI tool or client generator.

OpenAPI 3.1.0 · API version 1

Download the OpenAPI file View it on GitHub Back to the API overview

Overview

Send an EPUB, TXT chapters or a JSON document to a Libris server, let it translate on its own, then download the result with its completion report. Nothing needs a person along the way.

Authentication. Every call carries an API token: Authorization: Bearer lbr_…. Tokens are created in the interface (My account › API tokens); each one carries scopes, named on every operation below. The session cookie of the web interface never opens /api/v1.

Asynchronous work. A request is saved before the 202 Accepted answer and runs in the worker. Poll its status (?wait= long-polls up to 60 seconds by default) or receive a signed webhook when it ends. A request always ends: completed, completed_with_residuals, failed or cancelled (imported when it only imported chapters).

Errors. Every error is {"detail": {"code", "message", …}}. code is stable; message is in French, or in English with Accept-Language: en. Validation errors never echo the submitted text.

Limits. Calls per token and per minute (API_RATE_LIMIT_PER_MINUTE, 429 with Retry-After), body size (API_MAX_PAYLOAD_MB) and chapters per request (API_MAX_CHAPTERS) are set by the server's administrator.

The full guide, with curl examples, is docs/api.md.

Translation requests

Send content, follow it, pause, resume or cancel it.

Send a translation request

POST /api/v1/translation-requests

Send an EPUB (multipart field file, or the raw file as application/epub+zip with its options in the query string), TXT or DOCX chapters (multipart, one or more .txt or .docx files in file or files, one chapter each, or one file split at its chapter headings with split=headings) or a JSON document. One request carries one kind of file.

The request is stored before the answer and its pipeline starts in the worker: 202 Accepted with a Location header. The same content sent again with the same Idempotency-Key or external_id answers 200 with the original request and Idempotent-Replayed: true.

Without the pipeline:start scope, send start=false to import only.

Chapters sent to a volume already translated (volume.latest, or the same volume again) are appended and only they are translated. The request waits its turn in the fair queue at the priority it asks for, and is refused when its token's cost budget is reached.

Scope: content:write, and pipeline:start to start the pipeline.

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string	1–200 printable characters. Sending the same content again with the same key answers `200` with the original request; different content answers `409 idempotency_conflict`.

Request body

application/json · TranslationPayload

Example

json

{
  "external_id": "saga-volume-12",
  "series": {
    "name": "The Synthetic Saga",
    "create_if_missing": true
  },
  "volume": {
    "external_id": "volume-12",
    "number": 12,
    "title": "Volume 12"
  },
  "author": "A. Author",
  "source_language": "en",
  "target_language": "fr",
  "chapters": [
    {
      "external_id": "chapter-001",
      "number": 1,
      "title": "Chapter 1",
      "content": "First paragraph.\n\nSecond paragraph.\n"
    }
  ],
  "pipeline": {
    "start": true,
    "quality": "high",
    "context_backend": "hybrid",
    "final_review": true
  },
  "output": {
    "format": "json"
  },
  "callback_url": "https://hooks.example.org/libris"
}

multipart/form-data

An EPUB (one file in file), TXT or DOCX chapters (one or more .txt or .docx files in file or files; series or series_id, volume, source_language and target_language required) or one .json document in file with no other field. Empty fields count as not given; unknown fields are refused.

Name	Type	Description
`file`	file	The EPUB, the JSON document or a TXT or DOCX chapter.
`files`	array of file	TXT or DOCX chapters, one file each, numbered from their names.
`external_id`	string	Your identifier of the request (same rules as in the JSON document). Pattern `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$`.
`series`	string	The series by name, created when missing (not with `series_id`). Required for TXT. At most 500 characters.
`series_id`	string	The series by id (not with `series`). At most 36 characters.
`volume`	integer \| string \| null	Volume number, 1–10000, or `latest` for the series' last volume (TXT only). Required for TXT; for an EPUB in a series, taken from the file name when free, otherwise the next number.
`volume_external_id`	string	Your identifier of the volume. Pattern `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$`.
`title`	string	Volume title (an EPUB keeps its own otherwise). At most 500 characters.
`author`	string	Author of the volume. At most 500 characters.
`source_language`	string	BCP 47 tag such as `en`, `fr-FR`, `zh-Hant`. At most 35 characters.
`target_language`	string	BCP 47 tag. At most 35 characters.
`provider_id`	string	Provider to use; defaults to the volume's, then the series' provider. At most 36 characters.
`quality`	string	One of `"fast"`, `"normal"`, `"high"`, `"maximum"`.
`context_backend`	string	One of `"internal"`, `"openviking"`, `"hybrid"`.
`start`	boolean	Run the whole pipeline (needs the `pipeline:start` scope); false only imports. Default `true`.
`final_review`	boolean	Run the final review (never when the server disables it). Default `true`.
`output_format`	string	Default format of the result; `epub` only for an EPUB (and its default); `epub-bilingual` is a bilingual EPUB for proofreading, for any input. One of `"json"`, `"txt"`, `"txt-zip"`, `"epub"`, `"epub-bilingual"`.
`callback_url`	string	Webhook called when the request ends; its host must be allowed by an administrator. At most 2000 characters.
`callback_events`	string	Comma-separated extra webhooks, for example `chapters.translated`. At most 200 characters.
`replace_changed_chapters`	boolean	Replace chapters already imported with another text (otherwise `409 chapter_conflict`). Unchanged passages keep their translation. Default `false`.
`discard_human`	boolean	With `replace_changed_chapters`: allow dropping passages a person edited or validated (otherwise `409 conflict`). Default `false`.
`priority`	string	Place in the fair queue: `low`, `normal` (default) or `high`, within the token's `max_priority` and its account's ceiling (otherwise `403 priority_not_allowed`). Does not change what the request is. One of `"low"`, `"normal"`, `"high"`.
`analysis_mode`	string	`parallel`: the passages are analysed side by side, then each is reconciled with what precedes it; `strict`: one passage after the other. Default: the volume's choice, else `ANALYSIS_MODE`. One of `"parallel"`, `"strict"`.
`threads`	integer	Passages worked on at once, analysis and translation alike (1–64). It can only lower the volume's share of the provider's capacity; default: that share. Minimum 1. Maximum 64.
`split`	string	TXT or DOCX: `headings` splits one file holding many chapters at its chapter headings (a prologue, an interlude or another special keeps its place in the file and no chapter number; `Chapter 12 (Part 2)` is part 2 of chapter 12) (numbers and titles from the headings, the split recorded in `report.decisions.intake`); `none` (default) keeps each file as one chapter. Refused for an EPUB. One of `"none"`, `"headings"`. Default `"none"`.

application/epub+zip · file

Options of a raw EPUB body

With Content-Type: application/epub+zip, the options go in the query string. They are the same as the fields of the multipart upload:

filenameexternal_idseriesseries_idvolumevolume_external_idtitleauthorsource_languagetarget_languageprovider_idqualitycontext_backendstartfinal_reviewoutput_formatcallback_urlcallback_eventsreplace_changed_chaptersdiscard_humanpriorityanalysis_modethreadssplit

Answers

Status	Description	Content
200	Replayed: this content was already sent with this key or `external_id`. Headers: `LocationIdempotent-Replayed`	`application/json` `RequestSummary`
202	Accepted: the request is stored and will run in the worker. Headers: `Location`	`application/json` `RequestSummary`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
402	The token's cost budget is reached (`budget` gives the cap, the spend, the period and when it resets); a request that only imports (`start` false) is still accepted. Codes: `budget_exceeded`.	`application/json` `Error`
403	The token lacks a scope (`scope` names it), a browser page from another site, or the priority asked for is above the token's or the account's ceiling (`max_priority`). Codes: `insufficient_scope`, `forbidden`, `priority_not_allowed`.	`application/json` `Error`
404	The series named by `id` does not exist, or `create_if_missing` is false. Codes: `series_not_found`.	`application/json` `Error`
409	The content cannot be taken as it is. Codes: `idempotency_conflict`, `chapter_conflict`, `conflict`, `volume_conflict`, `series_archived`, `volume_archived`.	`application/json` `Error`
413	The body is above `API_MAX_PAYLOAD_MB`. Codes: `payload_too_large`.	`application/json` `Error`
415	Neither JSON, EPUB nor multipart. Codes: `unsupported_media_type`.	`application/json` `Error`
422	The document, the upload or an option is invalid. Codes: `invalid_payload`, `invalid_idempotency_key`, `unknown_provider`, `provider_required`, `invalid_epub`, `callback_refused`, `invalid_placement`.	`application/json` `Error`
429	Too many calls for this token (retry after `Retry-After` seconds), or the token or its account already has its quota of requests waiting to start (`scope`, `limit`): nothing is stored, retry once one of them has started. Codes: `rate_limited`, `queue_full`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Example · 200

json

{
  "request_id": "5b1c2d3e-0000-4000-8000-000000000001",
  "external_id": "saga-volume-12",
  "series_id": "5b1c2d3e-0000-4000-8000-000000000002",
  "project_id": "5b1c2d3e-0000-4000-8000-000000000003",
  "job_id": "5b1c2d3e-0000-4000-8000-000000000004",
  "input": "json",
  "status": "pending",
  "status_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001",
  "result_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001/result"
}

Example · 202

json

{
  "request_id": "5b1c2d3e-0000-4000-8000-000000000001",
  "external_id": "saga-volume-12",
  "series_id": "5b1c2d3e-0000-4000-8000-000000000002",
  "project_id": "5b1c2d3e-0000-4000-8000-000000000003",
  "job_id": "5b1c2d3e-0000-4000-8000-000000000004",
  "input": "json",
  "status": "pending",
  "status_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001",
  "result_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001/result"
}

Get the status of a request

GET /api/v1/translation-requests/{request_id}

Status, progress per chapter and stage, stored result and, once the request ended, its completion report. Add ?wait= to long-poll until the request ends.

Scope: jobs:read.

Parameters

Name	In	Type	Description
`request_id` required	path	string	The request's `request_id`.
`wait`	query	integer	Long poll: answer as soon as the request ends, or after this many seconds (bounded by the server's `API_RESULT_MAX_WAIT_SECONDS`, 60 by default). Default `0`. Minimum 0. Maximum 600.

Answers

Status	Description	Content
200	Success.	`application/json` `RequestDetail`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown, or owned by someone else. Codes: `request_not_found`.	`application/json` `Error`
422	A bad parameter. Codes: `invalid_request`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Example · 200

json

{
  "request_id": "5b1c2d3e-0000-4000-8000-000000000001",
  "external_id": "saga-volume-12",
  "series_id": "5b1c2d3e-0000-4000-8000-000000000002",
  "project_id": "5b1c2d3e-0000-4000-8000-000000000003",
  "job_id": "5b1c2d3e-0000-4000-8000-000000000004",
  "input": "json",
  "status": "running",
  "status_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001",
  "result_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001/result",
  "created_at": 1790000000,
  "updated_at": 1790000100,
  "finished_at": null,
  "stage": "translation",
  "step": "translation",
  "progress": {
    "segments": 412,
    "translated": 180,
    "percent": 44,
    "stages": [
      {
        "key": "translation",
        "done": 180,
        "total": 412,
        "percent": 44
      }
    ],
    "analysis": null
  },
  "estimate": null,
  "error": "",
  "stop_reason": "",
  "next_attempt": 0,
  "chapters": {
    "created": 1,
    "unchanged": 0,
    "replaced": 0,
    "items": [
      {
        "chapter_id": "5b1c2d3e-0000-4000-8000-000000000005",
        "external_id": "chapter-001",
        "number": 1,
        "kind": "chapter",
        "part": null,
        "part_count": null,
        "label": "",
        "display_label": "Chapter 1",
        "position": 0,
        "mapping": {
          "confidence": "high",
          "reason": "indiqué dans la requête",
          "detected": false
        },
        "title": "Chapter 1",
        "segments": 140,
        "translated": 60,
        "validated": 0,
        "flagged": 0,
        "complete": false
      }
    ],
    "new": [
      "5b1c2d3e-0000-4000-8000-000000000005"
    ]
  },
  "options": {
    "start": true,
    "final_review": true,
    "output_format": "json",
    "analysis_mode": null,
    "threads": null
  },
  "priority": "normal",
  "queue": null,
  "result": null,
  "report": null,
  "webhook": {
    "state": "pending",
    "attempts": 0,
    "error": ""
  },
  "chapter_events": {
    "event": "chapters.translated",
    "batches": 0,
    "delivered": 0,
    "pending": 0,
    "failed": 0,
    "waiting_chapters": 1,
    "error": ""
  }
}

Pause, resume or cancel a request

POST /api/v1/translation-requests/{request_id}/{action}

Same rules as the interface. A request without a job yet (queued) can only be cancelled. Resuming a job paused by a cost budget is refused until the budget is raised, and resuming counts as a new entry in the queue. Answers with the status document.

Scope: jobs:control.

Parameters

Name	In	Type	Description
`request_id` required	path	string	The request's `request_id`.
`action` required	path	string	`pause`, `resume` or `cancel`. One of `"pause"`, `"resume"`, `"cancel"`.

Answers

Status	Description	Content
200	Success.	`application/json` `RequestDetail`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown, or owned by someone else. Codes: `request_not_found`.	`application/json` `Error`
409	The job's state does not allow the action, or the book's or the token's cost budget that paused it is still reached. Codes: `not_started`, `conflict`, `budget_exceeded`.	`application/json` `Error`
429	Too many calls for this token (retry after `Retry-After` seconds), or resuming would exceed the token's or the account's quota of waiting requests (`scope`, `limit`). Codes: `rate_limited`, `queue_full`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Results

Download the translated book, its chapters or its JSON document.

Download the result

GET /api/v1/translation-requests/{request_id}/result

The chapters of the request in reading order (the whole book for an EPUB), as an EPUB (EPUB requests only), a bilingual EPUB for proofreading (epub-bilingual, any input, layout interleaved or side by side), a JSON document, one UTF-8 text file, or a ZIP of one text file per chapter with a manifest.json. ?format= wins, then the Accept header, then the request's own format. scope chooses the chapters: the request's, only its new ones, or the whole volume.

Passages without a translation keep their source text. Before the end the answer is 409 result_not_ready (with Retry-After), unless partial=true.

Scope: results:read.

Parameters

Name	In	Type	Description
`request_id` required	path	string	The request's `request_id`.
`format`	query	string	Result format; wins over the `Accept` header. Default: the request's own format (EPUB for an EPUB). One of `"json"`, `"txt"`, `"txt-zip"`, `"epub"`, `"epub-bilingual"`.
`partial`	query	boolean	Return what is translated so far instead of `409 result_not_ready` (missing passages keep their source text; `X-Libris-Complete: false`). Default `false`.
`wait`	query	integer	Long poll: answer as soon as the request ends, or after this many seconds (bounded by the server's `API_RESULT_MAX_WAIT_SECONDS`, 60 by default). Default `0`. Minimum 0. Maximum 600.
`layout`	query	string	`format=epub-bilingual` only: each source paragraph followed by its translation (`interleaved`) or next to it in two columns that stack on a narrow screen (`side-by-side`). One of `"interleaved"`, `"side-by-side"`. Default `"interleaved"`.
`scope`	query	string	The chapters covered: those the request sent (`request`, the whole book for an EPUB), only those it created or replaced (`new`), or every chapter of the volume (`volume`). `epub` is always the whole book. One of `"request"`, `"new"`, `"volume"`. Default `"request"`.

Answers

Status	Description	Content
200	The result. `X-Libris-Complete` tells whether every passage is translated. `application/epub+zip`: The translated EPUB (`format=epub`), or the bilingual EPUB (`format=epub-bilingual`). `application/json`: The JSON document (`format=json`). `text/plain`: One UTF-8 text file, chapters under their headings (`format=txt`). `application/zip`: `chapters/001 - Title.txt`… and `manifest.json` with each file's SHA-256 (`format=txt-zip`). Headers: `X-Libris-CompleteX-Libris-StatusContent-Disposition`	`application/epub+zip` file `application/json` `JsonResult` `text/plain` string `application/zip` file
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown request, or its volume was deleted. Codes: `request_not_found`, `volume_not_found`.	`application/json` `Error`
409	The result cannot be served yet or at all. Codes: `result_not_ready`, `request_failed`, `request_cancelled`, `format_unavailable`. Headers: `Retry-After`	`application/json` `Error`
422	A bad parameter, or an EPUB rendered on demand could not be built. Codes: `invalid_request`, `delivery_failed`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Series

The series of the token's owner and their volumes.

List your series

GET /api/v1/series

The series the token's owner owns, sorted by name.

Scope: series:read.

Answers

Status	Description	Content
200	Success.	`application/json` array of `SeriesSummary`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Get a series and its volumes

GET /api/v1/series/{series_id}

Scope: series:read.

Parameters

Name	In	Type	Description
`series_id` required	path	string	The series' `id`.

Answers

Status	Description	Content
200	Success.	`application/json` `SeriesDetail`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown, or owned by someone else. Codes: `series_not_found`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Providers

The model providers a request may name.

List the providers

GET /api/v1/providers

The providers a request may name in provider_id, sorted by name: identity and model only, never an address or a key.

Scope: content:write.

Answers

Status	Description	Content
200	Success.	`application/json` array of `Provider`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Glossaries

Shared glossaries: the terminology of a universe several of your series follow.

List your shared glossaries

GET /api/v1/glossaries

Your shared glossaries, sorted by name, with their term counts and the series that follow them.

Scope: series:read.

Answers

Status	Description	Content
200	Success.	`application/json` array of `SharedGlossary`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Create a shared glossary

POST /api/v1/glossaries

An empty shared glossary; fill it with an import. Languages are optional: with them, it only applies to volumes of the same pair.

Scope: content:write.

Request body

application/json · SharedGlossaryInput

Answers

Status	Description	Content
201	Success.	`application/json` `SharedGlossaryDetail`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
409	You already have a shared glossary of that name. Codes: `glossary_exists`.	`application/json` `Error`
422	A bad body, or a blank name. Codes: `invalid_request`, `invalid_name`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Get a shared glossary and its terms

GET /api/v1/glossaries/{glossary_id}

Scope: series:read.

Parameters

Name	In	Type	Description
`glossary_id` required	path	string	The shared glossary's `id`.

Answers

Status	Description	Content
200	Success.	`application/json` `SharedGlossaryDetail`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown, or owned by someone else. Codes: `glossary_not_found`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Download a shared glossary

GET /api/v1/glossaries/{glossary_id}/export/{format}

Its terms as JSON, CSV (for spreadsheets: delimiter=semicolon&bom=true) or TBX, with the fields source, translation, category, description, locked, accepted.

Scope: series:read.

Parameters

Name	In	Type	Description
`glossary_id` required	path	string	The shared glossary's `id`.
`format` required	path	string	`json`, `csv` or `tbx`. One of `"json"`, `"csv"`, `"tbx"`.
`delimiter`	query	string	CSV separator. One of `"comma"`, `"semicolon"`, `"tab"`. Default `"comma"`.
`bom`	query	boolean	Start a CSV file with a UTF-8 byte order mark (for Excel). Default `false`.

Answers

Status	Description	Content
200	The file, with a `Content-Disposition` file name. Headers: `Content-Disposition`	`application/json` array of object `text/csv` string `application/x-tbx+xml` string
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown, or owned by someone else. Codes: `glossary_not_found`.	`application/json` `Error`
422	A bad parameter. Codes: `invalid_request`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Import terms into a shared glossary

POST /api/v1/glossaries/{glossary_id}/import

Reads a JSON, CSV or TBX file into the glossary and answers the import report. With dry_run=true, nothing changes: the report is a preview that lists invalid rows instead of refusing the file. Sources are matched case-insensitively.

Scope: content:write.

Parameters

Name	In	Type	Description
`glossary_id` required	path	string	The shared glossary's `id`.
`dry_run`	query	boolean	Preview the import without changing anything. Default `false`.

Request body

multipart/form-data · GlossaryImportForm

Answers

Status	Description	Content
200	Success.	`application/json` `GlossaryImportReport`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown, or owned by someone else. Codes: `glossary_not_found`.	`application/json` `Error`
413	The file is above 2 MB. Codes: `glossary_too_large`.	`application/json` `Error`
422	The file cannot be read, has invalid rows (without `skip_invalid`), or an import option is invalid. Codes: `invalid_glossary`, `invalid_strategy`, `invalid_mapping`, `invalid_request`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Get the shared glossary a series follows

GET /api/v1/series/{series_id}/shared-glossary

Scope: series:read.

Parameters

Name	In	Type	Description
`series_id` required	path	string	The series' `id`.

Answers

Status	Description	Content
200	Success.	`application/json` `SeriesSharedGlossary`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown series, or owned by someone else. Codes: `series_not_found`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Attach a series to a shared glossary

PUT /api/v1/series/{series_id}/shared-glossary

The series follows this shared glossary from its next passages on (at most one per series); glossary_id: null detaches it. A glossary with languages only fits a series of the same pair.

Scope: content:write.

Parameters

Name	In	Type	Description
`series_id` required	path	string	The series' `id`.

Request body

application/json · SharedGlossaryAttachment

Answers

Status	Description	Content
200	Success.	`application/json` `SeriesSharedGlossary`
401	A missing, unknown, revoked or expired token, or a disabled account (header `WWW-Authenticate: Bearer`). Codes: `missing_token`, `invalid_token`, `revoked_token`, `expired_token`, `inactive_account`, `unauthorized`. Headers: `WWW-Authenticate`	`application/json` `Error`
403	The token lacks the scope (`scope` names it), or a browser page from another site. Codes: `insufficient_scope`, `forbidden`.	`application/json` `Error`
404	Unknown series or glossary, or owned by someone else. Codes: `series_not_found`, `glossary_not_found`.	`application/json` `Error`
409	The glossary's languages differ from the series'. Codes: `language_mismatch`.	`application/json` `Error`
422	A bad body. Codes: `invalid_request`.	`application/json` `Error`
429	Too many calls for this token; retry after `Retry-After` seconds. Codes: `rate_limited`. Headers: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Webhooks

Chapters were translated

POST callback_url

Sent by the worker to the request's callback_url while its job runs, once per batch of chapters whose passages all have a translation, when the request listed chapters.translated in callback_events. Batches go before the final webhook when both are due, but a retried batch can arrive after it: order them by batch. The text of a batch is a draft until the request ends. Check the signature over the raw body and refuse old timestamps. Any 2xx counts as delivered; anything else is retried with an exponential backoff (30 s, 60 s… up to one hour) at most API_WEBHOOK_MAX_ATTEMPTS times. Redirects are not followed.

Parameters

Name	In	Type	Description
`X-Libris-Event` required	header	string	`chapters.translated`.
`X-Libris-Delivery` required	header	string	`<request id>:chapters.translated:<batch>:<attempt number>`.
`X-Libris-Timestamp` required	header	string	Unix time in seconds.
`X-Libris-Signature` required	header	string	`sha256=<hex>`: HMAC-SHA256 of `<timestamp>.<raw body>` with the token's webhook secret, or the server's `API_WEBHOOK_SECRET`.

Request body

application/json · ChaptersTranslatedEvent

Answers

Status	Description	Content
2XX	Delivered.

A request ended

POST callback_url

Sent by the worker to the request's callback_url when it ends. Check the signature over the raw body and refuse old timestamps. Any 2xx counts as delivered; anything else is retried with an exponential backoff (30 s, 60 s… up to one hour) at most API_WEBHOOK_MAX_ATTEMPTS times. Redirects are not followed.

Parameters

Name	In	Type	Description
`X-Libris-Event` required	header	string	`translation_request.finished`.
`X-Libris-Delivery` required	header	string	`<request id>:<attempt number>`.
`X-Libris-Timestamp` required	header	string	Unix time in seconds.
`X-Libris-Signature` required	header	string	`sha256=<hex>`: HMAC-SHA256 of `<timestamp>.<raw body>` with the token's webhook secret, or the server's `API_WEBHOOK_SECRET`.

Request body

application/json · WebhookEvent

Answers

Status	Description	Content
2XX	Delivered.

Schemas

The documents the operations send and receive. Answers may gain fields in later versions: ignore the ones you do not know.

`AnalysisPhase`

object

Where a running analysis is; null when no analysis runs.

Name	Type	Description
`step`required	string	Parallel analysis: `extraction`, `consolidation`, `reconciliation`, `memory`, then `book_bible`; strict analysis: `chapter_analysis`, then `book_bible`. One of `"extraction"`, `"consolidation"`, `"reconciliation"`, `"memory"`, `"chapter_analysis"`, `"book_bible"`.
`current`required	integer	Passages (or Book Bible syntheses) started in this step.
`total`required	integer
`level`	integer	`book_bible` of a parallel analysis: the level of the tree being built.
`levels`	integer	Levels of the Book Bible tree.
`percent`required	integer	How far the whole analysis is, 0–100.

`ChapterCounts`

object

How many chapters the request created, found unchanged or replaced, and each chapter's progress.

Name	Type	Description
`created`	integer
`unchanged`	integer
`replaced`	integer
`items`required	array of `ChapterProgress`
`new`required	array of string	The chapters the request created or replaced (ids): the ones a follow-up translates.

`ChapterEvents`

object

The chapters.translated webhooks of the request.

Name	Type	Description
`event`required	string	One of `"chapters.translated"`.
`batches`required	integer	Batches queued so far.
`delivered`required	integer
`pending`required	integer
`failed`required	integer
`waiting_chapters`required	integer	Chapters of the request not translated (nor announced) yet.
`error`required	string	Last failure of a batch, empty when none.

`ChapterInput`

object

Name	Type	Description
`external_id`	string \| null	Your identifier of the chapter: sending it again finds the same chapter. Pattern `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$`.
`number`	number \| null	Chapter number, 0–100000; decimals such as `12.5` (a real half chapter) allowed. Required for a chapter unless the title gives it; for a special (`kind`), its own number (`Interlude 2`). Minimum 0. Maximum 100000.
`title`	string	Optional; without it the chapter is named by its number. At most 500 characters.
`content`required	string	The chapter's text (not blank, at most `TEXT_CHAPTER_MAX_CHARS` characters).
`kind`	string \| null	What the chapter is: `chapter`, `prologue`, `interlude`, `side_story`, `extra`, `epilogue`, `afterword`, `author_note`, `front_matter`. Absent: read from the title (`Prologue`, `Interlude – Ayla`), else `chapter`. One of `"chapter"`, `"prologue"`, `"interlude"`, `"side_story"`, `"extra"`, `"epilogue"`, `"afterword"`, `"author_note"`, `"front_matter"`.
`part`	integer \| null	Part of a chapter published in several, 1–999 (`Chapter 12 (Part 2)`: `number` 12, `part` 2). Absent: read from the title. Minimum 1. Maximum 999.
`part_count`	integer \| null	How many parts the chapter has, when known. Minimum 1. Maximum 999.
`label`	string \| null	Name shown after the kind (`Ayla` in `Interlude – Ayla`). At most 200 characters.
`after`	string \| number \| null	Insert after this chapter: its Libris `chapter_id`, its `external_id` (of the volume or of this request), a chapter number (after that chapter, its parts and the specials already after it), or `start`. Unknown: `422 invalid_placement`. Also moves a chapter sent again.
`position`	integer \| null	Insert at this reading position (0: first). Not with `after`. Minimum 0. Maximum 100000.

`ChapterProgress`

object

Name	Type	Description
`chapter_id`required	string	Identifier (UUID).
`external_id`required	string \| null
`number`required	number \| null	The chapter's number; a special's own number (`Interlude 2`).
`kind`required	string	What the chapter is in the reading. One of `"chapter"`, `"prologue"`, `"interlude"`, `"side_story"`, `"extra"`, `"epilogue"`, `"afterword"`, `"author_note"`, `"front_matter"`.
`part`required	integer \| null	Part of a chapter published in several (`Chapter 12 (Part 2)`).
`part_count`required	integer \| null	How many parts the chapter has, when known.
`label`required	string	The name after the kind and number (`Ayla` in `Interlude – Ayla`).
`display_label`required	string	The full label in the source language (`Chapter 12 (Part 2)`).
`position`required	integer	Reading position in the volume: what orders chapters, not the number.
`mapping`required	object \| null	How the map was decided: `confidence`, `reason`, `detected` (read from the title).
`title`required	string
`segments`required	integer
`translated`required	integer
`validated`required	integer
`flagged`required	integer	Passages still flagged (`check`, `error`, `refused`) and not validated.
`complete`required	boolean

`ChaptersTranslatedEvent`

object

Sent while the job runs, once per batch of chapters whose passages all have a translation.

Name	Type	Description
`event`required	string	One of `"chapters.translated"`.
`request_id`required	string	Identifier (UUID).
`external_id`required	string \| null
`series_id`required	string \| null
`project_id`required	string \| null
`batch`required	integer	Counts from 1 per request; order batches by it.
`chapters`required	array of object	The chapters of this batch, in reading order.
`announced`required	integer	Chapters announced so far, this batch included.
`total`required	integer	Chapters in the request.
`status_url`required	string
`result_url`required	string	Partial result of the request (`?partial=true`).
`created_at`required	number	Unix time in seconds.

`CompletionReport`

object

What was translated, what kept its source and why, what it cost and how long it took, and the quality scores of its passages.

Name	Type	Description
`version`required	integer
`outcome`required	string	One of `"completed"`, `"completed_with_residuals"`, `"failed"`, `"cancelled"`, `"imported"`.
`reason`required	string \| null	Why the request did not complete.
`passages`required	object	Counts over the request's passages (the whole book for an EPUB).
`passages.total`required	integer
`passages.translated`required	integer
`passages.source_retained`required	integer
`passages.untranslated`required	integer
`passages.flagged`required	integer
`passages.validated`required	integer
`passages.human`required	integer
`passages.by_status`required	object of integer	Passages per status.
`residual_total`required	integer
`residuals`required	array of `Residual`	At most 500; `residuals_truncated` tells when the list is cut.
`residuals_truncated`required	boolean
`usage`required	`Usage`
`durations`required	object
`durations.total_seconds`required	number
`durations.queued_seconds`required	number \| null
`durations.job_seconds`required	number \| null
`autopilot`required	object \| null	How the autopilot ended: `outcome`, `rounds`, `reason`.
`decisions`required	object
`decisions.autopilot`required	integer \| null	Decisions the autopilot logged for the job.
`decisions.intake`required	array of object	Choices made when reading the upload (volume and chapter numbers, encoding, reused EPUB), each with its reason.
`chapter_map`	array of object	Each chapter of the request: `chapter_id`, `external_id`, `status`, `kind`, `number`, `part`, `part_count`, `label`, `position`, and for a detection its `confidence` and `reason`.
`delivery`required	object \| null	EPUB only: EPUBCheck `validation`, `repairs`, `inherited_errors`, and `errors` when the delivery failed.
`cost`	`CostReport` \| null
`quality`	`QualityReport` \| null

`CostReport`

object

Estimated against real cost, in the currency of the provider prices, with the book's budget.

Name	Type	Description
`estimated`required	number \| null	The estimate made when the job started; `null` when none was made.
`actual`required	number \| null	The job's real cost (`usage.cost`); `null` when no call had a price.
`budget`required	number \| null	The book's cost budget; `null` without one.
`book_spent`required	number \| null	What the book has cost in all, every job included.
`warning`required	string \| null	The warning given at launch when the estimate exceeded what was left of a budget.
`paused_for_budget`required	boolean	Whether the job is paused because a budget was reached.
`provider_switches`required	integer	How many times the job moved to a cheaper fallback provider to stay within a budget.

`Error`

object

Every error of the automation API.

Name	Type	Description
`detail`required	`ErrorDetail`

`ErrorDetail`

object

Name	Type	Description
`code`required	string	Stable machine-readable code, for example `chapter_conflict`.
`message`required	string	Human-readable explanation, French by default, English with `Accept-Language: en`.
`errors`	array of `ValidationIssue`	Validation problems (`invalid_payload`, `invalid_request`).
`scope`	string	The missing scope (`insufficient_scope`), or whose quota is full, `token` or `account` (`queue_full`).
`limit`	integer	The quota that is full (`queue_full`).
`max_priority`	string	The highest priority the token and its account may ask for (`priority_not_allowed`). One of `"low"`, `"normal"`, `"high"`.
`budget`	object	The token's cost budget (`budget_exceeded` answered with `402`).
`budget.amount`required	number	The token's cap, in the currency of the provider prices.
`budget.spent`required	number	What the current period has spent.
`budget.period`required	string	`month` (calendar month, UTC) or `total`. One of `"month"`, `"total"`.
`budget.resets_at`required	number \| null	Start of the next month (Unix time); `null` for a total cap.
`request_id`	string	The request that already used this key (`idempotency_conflict`).
`status`	string	The request's status (`result_not_ready`, `request_failed`…).
`reason`	string	Why the request failed or was cancelled.
`incomplete_chapters`	array of string	Chapters not fully translated yet.
`conflicts`	array of any	Chapters already imported with another text (`chapter_conflict`).
`protected_segments`	array of any	Passages edited by a person that a replacement would drop.

`GlossaryImportForm`

object

A glossary file and how to read it. CSV files may carry a byte order mark; French or English headers are recognised.

Name	Type	Description
`file`required	file	The glossary: JSON, CSV or TBX (v2 and v3), 2 MB at most.
`strategy`	string	`skip` keeps the terms in place; `replace` replaces unlocked terms that differ; `replace_all` replaces locked ones too. One of `"skip"`, `"replace"`, `"replace_all"`. Default `"skip"`.
`delimiter`	string	CSV separator; detected when absent. One of `"comma"`, `"semicolon"`, `"tab"`.
`mapping`	string	JSON object from field to column number (from 0), for example `{"source": 0, "translation": 2}`; from the headers when absent.
`header`	boolean	Whether the first row holds column names; detected when absent.
`skip_invalid`	boolean	Leave invalid rows out instead of refusing the file. Default `false`.

`GlossaryImportReport`

object

The import plan: what the file adds, what conflicts with the terms in place and what is invalid.

Name	Type	Description
`format`required	string	One of `"json"`, `"csv"`, `"tbx"`.
`encoding`	string
`delimiter`	string \| null
`columns`	array of any	The first row of a CSV file.
`header`	boolean \| null
`mapping`	object \| null	Field → column number used.
`strategy`required	string	One of `"skip"`, `"replace"`, `"replace_all"`.
`counts`required	object
`counts.terms`required	integer
`counts.new`required	integer
`counts.unchanged`required	integer
`counts.conflicts`required	integer
`counts.replaced`required	integer
`counts.kept`required	integer
`counts.duplicates`required	integer
`counts.errors`required	integer
`new`required	array of object	Terms the import adds (at most 200).
`conflicts`required	array of object	Sources already present with other values: `existing`, `incoming`, the differing `fields`, `locked` and the `action` (`replace` or `keep`); at most 200.
`duplicates`required	array of object	A source repeated in the file (the first row counts); at most 200.
`errors`required	array of object	Invalid rows: `line`, `message`; at most 200.
`truncated`required	boolean	Whether a list was cut at 200 items.
`applied`required	boolean	`false` for a preview (`dry_run=true`).
`imported`	integer	Applied imports only: terms added.
`replaced`	integer	Applied imports only: terms replaced.
`skipped`	integer	Applied imports only: terms left as they were.

`JsonResult`

object

The JSON result (?format=json).

Name	Type	Description
`schema_version`required	integer
`request_id`required	string	Identifier (UUID).
`external_id`required	string \| null
`status`required	`RequestStatus`
`complete`required	boolean
`series`required	object \| null
`series.id`required	string	Identifier (UUID).
`series.name`required	string
`volume`required	object
`volume.project_id`required	string	Identifier (UUID).
`volume.external_id`required	string \| null
`volume.number`required	integer \| null
`volume.title`required	string
`source_language`required	string
`target_language`required	string
`strategy`required	object	Provider name and model (never its address or key), `quality`, `context_backend`, `final_review`.
`incomplete_chapters`required	array of string
`chapters`required	array of `ResultChapter`
`report`required	`CompletionReport` \| null
`scope`	string	What the result covers: the request's chapters, only the new ones, or the whole volume. One of `"request"`, `"new"`, `"volume"`.

`OutputOptions`

object

Name	Type	Description
`format`	string	Default format of the result; `epub-bilingual` is a bilingual EPUB for proofreading. One of `"json"`, `"txt"`, `"txt-zip"`, `"epub-bilingual"`. Default `"json"`.

`PipelineOptions`

object

Name	Type	Description
`start`	boolean	Run the whole pipeline (needs the `pipeline:start` scope); false only imports. Default `true`.
`provider_id`	string \| null	Provider to use; defaults to the volume's, then the series' provider. At most 36 characters.
`quality`	string \| null	One of `"fast"`, `"normal"`, `"high"`, `"maximum"`.
`context_backend`	string \| null	One of `"internal"`, `"openviking"`, `"hybrid"`.
`final_review`	boolean	Run the final review (never when the server disables it). Default `true`.
`priority`	string \| null	Place in the fair queue: `low`, `normal` (default) or `high`, within the token's `max_priority` and its account's ceiling (otherwise `403 priority_not_allowed`). Does not change what the request is. One of `"low"`, `"normal"`, `"high"`.
`analysis_mode`	string \| null	`parallel`: the passages are analysed side by side, then each is reconciled with what precedes it; `strict`: one passage after the other. Default: the volume's choice, else `ANALYSIS_MODE`. One of `"parallel"`, `"strict"`.
`threads`	integer \| null	Passages worked on at once, analysis and translation alike (1–64). It can only lower the volume's share of the provider's capacity; default: that share. Minimum 1. Maximum 64.

`Progress`

object

Name	Type	Description
`segments`required	integer	Passages of the request's chapters (the whole book for an EPUB).
`translated`required	integer
`percent`required	integer
`stages`required	array of `StageProgress`	The volume's progress per stage.
`analysis`required	`AnalysisPhase` \| null

`Provider`

object

A provider a request may name: identity and model only, never an address or a key.

Name	Type	Description
`id`required	string	Identifier (UUID).
`name`required	string
`kind`required	string	`openai`, `openai_direct`, `openai_responses`, `anthropic` or `codex_chatgpt`.
`model`required	string
`created_at`required	number	Unix time in seconds.
`default_for_series`required	array of string	Your series that use this provider by default.

`QualityReport`

object

Quality scores (0–100) of the passages the request covers, computed from the signals Libris records (checks, critiques, doubts, failed calls, recoveries, retained originals); no model call.

Name	Type	Description
`scored`required	integer	Passages with a score.
`average`required	number \| null	Average score (0–100); `null` when none is scored.
`minimum`required	integer \| null	Lowest score.
`bands`required	object of integer	Passages per band: `good` (85 and above), `fair` (70), `weak` (50), `poor` (below).
`histogram`required	array of integer	Passages per ten-point bucket, from 0–9 to 90–100.
`to_review`required	integer	Passages below `review_below` that no person validated.
`review_below`required	integer	The score under which a passage should be reviewed.
`weakest_chapters`required	array of object	The 10 chapters with the lowest scores: `chapter_id`, `title`, `external_id`, `number`, `passages`, `scored`, `average`, `minimum`, `weak`…
`review_first`required	array of object	The 10 passages to review first: `segment_id`, `chapter_id`, `position`, `score`, `band` and the `signals` (`code`, `count`, `penalty`) that lowered them.

`QueuePlace`

object

Where a request that has not started yet stands in the fair queue.

Name	Type	Description
`position`required	integer \| null	Place in the line of its provider (1: next); `null` when it waits for its volume.
`reason`required	string \| null	Why it waits: `starting`, `provider_busy`, `account_limit`, `token_limit`, `retry_scheduled`, `provider_missing`, or `volume_busy` while another job holds the volume.
`effective_priority`	string	Its priority, raised one level after a long wait. One of `"low"`, `"normal"`, `"high"`.
`next_attempt`	number	When a waiting job retries (Unix time, `0` when not waiting).

`RequestDetail`

object

The status document of a request.

Name	Type	Description
`request_id`required	string	Identifier (UUID).
`external_id`required	string \| null	Your identifier of the request.
`series_id`required	string \| null	Identifier (UUID).
`project_id`required	string \| null	The volume (UUID).
`job_id`required	string \| null	The pipeline job; `null` while the request waits (`queued`).
`input`required	string	What was sent. One of `"epub"`, `"txt"`, `"docx"`, `"json"`.
`status`required	`RequestStatus`
`status_url`required	string	Path of the status document.
`result_url`required	string	Path of the result.
`created_at`required	number	Unix time in seconds.
`updated_at`required	number	Unix time in seconds.
`finished_at`required	number \| null	Unix time in seconds.
`stage`required	string \| null	Current stage of the volume (`null` without a job).
`step`required	string \| null	Current step of the job, for example `translation`, `final_review`.
`progress`required	`Progress`
`estimate`required	object \| null	Remaining time and cost, once enough calls were observed.
`error`required	string	Why the job stopped or failed; empty otherwise.
`stop_reason`required	string
`next_attempt`required	number	When a waiting job retries (Unix time, `0` when not waiting).
`chapters`required	`ChapterCounts`
`options`required	object
`options.start`required	boolean
`options.final_review`required	boolean
`options.output_format`required	string \| null
`options.analysis_mode`required	string \| null	One of `"parallel"`, `"strict"`, `null`.
`options.threads`required	integer \| null
`priority`required	string	The request's priority, as changed by a person in the interface if it was. One of `"low"`, `"normal"`, `"high"`.
`queue`required	`QueuePlace` \| null
`result`required	`StoredResult` \| null
`report`required	`CompletionReport` \| null
`webhook`required	`WebhookState` \| null
`chapter_events`required	`ChapterEvents` \| null

`RequestStatus`

string

queued: waiting for its volume. imported: chapters imported, nothing started (end state). pending/running: the job waits for a worker or works. paused, waiting (provider temporarily unavailable, retried), blocked (needs attention). finalizing: the result is being built. End states: completed, completed_with_residuals (some passages kept their source, listed in the report), failed, cancelled.

One of "queued", "imported", "pending", "running", "paused", "waiting", "blocked", "finalizing", "completed", "completed_with_residuals", "failed", "cancelled".

`RequestSummary`

object

A translation request, as answered when it is created.

Name	Type	Description
`request_id`required	string	Identifier (UUID).
`external_id`required	string \| null	Your identifier of the request.
`series_id`required	string \| null	Identifier (UUID).
`project_id`required	string \| null	The volume (UUID).
`job_id`required	string \| null	The pipeline job; `null` while the request waits (`queued`).
`input`required	string	What was sent. One of `"epub"`, `"txt"`, `"docx"`, `"json"`.
`status`required	`RequestStatus`
`status_url`required	string	Path of the status document.
`result_url`required	string	Path of the result.

`Residual`

object

A passage delivered in its source text.

Name	Type	Description
`segment_id`required	string	Identifier (UUID).
`chapter_id`	string	Identifier (UUID).
`chapter_external_id`	string \| null
`chapter_title`	string
`position`	integer
`status`	string
`kept`required	string	One of `"source"`.
`reason`required	string	The autopilot's reason, the passage's last error, or `source_retained`, `untranslated`, `markup_mismatch`, `epubcheck_repair`.

`ResultChapter`

object

Name	Type	Description
`chapter_id`required	string	Identifier (UUID).
`external_id`required	string \| null
`number`required	number \| null
`kind`required	string	One of `"chapter"`, `"prologue"`, `"interlude"`, `"side_story"`, `"extra"`, `"epilogue"`, `"afterword"`, `"author_note"`, `"front_matter"`.
`part`required	integer \| null
`part_count`required	integer \| null
`label`required	string
`display_label`required	string	The label in the target language (`Chapitre 12 (partie 2)`).
`position`required	integer	Reading position: chapters are listed in this order.
`title`required	string
`translated_title`required	string
`complete`required	boolean
`missing_segments`required	integer
`translation`required	string	The chapter's text; missing passages keep their source text.
`source_sha256`required	string \| null	SHA-256 of the normalized source text (`null` when not recorded).
`sha256`required	string	SHA-256 of `translation` (UTF-8).
`review`required	object
`review.segments`required	integer
`review.validated`required	integer
`review.flagged`required	integer
`issues`required	array of object	Unresolved quality issues: `segment_id`, `severity`, `code`, `message`.
`flagged_passages`required	array of object	Passages still flagged: `segment_id`, `position`, `status`.

`SeriesDetail`

object

Name	Type	Description
`id`required	string	Identifier (UUID).
`name`required	string
`kind`required	string
`source_language`required	string \| null
`target_language`required	string \| null
`archived`required	boolean
`volumes`required	integer
`created_at`required	number	Unix time in seconds.
`updated_at`required	number	Unix time in seconds.
`volume_list`required	array of `VolumeSummary`	Sorted by volume number.

`SeriesReference`

object

Name	Type	Description
`id`	string \| null	A series you own. At most 36 characters.
`name`	string \| null	Found by name; created when missing unless `create_if_missing` is false. At most 500 characters.
`create_if_missing`	boolean	Create the series named by `name` when it does not exist. Default `true`.

`SeriesSharedGlossary`

object

The shared glossary the series follows, with its terms; null when it follows none.

Name	Type	Description
`glossary`required	`SharedGlossaryDetail` \| null

`SeriesSummary`

object

Name	Type	Description
`id`required	string	Identifier (UUID).
`name`required	string
`kind`required	string
`source_language`required	string \| null
`target_language`required	string \| null
`archived`required	boolean
`volumes`required	integer
`created_at`required	number	Unix time in seconds.
`updated_at`required	number	Unix time in seconds.

`SharedGlossary`

object

A named glossary several series of the same universe follow. Its accepted terms come after the book's and the series' own (book > series > shared glossary).

Name	Type	Description
`id`required	string	Identifier (UUID).
`name`required	string
`description`required	string
`source_language`required	string \| null
`target_language`required	string \| null
`created_at`required	number	Unix time in seconds.
`updated_at`required	number	Unix time in seconds.
`term_count`required	integer
`locked_count`required	integer	Locked terms: enforced and checked in every passage.
`series`required	array of object	The series that follow it.

`SharedGlossaryAttachment`

object

The shared glossary a series follows.

Name	Type	Description
`glossary_id`required	string \| null	The shared glossary to follow; `null` detaches the series.

`SharedGlossaryDetail`

object

A shared glossary with its terms.

Name	Type	Description
`id`required	string	Identifier (UUID).
`name`required	string
`description`required	string
`source_language`required	string \| null
`target_language`required	string \| null
`created_at`required	number	Unix time in seconds.
`updated_at`required	number	Unix time in seconds.
`term_count`required	integer
`locked_count`required	integer	Locked terms: enforced and checked in every passage.
`series`required	array of object	The series that follow it.
`terms`required	array of `SharedTerm`	Sorted by source.

`SharedGlossaryInput`

object

A new shared glossary.

Name	Type	Description
`name`required	string	1–200 characters, unique among your shared glossaries. At least 1 characters. At most 200 characters.
`description`	string	At most 4000 characters. At most 4000 characters.
`source_language`	string \| null	BCP 47 tag; with the target, the glossary only applies to volumes of that pair.
`target_language`	string \| null	BCP 47 tag.

`SharedTerm`

object

Name	Type	Description
`id`required	string	Identifier (UUID).
`source`required	string
`translation`required	string
`category`required	string
`description`required	string
`locked`required	boolean	Enforced by the pipeline and the autopilot, checked in every passage.
`accepted`required	boolean	Only accepted terms are applied.

`StageProgress`

object

Name	Type	Description
`key`required	string	`import`, `analysis`, `translation`, `review` or `export`.
`done`required	integer
`total`required	integer
`percent`required	integer

`StoredResult`

object

The result file stored when the request ended successfully.

Name	Type	Description
`format`required	string	One of `"epub"`, `"json"`, `"txt"`, `"txt-zip"`, `"epub-bilingual"`.
`media_type`required	string
`filename`required	string
`size`required	integer	Bytes.
`sha256`required	string
`created_at`required	number	Unix time in seconds.

`TranslationPayload`

object

A JSON translation request. Unknown fields are refused; nothing is ever downloaded from a URL it names.

Name	Type	Description
`external_id`	string \| null	Your identifier of the request: a letter or digit, then letters, digits and `._:/-` (200 at most). Unique per owner: the same content sent again returns the original request. Pattern `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$`.
`series`required	`SeriesReference`	The series: `id` (one you own) or `name`.
`volume`required	`VolumeReference`	The volume: found by `external_id`, then by `number` in the series; otherwise created.
`author`	string	Author of the volume. At most 500 characters.
`source_language`required	string	BCP 47 tag such as `en`, `fr-FR`, `zh-Hant`. At most 35 characters.
`target_language`required	string	BCP 47 tag. At most 35 characters.
`chapters`required	array of `ChapterInput`	1 to `API_MAX_CHAPTERS` chapters; numbers (with their part) and `external_id`s must not repeat. Numbered chapters are placed by number and part; a special after the chapter it follows in this list. At least 1 items.
`replace_changed_chapters`	boolean	Replace chapters already imported with another text (otherwise `409 chapter_conflict`). Unchanged passages keep their translation. Default `false`.
`discard_human`	boolean	With `replace_changed_chapters`: allow dropping passages a person edited or validated (otherwise `409 conflict`). Default `false`.
`pipeline`	`PipelineOptions`	How to run the pipeline.
`output`	`OutputOptions`	Default format of the result.
`callback_url`	string \| null	Webhook called when the request ends; its host must be allowed by an administrator. At most 2000 characters.
`callback_events`	array of string	Extra webhooks on top of `translation_request.finished`: `chapters.translated` sends one per batch of chapters translated while the job runs.

`Usage`

object

Model calls of the request's job.

Name	Type	Description
`calls`required	integer
`prompt_tokens`required	integer
`completion_tokens`required	integer
`cached_calls`required	integer
`cost`required	number \| null	Cost of the calls with a known price; `null` when none had one.

`ValidationIssue`

object

Name	Type	Description
`loc`required	array of string \| integer	Where the problem is, for example `["chapters", 0, "number"]`.
`msg`required	string	What is wrong (the submitted value is never repeated).
`type`	string	Kind of problem.

`VolumeReference`

object

Name	Type	Description
`external_id`	string \| null	Your identifier of the volume. Pattern `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$`.
`latest`	boolean	Follow up a webnovel: the chapters go to the series' last numbered volume (else its continuous chapter container, else volume 1). Not with `number`. Default `false`.
`number`	integer \| null	Volume number, 1–10000. Required unless `latest` is true. Minimum 1. Maximum 10000.
`title`	string	Title of a new volume (default: “Series — number”). At most 500 characters.

`VolumeSummary`

object

Name	Type	Description
`project_id`required	string	Identifier (UUID).
`title`required	string
`volume_number`required	integer \| null
`external_id`required	string \| null
`source_format`required	string
`project_kind`required	string
`status`required	string
`chapters`required	integer

`WebhookEvent`

object

Sent once when a request ends (any end state, imported included).

Name	Type	Description
`event`required	string	One of `"translation_request.finished"`.
`request_id`required	string	Identifier (UUID).
`external_id`required	string \| null
`status`required	`RequestStatus`
`error`required	string \| null
`project_id`required	string \| null
`job_id`required	string \| null
`status_url`required	string
`result_url`required	string
`artifact`required	object \| null
`artifact.format`required	string
`artifact.size`required	integer
`artifact.sha256`required	string
`report`required	`CompletionReport` \| null
`finished_at`required	number \| null	Unix time in seconds.

`WebhookState`

object

Name	Type	Description
`state`required	string	One of `"pending"`, `"delivered"`, `"failed"`.
`attempts`required	integer
`error`required	string	Last failure, empty when none.