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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
}
}