Document extraction API

POST a PDF or image, get back structured JSON. No templates, no model training, no per-vendor setup.

Quick start

curl -X POST https://extractfox.com/api/v1/extractions \
  -H "Authorization: Bearer $EXTRACTFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "prebuilt",
    "schema_id": "invoice",
    "file": { "data": "'"$(base64 -i invoice.pdf)"'", "media_type": "application/pdf" }
  }'

# Response
{
  "id": "job_4f9c2a1b8d7e6f5a4b3c2d1e",
  "object": "extraction",
  "status": "succeeded",
  "result": {
    "vendor": "Acme Supplies Ltd.",
    "invoice_number": "INV-00284",
    "issue_date": "2026-04-12",
    "line_items": [...],
    "total": 278.40
  },
  "quota": { "used": 12, "limit": 300, "remaining": 288 }
}

Full contract: OpenAPI 3.1 document.

Your API keys

A key authenticates both the REST API and the MCP server, and spends the quota of the account that created it. A key is shown once, at creation.

Endpoints

POST/api/v1/extractions

Run an extraction and get the JSON object back. Add async: true to get a job id immediately and poll for the result.

JSON: mode (prebuilt|custom), schema_id or prompt, and one of file (base64), url, text

GET/api/v1/extractions/{id}

Fetch an extraction you already ran, so a lost response doesn't cost a second run. Results are kept for 7 days.

—

GET/api/v1/extractions

Your most recent extractions, newest first.

?limit=20

GET/api/v1/schemas

The prebuilt schemas with their JSON Schema. Public — no key needed.

—

GET/api/v1/me

Plan, tier and how many extractions are left this period.

—

POST/api/mcp

MCP server: extract_document, list_schemas, get_extraction, get_account_usage.

JSON-RPC 2.0 over Streamable HTTP

Use it from an AI agent

ExtractFox speaks MCP over Streamable HTTP, so an agent can extract documents itself. Point any MCP client at the endpoint with your key:

{
  "mcpServers": {
    "extractfox": {
      "url": "https://extractfox.com/api/mcp",
      "headers": { "Authorization": "Bearer $EXTRACTFOX_API_KEY" }
    }
  }
}

Tools: extract_document, list_schemas, get_extraction, get_account_usage. Only extraction spends quota.

Limits

Rate: 60 extraction calls a minute per IP, 4 in flight.
Inline files: 3 MB of base64 in one request body.
Linked files: Pass url instead: PDFs up to 50 MB, images up to 20 MB, fetched as files.
Pasted text: 200,000 characters.
Quota: One unit per successful extraction. Empty results are refunded automatically.

Errors

Every failure returns the same envelope, so you can branch on error.code rather than parse prose. Quote request_id when you ask us about one.

{
  "error": {
    "type": "quota_error",
    "code": "quota_exhausted",
    "message": "Monthly extraction quota used up. Upgrade to a higher plan or wait for next month."
  },
  "request_id": "req_2f8a1c0b9d7e6f5a4b3c2d1e"
}

400: invalid_request — a field is missing, unknown, or the wrong shape.
401: missing_api_key / invalid_api_key — no key, or a revoked one.
402: quota_exhausted — the monthly quota is used up.
413: payload_too_large — the file or text is over the limit.
415: unsupported_media_type — send PDF, PNG, JPEG, WEBP, HEIC or HEIF.
429: rate_limited — back off and retry after Retry-After seconds.
504: timeout — the document took too long; split it into fewer pages.

Product APIs

Dedicated docs for high-volume document types — curl examples, response schemas, and error codes:

Invoice OCR API — Invoice OCR API: POST a PDF or scan with a bearer API key, get vendor, line_item…
Resume parser API — Resume parser API: POST a CV PDF with a bearer API key, get contact, experience,…

Schemas

Six prebuilt schemas ship out of the box: invoice, receipt, passport, bank_statement, contract, resume. Pass schema_id with one of these to get the canonical extraction.

For anything else, pass mode=custom with a free-text prompt describing what you want.

Frequently asked questions

Is there a document extraction API I can call?+

Yes. POST /api/v1/extractions with an API key extracts one document and returns the JSON. The same account quota applies whether you call the API, the MCP server, or use the web app.

How do I authenticate?+

Create a key on this page while signed in, then send it as Authorization: Bearer efk_live_.... Keys are shown once and stored only as a hash, so keep a copy when you create one. Revoke a key here and it stops working immediately.

What's the latency per extraction?+

Typical latency is 2–6 seconds for a single PDF or image, dominated by the model call. Larger documents and multi-page scans take longer. Pass async: true if you would rather poll than hold a connection open.

Can I use the API to bulk-process documents?+

Yes. Loop with a sensible concurrency cap (3–5 in flight, 60 calls a minute) and keep the returned extraction ids, so a lost response can be fetched again instead of re-run.

Does the API support custom schemas?+

Yes. Pass mode=custom with a prompt and the server infers a schema from the document before extracting. GET /api/v1/schemas returns the prebuilt schemas as JSON Schema.

How do I send larger PDFs?+

Inline base64 is capped at 3 MB because the hosting platform rejects bigger request bodies. Host the file and pass its url instead — linked PDFs up to 50 MB and images up to 20 MB are fetched and extracted as files, not scraped as text.

Can an AI agent use ExtractFox directly?+

Yes. /api/mcp is an MCP server over Streamable HTTP: point any MCP client at it with the same Bearer key and the agent gets extract_document, list_schemas, get_extraction and get_account_usage.

How long do you keep extracted data?+

Extraction results are readable for 7 days so a lost response can be recovered, then the stored result is deleted. The job record (id, status, timestamps) is kept for accounting.

Use the API

See pricing