API d’automatisation · Référence

Référence de l’API

Chaque opération de /api/v1, avec sa portée, ses paramètres, ses corps, ses réponses et ses codes d’erreur, générée à partir de la description OpenAPI livrée avec Libris. Chargez le même fichier dans n’importe quel outil OpenAPI ou générateur de client.

OpenAPI 3.1.0 · version d’API 1 · Les descriptions viennent du fichier OpenAPI et sont en anglais.

Télécharger le fichier OpenAPI Le voir sur GitHub Retour à la présentation de l’API

Vue d’ensemble

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.

Paramètres

Nom	Où	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`.

Corps de la requête

application/json · TranslationPayload

Exemple

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.

Nom	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 d’un EPUB envoyé brut

Avec Content-Type: application/epub+zip, les options passent dans la chaîne de requête. Ce sont les mêmes que les champs de l’envoi multipart :

filenameexternal_idseriesseries_idvolumevolume_external_idtitleauthorsource_languagetarget_languageprovider_idqualitycontext_backendstartfinal_reviewoutput_formatcallback_urlcallback_eventsreplace_changed_chaptersdiscard_humanpriorityanalysis_modethreadssplit

Réponses

Statut	Description	Contenu
200	Replayed: this content was already sent with this key or `external_id`. En-têtes: `LocationIdempotent-Replayed`	`application/json` `RequestSummary`
202	Accepted: the request is stored and will run in the worker. En-têtes: `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`. En-têtes: `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`. En-têtes: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Exemple · 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"
}

Exemple · 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.

Paramètres

Nom	Où	Type	Description
`request_id` obligatoire	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.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `Retry-After`	`application/json` `Error`
500	Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: `server_error`.	`application/json` `Error`

Exemple · 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.

Paramètres

Nom	Où	Type	Description
`request_id` obligatoire	path	string	The request's `request_id`.
`action` obligatoire	path	string	`pause`, `resume` or `cancel`. One of `"pause"`, `"resume"`, `"cancel"`.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`request_id` obligatoire	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"`.

Réponses

Statut	Description	Contenu
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`). En-têtes: `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`. En-têtes: `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`. En-têtes: `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`. En-têtes: `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.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`series_id` obligatoire	path	string	The series' `id`.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Corps de la requête

application/json · SharedGlossaryInput

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`glossary_id` obligatoire	path	string	The shared glossary's `id`.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`glossary_id` obligatoire	path	string	The shared glossary's `id`.
`format` obligatoire	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`.

Réponses

Statut	Description	Contenu
200	The file, with a `Content-Disposition` file name. En-têtes: `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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`glossary_id` obligatoire	path	string	The shared glossary's `id`.
`dry_run`	query	boolean	Preview the import without changing anything. Default `false`.

Corps de la requête

multipart/form-data · GlossaryImportForm

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`series_id` obligatoire	path	string	The series' `id`.

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

Nom	Où	Type	Description
`series_id` obligatoire	path	string	The series' `id`.

Corps de la requête

application/json · SharedGlossaryAttachment

Réponses

Statut	Description	Contenu
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`. En-têtes: `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`. En-têtes: `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.

Paramètres

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

Corps de la requête

application/json · ChaptersTranslatedEvent

Réponses

Statut	Description	Contenu
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.

Paramètres

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

Corps de la requête

application/json · WebhookEvent

Réponses

Statut	Description	Contenu
2XX	Delivered.

Schémas

Les documents que les opérations envoient et reçoivent. Les réponses peuvent gagner des champs dans les versions suivantes : ignorez ceux que vous ne connaissez pas.

`AnalysisPhase`

object

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

Nom	Type	Description
`step`obligatoire	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`obligatoire	integer	Passages (or Book Bible syntheses) started in this step.
`total`obligatoire	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`obligatoire	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.

Nom	Type	Description
`created`	integer
`unchanged`	integer
`replaced`	integer
`items`obligatoire	array of `ChapterProgress`
`new`obligatoire	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.

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

`ChapterInput`

object

Nom	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`obligatoire	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

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

`ChaptersTranslatedEvent`

object

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

Nom	Type	Description
`event`obligatoire	string	One of `"chapters.translated"`.
`request_id`obligatoire	string	Identifier (UUID).
`external_id`obligatoire	string \| null
`series_id`obligatoire	string \| null
`project_id`obligatoire	string \| null
`batch`obligatoire	integer	Counts from 1 per request; order batches by it.
`chapters`obligatoire	array of object	The chapters of this batch, in reading order.
`announced`obligatoire	integer	Chapters announced so far, this batch included.
`total`obligatoire	integer	Chapters in the request.
`status_url`obligatoire	string
`result_url`obligatoire	string	Partial result of the request (`?partial=true`).
`created_at`obligatoire	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.

Nom	Type	Description
`version`obligatoire	integer
`outcome`obligatoire	string	One of `"completed"`, `"completed_with_residuals"`, `"failed"`, `"cancelled"`, `"imported"`.
`reason`obligatoire	string \| null	Why the request did not complete.
`passages`obligatoire	object	Counts over the request's passages (the whole book for an EPUB).
`passages.total`obligatoire	integer
`passages.translated`obligatoire	integer
`passages.source_retained`obligatoire	integer
`passages.untranslated`obligatoire	integer
`passages.flagged`obligatoire	integer
`passages.validated`obligatoire	integer
`passages.human`obligatoire	integer
`passages.by_status`obligatoire	object of integer	Passages per status.
`residual_total`obligatoire	integer
`residuals`obligatoire	array of `Residual`	At most 500; `residuals_truncated` tells when the list is cut.
`residuals_truncated`obligatoire	boolean
`usage`obligatoire	`Usage`
`durations`obligatoire	object
`durations.total_seconds`obligatoire	number
`durations.queued_seconds`obligatoire	number \| null
`durations.job_seconds`obligatoire	number \| null
`autopilot`obligatoire	object \| null	How the autopilot ended: `outcome`, `rounds`, `reason`.
`decisions`obligatoire	object
`decisions.autopilot`obligatoire	integer \| null	Decisions the autopilot logged for the job.
`decisions.intake`obligatoire	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`obligatoire	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.

Nom	Type	Description
`estimated`obligatoire	number \| null	The estimate made when the job started; `null` when none was made.
`actual`obligatoire	number \| null	The job's real cost (`usage.cost`); `null` when no call had a price.
`budget`obligatoire	number \| null	The book's cost budget; `null` without one.
`book_spent`obligatoire	number \| null	What the book has cost in all, every job included.
`warning`obligatoire	string \| null	The warning given at launch when the estimate exceeded what was left of a budget.
`paused_for_budget`obligatoire	boolean	Whether the job is paused because a budget was reached.
`provider_switches`obligatoire	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.

Nom	Type	Description
`detail`obligatoire	`ErrorDetail`

`ErrorDetail`

object

Nom	Type	Description
`code`obligatoire	string	Stable machine-readable code, for example `chapter_conflict`.
`message`obligatoire	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`obligatoire	number	The token's cap, in the currency of the provider prices.
`budget.spent`obligatoire	number	What the current period has spent.
`budget.period`obligatoire	string	`month` (calendar month, UTC) or `total`. One of `"month"`, `"total"`.
`budget.resets_at`obligatoire	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.

Nom	Type	Description
`file`obligatoire	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.

Nom	Type	Description
`format`obligatoire	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`obligatoire	string	One of `"skip"`, `"replace"`, `"replace_all"`.
`counts`obligatoire	object
`counts.terms`obligatoire	integer
`counts.new`obligatoire	integer
`counts.unchanged`obligatoire	integer
`counts.conflicts`obligatoire	integer
`counts.replaced`obligatoire	integer
`counts.kept`obligatoire	integer
`counts.duplicates`obligatoire	integer
`counts.errors`obligatoire	integer
`new`obligatoire	array of object	Terms the import adds (at most 200).
`conflicts`obligatoire	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`obligatoire	array of object	A source repeated in the file (the first row counts); at most 200.
`errors`obligatoire	array of object	Invalid rows: `line`, `message`; at most 200.
`truncated`obligatoire	boolean	Whether a list was cut at 200 items.
`applied`obligatoire	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).

Nom	Type	Description
`schema_version`obligatoire	integer
`request_id`obligatoire	string	Identifier (UUID).
`external_id`obligatoire	string \| null
`status`obligatoire	`RequestStatus`
`complete`obligatoire	boolean
`series`obligatoire	object \| null
`series.id`obligatoire	string	Identifier (UUID).
`series.name`obligatoire	string
`volume`obligatoire	object
`volume.project_id`obligatoire	string	Identifier (UUID).
`volume.external_id`obligatoire	string \| null
`volume.number`obligatoire	integer \| null
`volume.title`obligatoire	string
`source_language`obligatoire	string
`target_language`obligatoire	string
`strategy`obligatoire	object	Provider name and model (never its address or key), `quality`, `context_backend`, `final_review`.
`incomplete_chapters`obligatoire	array of string
`chapters`obligatoire	array of `ResultChapter`
`report`obligatoire	`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

Nom	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

Nom	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

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

`Provider`

object

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

Nom	Type	Description
`id`obligatoire	string	Identifier (UUID).
`name`obligatoire	string
`kind`obligatoire	string	`openai`, `openai_direct`, `openai_responses`, `anthropic` or `codex_chatgpt`.
`model`obligatoire	string
`created_at`obligatoire	number	Unix time in seconds.
`default_for_series`obligatoire	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.

Nom	Type	Description
`scored`obligatoire	integer	Passages with a score.
`average`obligatoire	number \| null	Average score (0–100); `null` when none is scored.
`minimum`obligatoire	integer \| null	Lowest score.
`bands`obligatoire	object of integer	Passages per band: `good` (85 and above), `fair` (70), `weak` (50), `poor` (below).
`histogram`obligatoire	array of integer	Passages per ten-point bucket, from 0–9 to 90–100.
`to_review`obligatoire	integer	Passages below `review_below` that no person validated.
`review_below`obligatoire	integer	The score under which a passage should be reviewed.
`weakest_chapters`obligatoire	array of object	The 10 chapters with the lowest scores: `chapter_id`, `title`, `external_id`, `number`, `passages`, `scored`, `average`, `minimum`, `weak`…
`review_first`obligatoire	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.

Nom	Type	Description
`position`obligatoire	integer \| null	Place in the line of its provider (1: next); `null` when it waits for its volume.
`reason`obligatoire	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.

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

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

`Residual`

object

A passage delivered in its source text.

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

`ResultChapter`

object

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

`SeriesDetail`

object

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

`SeriesReference`

object

Nom	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.

Nom	Type	Description
`glossary`obligatoire	`SharedGlossaryDetail` \| null

`SeriesSummary`

object

Nom	Type	Description
`id`obligatoire	string	Identifier (UUID).
`name`obligatoire	string
`kind`obligatoire	string
`source_language`obligatoire	string \| null
`target_language`obligatoire	string \| null
`archived`obligatoire	boolean
`volumes`obligatoire	integer
`created_at`obligatoire	number	Unix time in seconds.
`updated_at`obligatoire	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).

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

`SharedGlossaryAttachment`

object

The shared glossary a series follows.

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

`SharedGlossaryDetail`

object

A shared glossary with its terms.

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

`SharedGlossaryInput`

object

A new shared glossary.

Nom	Type	Description
`name`obligatoire	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

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

`StageProgress`

object

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

`StoredResult`

object

The result file stored when the request ended successfully.

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

`TranslationPayload`

object

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

Nom	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`obligatoire	`SeriesReference`	The series: `id` (one you own) or `name`.
`volume`obligatoire	`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`obligatoire	string	BCP 47 tag such as `en`, `fr-FR`, `zh-Hant`. At most 35 characters.
`target_language`obligatoire	string	BCP 47 tag. At most 35 characters.
`chapters`obligatoire	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.

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

`ValidationIssue`

object

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

`VolumeReference`

object

Nom	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

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

`WebhookEvent`

object

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

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

`WebhookState`

object

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