API

Jobs

Follow the background work on a document.

Background work on a document runs as engine jobs: thumbnails and page counts, exports, recognition, and a publication's pages. An export's id and a recognition job's id are job ids, so jobs.get can follow either without knowing which it is.

A job is queued, then running, then done or failed. A failed try is retried after a delay and goes back to queued; attempts counts the tries, and failed is final. A failed job says why in errorCode, a stable code, and error, a sentence for people: the codes are the document.processed webhook event's, and cancelled for a job Flipbird support cancelled. The job says how it stands, not what it made: fetch the result from the export or the recognition job. The document.processed webhook event is sent as each job finishes or fails for good.

A job and how far it has got

GET /jobs/{jobId} jobs.get

Any engine job on a document you can see: an export's or an OCR run's id is its job id. Poll until status is done or failed, then fetch the result from the resource that started it (exports.get, ocr.get). A job on a document you cannot see, on a document in the trash, or with no document, is 404 not_found.

Scopes
documents.read
MCP tool
job_status

Path parameters

NameTypeDescription
jobId required string The job's id: an export's or a recognition job's id is its job id. An id starting job_.

Response

200 OK. A JSON object:

Response fields (12)
NameTypeDescription
job object The job.
job.id string The job's id.
job.type string What the job makes: thumbnail (a version's first-page thumbnail and page count), export-svg, export-images, export-flipbook and export-offline (exports), ocr (recognised text), viewer-pages, viewer-pdf and tiles (a publication's pages, download copy and deep-zoom tiles), and font-subset (a workspace font cut down for an export). One of thumbnail, tiles, export-svg, export-flipbook, export-images, export-offline, viewer-pages, viewer-pdf, ocr, pdfa, font-subset, purge-tenant.
job.documentId string The document it works on.
job.version number The number of the version it works on. Can be null.
job.status string queued (waiting, also between retries), running, done, or failed for good. One of queued, running, done, failed.
job.attempts number Tries so far, including one running now.
job.error string Why it failed, in a sentence for people, when status is failed; null otherwise. It may change: switch on errorCode. Can be null.
job.errorCode string Why it failed, as a stable code, when status is failed; null otherwise. source_missing: the version's stored file is gone. engine_error: the engine could not process this document. gave_up: it did not finish after every attempt. cancelled: Flipbird support cancelled it. job_failed: any other failure. The document.processed webhook event uses the same codes, except cancelled, which it never carries. One of source_missing, engine_error, gave_up, job_failed, cancelled. Can be null.
job.createdAt number When the job was first queued, epoch milliseconds.
job.startedAt number When its latest try started, epoch milliseconds. Null until one has. Can be null.
job.finishedAt number When it finished or failed for good, epoch milliseconds. Null until then. Can be null.

Example request

curl https://api.flipbird.io/api/v1/jobs/job_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "job": {
    "id": "string",
    "type": "thumbnail",
    "documentId": "…",
    "version": 1,
    "status": "queued",
    "attempts": 1,
    "error": "string",
    "errorCode": "source_missing",
    "createdAt": 1767225600000,
    "startedAt": 1767225600000,
    "finishedAt": 1767225600000
  }
}