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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Response

200 OK. A JSON object:

Response fields (18)
NameTypeDescription
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

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
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:

StatusCodeWhen
409nothing_to_recogniseThe document has no version.
409not_readyDownloading before the job is done.
409unchangedRecognition found nothing to add, so there is no file.
410goneThe file is no longer stored.