OCR API reference: endpoints, fields, error codes

Every endpoint, generated from the API specification. Parameters, bodies, responses and fields on this page are read from the same OpenAPI file you can download here.

Examples read the host from the environment. Hosted service: export OCR_BASE=https://api.ocr-software.com; your own server: export OCR_BASE=http://127.0.0.1:8080. A call marked “Key” needs Authorization: Bearer ocr_...; put your key in OCR_KEY. “No key” calls need none.

Every call can also answer 429 rate_limited or 503 with Retry-After: wait that long, then retry.

Download openapi.json

Let your agent set it up

One Markdown file holds the same API in text an agent reads. Agent guide · This page as Markdown · llms.txt

Service

GET /

Entry point

Authentication: none, open without an API key.

Fixed pointers to the public routes and how to get a key; no data of its own, no key needed. Links are absolute when the server knows its public address, else relative.

Responses

200 application/json

Example

curl -s "$OCR_BASE/"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/"
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /healthz

Liveness

Authentication: none, open without an API key.

Responses

200 application/json

Example

curl -s "$OCR_BASE/healthz"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/healthz"
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/status

Load of the service (public, no key)

Authentication: none, open without an API key.

How busy the service is and how long a new page waits, per class. Only counts and seconds; it names no key, job, address or file name. The wait uses the same estimate as queue in a job status. Limited per client address; Retry-After says when to retry.

Responses

200 application/json

Example

curl -s "$OCR_BASE/v1/status"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/status"
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /openapi.json

This specification

Authentication: none, open without an API key.

Responses

Example

curl -s "$OCR_BASE/openapi.json"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/openapi.json"
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

Pipelines and usage

GET /v1/catalog

What the service offers (public, no key)

Authentication: none, open without an API key.

Pipelines with description, capabilities, formats, features and price per page, plus the query parameters of POST /v1/jobs. The same registry as GET /v1/pipelines, the same for everyone, cached for a minute. It names no host, revision, load or worker; a pipeline that cannot run right now has available false and one generic note. Limited per client address; Retry-After says when to retry.

In the guide

Responses

200 application/json

Example

curl -s "$OCR_BASE/v1/catalog"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/catalog"
req = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/pipelines

List pipelines with factor, price and capabilities

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Responses

200 application/json

Example

curl -s "$OCR_BASE/v1/pipelines" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/pipelines"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/pipelines/{ref}

One pipeline

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Responses

Example

curl -s "$OCR_BASE/v1/pipelines/$REF" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

REF = "..."  # the ref of your call
url = os.environ["OCR_BASE"] + f"/v1/pipelines/{REF}"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/usage

Pages used by this key

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Responses

Example

curl -s "$OCR_BASE/v1/usage" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/usage"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

Jobs

GET /v1/jobs

List the jobs of the calling key, newest first, in pages. Filter with client_ref and status; continue with next_cursor.

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Responses

Example

curl -s "$OCR_BASE/v1/jobs" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/jobs"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

POST /v1/jobs

Submit a document (request body = the file: PDF, PNG, JPEG or TIFF; each TIFF directory is one page). With dry_run=1 only the exact price is returned. Send an Idempotency-Key header to make a retry safe: the same key with the same document and parameters within 24 hours returns the existing job (200, header Idempotent-Replayed: true) and charges nothing again.

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Request body application/pdf: the file itself

Request body image/png: the file itself

Request body image/jpeg: the file itself

Request body image/tiff: the file itself

Responses

Example

curl -s -X POST "$OCR_BASE/v1/jobs?pipeline=scan-ctc@2&job_budget=5000" \
  -H "Authorization: Bearer $OCR_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @file.pdf

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/jobs?pipeline=scan-ctc@2&job_budget=5000"
req = urllib.request.Request(url, data=open("file.pdf", "rb").read(), method="POST", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"], "Content-Type": "application/pdf"})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/jobs/{id}

State and counts of a job

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Responses

Example

curl -s "$OCR_BASE/v1/jobs/$ID?wait=30" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

ID = "..."  # the id of your call
url = os.environ["OCR_BASE"] + f"/v1/jobs/{ID}?wait=30"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

DELETE /v1/jobs/{id}

Delete the stored result of a finished job now instead of after result_ttl (24 h by default). The job state and its counts stay readable; the bookings stay. Repeating the call is fine. A job that still runs is cancelled instead (202): its open pages end as not_run (counted in pages_not_run), finished pages stay booked, nothing more is charged, and the job ends with stop cancelled.

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Responses

Example

curl -s -X DELETE "$OCR_BASE/v1/jobs/$ID" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

ID = "..."  # the id of your call
url = os.environ["OCR_BASE"] + f"/v1/jobs/{ID}"
req = urllib.request.Request(url, method="DELETE", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/jobs/{id}/report

Job report: how the pages of a job were read. Kept as long as the result (result_ttl).

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

Names the pipeline file by its hash, shows every value of that file that changes the result (params, as the worker received them, with the render dpi the job chose), the model_rev the worker reported and the seconds per stage. Works for a running job (the pages read so far) and a finished one. It holds numbers, codes and hashes only, never text or file names.

Parameters

Responses

Example

curl -s "$OCR_BASE/v1/jobs/$ID/report" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

ID = "..."  # the id of your call
url = os.environ["OCR_BASE"] + f"/v1/jobs/{ID}/report"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/jobs/{id}/result

Result of a finished job. Results are kept for a limited time (result_ttl).

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Responses

Example

curl -s "$OCR_BASE/v1/jobs/$ID/result?format=json" \
  -H "Authorization: Bearer $OCR_KEY" \
  -o response.out

import os, urllib.request

ID = "..."  # the id of your call
url = os.environ["OCR_BASE"] + f"/v1/jobs/{ID}/result?format=json"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    open("response.out", "wb").write(r.read())

POST /v1/jobs/{id}/result

Searchable PDF of a finished job. The body is the original document (the service does not keep it); the invisible text layer is placed at the level of the pipeline (words or lines). Nothing is stored.

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Request body application/octet-stream: the file itself

Responses

Example

curl -s -X POST "$OCR_BASE/v1/jobs/$ID/result?format=pdf" \
  -H "Authorization: Bearer $OCR_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @body.json \
  -o response.out

import os, urllib.request

ID = "..."  # the id of your call
url = os.environ["OCR_BASE"] + f"/v1/jobs/{ID}/result?format=pdf"
req = urllib.request.Request(url, data=open("body.json", "rb").read(), method="POST", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"], "Content-Type": "application/octet-stream"})
with urllib.request.urlopen(req) as r:
    open("response.out", "wb").write(r.read())

Bucket jobs

POST /v1/bucket-jobs

Start a job over an S3 bucket: every PDF under source.prefix is recognized, results and manifest.json are written under destination.prefix. The same job_id again resumes. Credentials live in RAM only.

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Request body application/json: object

Responses

202 application/json

Example

curl -s -X POST "$OCR_BASE/v1/bucket-jobs" \
  -H "Authorization: Bearer $OCR_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

import os, urllib.request

url = os.environ["OCR_BASE"] + f"/v1/bucket-jobs"
req = urllib.request.Request(url, data=open("body.json", "rb").read(), method="POST", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"], "Content-Type": "application/json"})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

GET /v1/bucket-jobs/{id}

State and counts of a bucket job (no names)

Authentication: API key in the header Authorization: Bearer $OCR_KEY.

In the guide

Parameters

Responses

Example

curl -s "$OCR_BASE/v1/bucket-jobs/$ID?wait=30" \
  -H "Authorization: Bearer $OCR_KEY"

import os, urllib.request

ID = "..."  # the id of your call
url = os.environ["OCR_BASE"] + f"/v1/bucket-jobs/{ID}?wait=30"
req = urllib.request.Request(url, method="GET", headers={"Authorization": "Bearer " + os.environ["OCR_KEY"]})
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

Objects

The named objects that the calls above return or accept.

Pipeline

Usage

DryRun

DryRunWarning

JobAccepted

JobCancelling

Answer of DELETE on a job that still runs. state is cancelling only here; GET /v1/jobs/{id} shows running until the job has ended, then done.

JobReport

JobReportPages

JobStatus

JobList

QueueInfo

Where a running job stands among all jobs waiting for the OCR machine. Paid jobs run before free ones, jobs of different customers take turns, small backlogs go first. The job keeps running while it waits; the numbers change as other jobs come and go.

BucketJobStatus

Result

ResultBox

ResultCell

ResultLine

ResultModel_run

ResultPage

ResultPage_error

ResultRegion

ResultTable

ResultWarning

ResultWord

Errors

Every error is JSON {"error":{"code","message"}}. Branch on code, not on message.