Libris
Français

Automation API

Send a book, get it back translated.

The automation API lets a script or another server hand books to Libris with no step in the web interface. The whole pipeline runs on its own, under the autopilot, and every request ends with a result or a stated reason.

Read the API guide on GitHub Install

The principle

  1. Create a token

    In My account › API tokens, pick only the scopes the script needs. The secret is shown once.

  2. Send the book

    POST /api/v1/translation-requests takes an EPUB, one or more TXT chapters, or a JSON document. Libris answers 202 Accepted at once.

  3. Follow it

    Poll the status with ?wait= to hold the call until the request ends, or let a signed webhook tell you.

  4. Get the result

    The translated EPUB for an EPUB, validated with EPUBCheck, or JSON, text or a ZIP of chapters, with the completion report.

A complete example

Upload an EPUB, wait for the end, then download the translated book and read the report. The script expects LIBRIS_URL, LIBRIS_TOKEN and PROVIDER_ID in the environment, and uses curl and jq. It is taken as is from the API guide.

bash 
#!/usr/bin/env bash
set -euo pipefail

REQUEST_ID=$(curl -sS -X POST "$LIBRIS_URL/api/v1/translation-requests" \
  -H "Authorization: Bearer $LIBRIS_TOKEN" \
  -H "Idempotency-Key: book-fr-1" \
  -F "file=@book.epub" -F target_language=fr -F provider_id="$PROVIDER_ID" \
  | jq -r .request_id)

while :; do   # each call answers when the request ends, or after 60 seconds
  STATUS=$(curl -sS "$LIBRIS_URL/api/v1/translation-requests/$REQUEST_ID?wait=60" \
    -H "Authorization: Bearer $LIBRIS_TOKEN" | jq -r .status)
  case "$STATUS" in completed|completed_with_residuals|failed|cancelled) break ;; esac
done
echo "Request ended: $STATUS"

if [ "$STATUS" = completed ] || [ "$STATUS" = completed_with_residuals ]; then
  curl -sS "$LIBRIS_URL/api/v1/translation-requests/$REQUEST_ID/result" \
    -H "Authorization: Bearer $LIBRIS_TOKEN" -o book.fr.epub
fi
curl -sS "$LIBRIS_URL/api/v1/translation-requests/$REQUEST_ID" \
  -H "Authorization: Bearer $LIBRIS_TOKEN" | jq '.report | {outcome, residual_total, usage}'

Built for scripts that run unattended

  • Scoped tokens

    Six scopes, from series:read to results:read, with optional expiry and immediate revocation. Tokens are stored as SHA-256 hashes and rate-limited per token.

  • Idempotent requests

    An Idempotency-Key header makes a retried upload return the first request instead of creating a second one.

  • A request always ends

    Every request finishes as completed, completed_with_residuals, failed with a reason, or cancelled. None stays running forever.

  • Signed webhooks

    HMAC-SHA256 signatures, allow-listed hosts only, no private addresses unless you allow them, and bounded retries.

  • A report with every result

    Passage states, passages kept in the original with their reason, costs, durations, and the import and autopilot decisions.

  • Separate from the interface

    /api/v1 only accepts API tokens, and a token never opens the interface's routes.

Endpoints

Method and pathScopePurpose
POST /api/v1/translation-requests content:write (+ pipeline:start) Send an EPUB, TXT chapters or a JSON document
GET /api/v1/translation-requests/{id} jobs:read Status, progress and report (?wait= to long-poll)
POST …/{id}/pause · …/resume · …/cancel jobs:control Pause, resume or cancel the request's job
GET /api/v1/translation-requests/{id}/result results:read Download the result (EPUB, JSON, TXT or ZIP)
GET /api/v1/series · /api/v1/series/{id} series:read List your series, or one series and its volumes

The full reference

Request options, the JSON document format, status and report fields, webhook verification, errors and limits are all in the API guide.

Read the API guide on GitHub