ContextOCR API documentation

Upload a PDF, image, or EML file and get JSON back with Mistral OCR 4-powered output in the markdown field plus usage details. ContextOCR is independent from Mistral AI and adds page boundaries, email body and attachments, visual context, plus QR/barcode types and decoded values.

Endpoint

POST https://api.contextocr.dev/v1/ocr

Auth

Authorization: Bearer ak_... or X-API-Key

Engine

Inputs

PDF, EML, JPG, PNG, GIF, BMP, TIFF, WebP

Speed

Most requests return in 2-4 seconds

Billing

1 credit per processed page

Quickstart

Upload a file

Use multipart uploads for normal file streams. Use JSON only when the file is already Base64 in your system.

Multipart upload

Best for backend services and direct file streams.

curl -X POST "https://api.contextocr.dev/v1/ocr" \
  -H "Authorization: Bearer ak_your_key" \
  -H "X-Request-ID: invoice-import-2026-05-27-001" \
  -F "[email protected]" \
  -F "mime_type=application/pdf"

Output

markdown

The API returns JSON. Read the markdown field from that JSON; its value is already the final OCR output.

Formatting

Useful invariants for chunking, indexing, and review.

The markdown field is a normal JSON string. After JSON parsing, use that string directly.
PDFs and images start with the filename, then a source heading, then page sections.
Emails start with the subject when available. The email body and each attachment get their own source section.
Each page begins with ### Page n so you can split, index, cite, or chunk pages predictably.
Tables, visual notes, image labels, signatures, stamps, and decoded QR codes or barcodes are placed near the content they describe.
Repeated barcode values on the same page are deduplicated.

Example shape

Email body, attachment pages, tables, and barcodes in one OCR output string.

# Email: Order confirmation

## Email Body

### Page 1

Thanks for your order...

#### Decoded QR Codes and Barcodes

Barcode type: QR_CODE
Decoded value: `https://contextocr.dev/track/123`

## Attachment 1: invoice.pdf

### Page 1

| Item | Total |
| --- | ---: |
| Subscription | $49.00 |

Response

JSON response shape

A successful request returns the markdown field, request_id, and usage metadata.

200 OK

JSON response. The markdown field is escaped because it is a JSON string.

{
  "markdown": "# document.pdf\n\n## Source: document.pdf\n\n### Page 1\n\n...",
  "request_id": "invoice-import-2026-05-27-001",
  "usage": {
    "usage_event_id": "usage_event_123",
    "pages": 3,
    "charged_credits": 3,
    "remaining_credits": 97
  }
}

Inputs

Supported files and limits

These are the current upload, rate, and processing limits.

File support

Set mime_type when you know it; otherwise the API detects the file type.

Family	Extensions	Notes
PDF	.pdf	Multi-page OCR with tables, images, and QR/barcode decoding.
Email	.eml	Processes the email body and supported attachments. HTML emails are rendered for OCR.
Images	.jpg, .jpeg, .png, .gif, .bmp, .tiff, .tif, .webp	Single-image OCR with image annotations plus QR/barcode type and value extraction.

Request details

Headers and body formats

Mostly standard file upload mechanics. X-Request-ID is useful for tracing but is not an idempotency key.

Item	Details
multipart/form-data	Send one file field named file. Optional mime_type.
application/json	Send file_content as Base64, required filename, optional mime_type.
filename	Required for JSON uploads. Limited to 255 characters.
X-Request-ID	Optional trace ID echoed in the response body and X-Request-ID response header.
Response headers	X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.

Errors

Error handling

Error responses use a stable envelope. Retry 429 after Retry-After. Retry 5xx with backoff. Do not retry 400/401/402/403 without changing the request, key, or balance.

Error envelope

{
  "error": {
    "code": "insufficient_usage_balance",
    "message": "Not enough credits. Add credits to continue.",
    "request_id": "invoice-import-2026-05-27-001"
  }
}

HTTP status

Status	Meaning
400	Malformed upload or request body. Fix before retrying.
401	Missing or invalid API key.
402	Not enough credits for the document page count.
403	Revoked API key.
413	Upload or processed output is too large.
429	Rate limited. Retry after Retry-After.
502, 503, 504	Transient OCR failure or timeout. Retry with backoff.

Versioning

Changelog

Documentation version history for this API reference.

Version	Date	Notes
v1.0.0	2026-06-19	Initial documentation for POST /v1/ocr, including auth, uploads, OCR output, limits, errors, and retry guidance.

curl -X POST "https://api.contextocr.dev/v1/ocr" \ -H "Authorization: Bearer ak_your_key" \ -H "X-Request-ID: invoice-import-2026-05-27-001" \ -F "[email protected]" \ -F "mime_type=application/pdf"

# Email: Order confirmation ## Email Body ### Page 1 Thanks for your order... #### Decoded QR Codes and Barcodes Barcode type: QR_CODE Decoded value: `https://contextocr.dev/track/123` ## Attachment 1: invoice.pdf ### Page 1 | Item | Total | | --- | ---: | | Subscription | $49.00 |

{ "markdown": "# document.pdf\n\n## Source: document.pdf\n\n### Page 1\n\n...", "request_id": "invoice-import-2026-05-27-001", "usage": { "usage_event_id": "usage_event_123", "pages": 3, "charged_credits": 3, "remaining_credits": 97 } }

Family

Extensions

Notes

PDF

.pdf

Multi-page OCR with tables, images, and QR/barcode decoding.

.eml

Processes the email body and supported attachments. HTML emails are rendered for OCR.

Images

.jpg, .jpeg, .png, .gif, .bmp, .tiff, .tif, .webp

Single-image OCR with image annotations plus QR/barcode type and value extraction.

Item

Details

multipart/form-data

Send one file field named file. Optional mime_type.

application/json

Send file_content as Base64, required filename, optional mime_type.

filename

Required for JSON uploads. Limited to 255 characters.

X-Request-ID

Optional trace ID echoed in the response body and X-Request-ID response header.

Response headers

X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.

Status

Meaning

400

Malformed upload or request body. Fix before retrying.

401

Missing or invalid API key.

402

Not enough credits for the document page count.

403

Revoked API key.

413

Upload or processed output is too large.

429

Rate limited. Retry after Retry-After.

502, 503, 504

Transient OCR failure or timeout. Retry with backoff.

Version

Date

Notes

v1.0.0

2026-06-19

Initial documentation for POST /v1/ocr, including auth, uploads, OCR output, limits, errors, and retry guidance.