API

REST API guide

The PDF Extractor API accepts PDF uploads as multipart form data and returns detected element metadata plus download URLs or inline file data. Use the interactive API reference for complete request and response schemas.

Create and protect a token

1. Sign in and open API Tokens.
2. Create a named token.
3. Copy it immediately. The full value is shown once.
4. Store it in a secret manager or environment variable, not in source code.

Tokens begin with pdf-ext_. Examples in this guide use YOUR_TOKEN; never paste a real token into a public issue, screenshot, or repository. Revoke an exposed token from the Tokens page.

Basic request

curl -X POST 'https://pdf-xtract.com/api/extract-elements' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'File=@document.pdf;type=application/pdf' \
  -F 'Categories=Image,Table' \
  -F 'PageRange=1-10' \
  -F 'StoreFile=false'

StoreFile=false returns file data in the response for immediate handling. StoreFile=true stores results temporarily and returns URLs that expire under the account's retention rules.

Common form fields

Field	Values and behavior
File	Required PDF upload
Categories	Repeated fields or a comma-separated list; defaults to Image
PageRange	Range such as 1-10 or list such as 1,2,5; default covers pages 1–2000
ImageResolution	10–800 DPI; default 200
ImageOutputFormat	default, jpg, png, or tiff
MinimumImageWidth / MinimumImageHeight	0–1000 pixels; default 10
confidence_threshold	0–1; default 0.15
iou_threshold	0–1; default 0.45
Timeout	10–1200 seconds; default 600
Password	Password for a protected PDF
StoreFile	false for inline data or true for temporary stored URLs
OcrMode	none, element, or page
OcrLanguage	Tesseract language code such as eng, fra, or deu
OcrEngine	tesseract or advanced; advanced OCR requires page mode
OcrOutputFormat	text, markdown, or json; Tesseract supports text
ExtractTables	true to transcribe detected Table regions with the advanced engine
TableFormat	markdown, html, or csv when table extraction is enabled

The category values are Caption, Footnote, Expression, Entry, Footer, Header, Image, SectionTitle, Table, Text, and Title. API values use SectionTitle without a space.

OCR request

Advanced OCR operates on whole pages:

curl -X POST 'https://pdf-xtract.com/api/extract-elements' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'File=@scan.pdf;type=application/pdf' \
  -F 'Categories=Image,Text' \
  -F 'OcrMode=page' \
  -F 'OcrEngine=advanced' \
  -F 'OcrOutputFormat=markdown' \
  -F 'StoreFile=true'

OCR, advanced OCR, structured tables, and batch extraction depend on the account plan and service configuration. The API returns an error when a requested capability is unavailable.

Batch extraction and saved jobs

• POST /api/extract-elements/batch processes multiple PDFs and requires the Business plan.
• GET /api/extractions lists saved extraction records.
• GET /api/extractions/{extraction_id} returns one saved extraction.
• DELETE /api/extractions/{extraction_id} deletes an extraction record and its managed files.

The interactive API reference is authoritative for filters, pagination, response fields, and file-content endpoints.

Error checklist

Status	First checks
400	Form field names and values, page range, password, advanced OCR page mode
401	Bearer header, token spelling, token status
403	Monthly allowance and plan access for OCR or batch features
415	File extension and PDF content type
500	Retry a smaller page range and record the sanitized response body
503	Advanced OCR or another server-side dependency may be temporarily unavailable

Do not retry an authentication or validation error in a tight loop. Correct the request first. For server failures, use exponential backoff and an idempotent client workflow that can recognize a completed extraction.

Get help or request API features

Report a reproducible API bug or request an API enhancement. Include the endpoint, status code, sanitized response, and a minimal request with the token removed.

GitHub Issues are public. Do not upload the source PDF or reveal the bearer token, document content, personal information, or billing details. Use private support when the request or document cannot be safely sanitized.

Last reviewed: August 21, 2026.