API
Text recognition
Recognise the text on a scanned version and store a searchable PDF.
Recognition runs OCR over a version's pages and writes an invisible text layer, stored as a separate searchable PDF; the version itself is not replaced. Pages that already have text are skipped unless skipText is false. Asking again with the same file and options returns the job already made.
Poll ocr.get or jobs.get until status is done, then download with ocr.download. When nothing new was recognised, unchanged is true and there is no file. Each page that gains text costs 1 credit, taken when the job finishes. Recognition needs edit access to the document.
Recognise text on a version and store a searchable PDF
POST /documents/{documentId}/ocr ocr.request
Queues recognition, or returns the job already made or on its way for the same file and parameters (another version with the same bytes counts as the same file). Pages are 1-based; a range such as 1-3, 5 picks pages, and blank is every page. A page that already has text is skipped unless skipText is false. Each page that gains text costs one credit, taken when the job finishes.
The result is a separate PDF; the version itself is not replaced. Poll the job with ocr.get (or jobs.get), then download its file with ocr.download. Needs edit access to the document (403 forbidden). A document with no version is 409 nothing_to_recognise, an unknown version is 404 not_found, and a workspace whose credits are throttled is 402 credits_required.
- Scopes
documents.edit- Credits
- Spends credits: 1 credit per page recognised.
- Retries
- Safe with an
Idempotency-Key - MCP tool
ocr_request
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
version | integer | The number of the version to recognise. Default the document's current version. At least 1. |
params | object | Recognition options. Each left out takes its default. |
params.pages | string | Which pages, as a print-dialog range of 1-based pages such as 1-3, 5, 8-. Blank, the default, is every page. Matches ^(?:\s*\d{1,6}\s*(?:-\s*(?:\d{1,6}\s*)?)?(?:,|$))*$. At most 500 characters. Default ``. |
params.skipText | boolean | Leave alone a page that already has text that can be extracted. Default true. Default true. |
Response
202 Accepted. A JSON object:
Response fields (18)
| Name | Type | Description |
|---|---|---|
ocr | object | The recognition job: new, or the one already made or on its way. |
ocr.id | string | The recognition job's id, which is also its id for jobs.get. |
ocr.version | number | The number of the version recognised. Can be null. |
ocr.status | string | queued (waiting, also between retries), running, done or failed (for good; asking again retries it). One of queued, running, done, failed. |
ocr.params | map of anys | The options the job runs with, every default filled in. |
ocr.file | object | Once done, and only when text was written: the searchable PDF the download sends. Null otherwise. Can be null. |
ocr.file.name | string | The stored file's name. The download is named after the document. |
ocr.file.contentType | string | The file's media type: application/pdf. |
ocr.file.bytes | number | The file's size in bytes. |
ocr.file.pages | number | Pages in the PDF. |
ocr.recognised | number | Pages that gained a text layer. 0 until done. |
ocr.skipped | number | Pages left alone because they already had text. 0 until done. |
ocr.words | number | Words written. 0 until done. |
ocr.unchanged | boolean | True when the job is done and recognised nothing new, so there is no file. |
ocr.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. |
ocr.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. |
ocr.createdAt | number | When recognition was first asked for, epoch milliseconds. |
ocr.finishedAt | number | When it finished or failed for good, epoch milliseconds. Null until then. Can be null. |
Example request
curl -X POST https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/ocr \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"version": 1,
"params": {
"pages": "",
"skipText": true
}
}' Example response
{
"ocr": {
"id": "string",
"version": 1,
"status": "queued",
"params": {},
"file": {
"name": "Spring catalogue",
"contentType": "string",
"bytes": 1,
"pages": 1
},
"recognised": 1,
"skipped": 1,
"words": 1,
"unchanged": true,
"error": "string",
"errorCode": "source_missing",
"createdAt": 1767225600000,
"finishedAt": 1767225600000
}
} A document's recognition jobs, newest first
GET /documents/{documentId}/ocr ocr.list
The document's recognition jobs of every status, newest first, at most 50. There is no paging.
- Scopes
documents.edit- MCP tool
ocr_list
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (18)
| Name | Type | Description |
|---|---|---|
jobs | array of objects | The recognition jobs, newest first. |
jobs[].id | string | The recognition job's id, which is also its id for jobs.get. |
jobs[].version | number | The number of the version recognised. Can be null. |
jobs[].status | string | queued (waiting, also between retries), running, done or failed (for good; asking again retries it). One of queued, running, done, failed. |
jobs[].params | map of anys | The options the job runs with, every default filled in. |
jobs[].file | object | Once done, and only when text was written: the searchable PDF the download sends. Null otherwise. Can be null. |
jobs[].file.name | string | The stored file's name. The download is named after the document. |
jobs[].file.contentType | string | The file's media type: application/pdf. |
jobs[].file.bytes | number | The file's size in bytes. |
jobs[].file.pages | number | Pages in the PDF. |
jobs[].recognised | number | Pages that gained a text layer. 0 until done. |
jobs[].skipped | number | Pages left alone because they already had text. 0 until done. |
jobs[].words | number | Words written. 0 until done. |
jobs[].unchanged | boolean | True when the job is done and recognised nothing new, so there is no file. |
jobs[].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. |
jobs[].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. |
jobs[].createdAt | number | When recognition was first asked for, epoch milliseconds. |
jobs[].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/documents/doc_7m2kq9vx4c8d1r5t6wnb/ocr \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"jobs": [
{
"id": "string",
"version": 1,
"status": "queued",
"params": {},
"file": {
"name": "Spring catalogue",
"contentType": "string",
"bytes": 1,
"pages": 1
},
"recognised": 1,
"skipped": 1,
"words": 1,
"unchanged": true,
"error": "string",
"errorCode": "source_missing",
"createdAt": 1767225600000,
"finishedAt": 1767225600000
}
]
} A recognition job and how far it has got
GET /documents/{documentId}/ocr/{ocrId} ocr.get
Poll this until status is done, then download the file with ocr.download unless unchanged is true, or until it is failed. A job of another document, or an id that is not a recognition job, is 404 not_found.
- Scopes
documents.edit- MCP tool
ocr_get
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
ocrId required | string | The recognition job's id, from ocr.request or ocr.list. An id starting job_. |
Response
200 OK. A JSON object:
Response fields (18)
| Name | Type | Description |
|---|---|---|
ocr | object | The recognition job. |
ocr.id | string | The recognition job's id, which is also its id for jobs.get. |
ocr.version | number | The number of the version recognised. Can be null. |
ocr.status | string | queued (waiting, also between retries), running, done or failed (for good; asking again retries it). One of queued, running, done, failed. |
ocr.params | map of anys | The options the job runs with, every default filled in. |
ocr.file | object | Once done, and only when text was written: the searchable PDF the download sends. Null otherwise. Can be null. |
ocr.file.name | string | The stored file's name. The download is named after the document. |
ocr.file.contentType | string | The file's media type: application/pdf. |
ocr.file.bytes | number | The file's size in bytes. |
ocr.file.pages | number | Pages in the PDF. |
ocr.recognised | number | Pages that gained a text layer. 0 until done. |
ocr.skipped | number | Pages left alone because they already had text. 0 until done. |
ocr.words | number | Words written. 0 until done. |
ocr.unchanged | boolean | True when the job is done and recognised nothing new, so there is no file. |
ocr.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. |
ocr.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. |
ocr.createdAt | number | When recognition was first asked for, epoch milliseconds. |
ocr.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/documents/doc_7m2kq9vx4c8d1r5t6wnb/ocr/job_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"ocr": {
"id": "string",
"version": 1,
"status": "queued",
"params": {},
"file": {
"name": "Spring catalogue",
"contentType": "string",
"bytes": 1,
"pages": 1
},
"recognised": 1,
"skipped": 1,
"words": 1,
"unchanged": true,
"error": "string",
"errorCode": "source_missing",
"createdAt": 1767225600000,
"finishedAt": 1767225600000
}
} Download a searchable PDF from a finished recognition job
GET /documents/{documentId}/ocr/{ocrId}/file ocr.download
The searchable PDF, named after the document. 409 with code not_ready until the job is done (details.status says how it stands), 409 with code unchanged when recognition found nothing to add, and 410 gone when the file is no longer stored.
- Scopes
documents.edit
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
ocrId required | string | The recognition job's id, from ocr.request or ocr.list. An id starting job_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/ocr/job_7m2kq9vx4c8d1r5t6wnb/file \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 409 | nothing_to_recognise | The document has no version. |
| 409 | not_ready | Downloading before the job is done. |
| 409 | unchanged | Recognition found nothing to add, so there is no file. |
| 410 | gone | The file is no longer stored. |