Select pages
POST
/v1/projects/{id}/select-pages
Narrow a book down to just the page numbers you list — everything else is skipped and never charged. Call this after normalizing and before processing starts; once a batch has begun, this returns 409.
Authorizations
Bearer
JWT bearer token from POST /v1/auth/login.
Type
HTTP (bearer)
or
ApiKey
Scoped API key for non-interactive clients (issued by PBI #1426).
Type
API Key (header: X-Api-Key)
Parameters
Path Parameters
id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
One of
Request body for choosing which pages to translate (PBI #1386): the page numbers to keep.
The page numbers to keep; every other page is skipped and never charged.
Responses
OK
application/json
The top-level unit of work: one book (or set of screenshots) being translated page-by-page,
together with all of its pages and the state of the human-in-the-loop approval ladder.
Number of batches the system has processed and auto-confirmed. Starts at 0 (a brand-new project),
and the batch-size ladder reads directly from this value — see BatchPolicy.
Format
"int32"Pattern
"^-?(?:0|[1-9]\\d*)$"When the project was created (UTC).
Format
"date-time"The page IDs that make up the batch currently being processed. Empty when no batch is in flight.
The pipeline auto-confirms the round once its pages are processed (each PageStatus.Approved);
a page that fails is recorded as PageStatus.Failed and excluded so it stays retryable.
When this project becomes eligible for deletion (UTC) — DateTime TranslationProject.CreatedAtUtc plus the
retention window that applies for its current ProjectStatus TranslationProject.Status. A never-started draft
(bool RetentionPolicy.IsNeverStartedStatus(ProjectStatus status)) uses the shorter never-started window (PBI #2240);
once started it uses the normal window. Computed via RetentionPolicy, so it always agrees
with the policy and round-trips automatically; serialized onto the list/detail DTO so the UI can show a
retention notice. Read-only (no setter) — nothing persists it independently.
Format
"date-time"Stable identifier for this project.
Format
"uuid"Human-friendly project name (often the book title). Mutable so the owner can rename
a project after creation; the rename transition persists it through the store, which keeps the
promoted Name column and the jsonb payload in sync.
The user who owns this project (multi-tenancy). null for legacy / un-owned
projects (tests, the single-user filesystem store). When set, the API scopes every project
operation to the authenticated owner.
Format
"uuid"All pages of the book, in page order.
The length of the retention window in whole days that applies for the current ProjectStatus TranslationProject.Status,
surfaced alongside DateTime TranslationProject.ExpiresAtUtc so the UI can render "Kept N days · expires <date>"
without hard-coding the policy. Shorter for a never-started draft (PBI #2240).
Format
"int32"Pattern
"^-?(?:0|[1-9]\\d*)$"A project-wide correction of the source language (PBI #1368). When set it is the default source
language for pages that have no per-page string? BookPage.SourceLanguageOverride — applied
when a page is processed and as the fallback for display/translation. null when
per-page auto-detection stands. A per-page override always wins over this.
Durable object-storage key of the uploaded source (e.g.
uploads/{ownerId}/{uploadId}/book.pdf) when the project was created by uploading a file
through the browser rather than pointing at a server-side path. null for
legacy server-path projects. The normalize transition downloads this to the project's working
volume before rendering, so processing works on any instance without a shared filesystem.
Absolute or repo-relative path to the original input (a PDF, a folder of images, …).
Recorded for provenance and so a project can be re-normalized if needed. For projects created
from a browser upload this starts empty and the normalize transition fills it in with the local
working copy hydrated from string? TranslationProject.SourceObjectKey.
Size in bytes of the original uploaded source file, captured at creation time from the browser
upload, so the library dashboard can show "how big is this book" without re-reading the blob.
null for legacy / server-path projects whose size was never recorded.
Format
"int64"Pattern
"^-?(?:0|[1-9]\\d*)$"Where the project is in its overall lifecycle.
Valid values
"Created""Calibrating""Processing""PausedNeedsCredit""PausedNeedsCapacity""Complete""CompletedWithErrors""Failed""Cancelling""Cancelled"The language this project is translated into (PBI #1451) — a supported ISO-639 code from
SupportedLanguages, lower-cased. Chosen at creation (defaulting to the owner's
UserPreferences.DefaultTargetLanguageCode) and threaded through the translation stage so the
pipeline targets this language rather than a hardcoded English. Defaults to
string SupportedLanguages.Default (en), so a project created before this field existed
deserialises as English and no null ever reaches the pipeline.