OkraPDF

Upload a PDF, get an API. Extract tables, ask questions, get structured JSON — via MCP, CLI, or HTTP.

Designed for subagents. Every document is its own stateless endpoint. Fire off parallel queries to different documents — no shared state, no locks, no ordering issues. Ideal as a tool inside agent loops (Claude, GPT, custom orchestrators).

Setup

MCP (Claude Code, Cursor, OpenCode)

Add to ~/.claude/mcp.json or .cursor/mcp.json:

CODEBLOCK0

CLI

CODEBLOCK1

HTTP

All endpoints use https://api.okrapdf.com with header Authorization: Bearer $OKRA_API_KEY.

Get a free API key at okrapdf.com (Settings > API Keys).

---

Upload a PDF

CLI

CODEBLOCK2

Options: -o json|markdown|table, --processor, --tables-only, --text-only, -d <dir> (agentic workspace), -q (quiet, for piping)

MCP

CODEBLOCK3

Parameters: url (required), wait (default: true), document_id (optional), page_images (none/cover/lazy), INLINECODE17

HTTP

CODEBLOCK4

Response: {"document_id": "doc-abc123", "phase": "extracting", "pages_total": 42}

---

Check Status

CLI

CODEBLOCK5

MCP

CODEBLOCK6

HTTP

CODEBLOCK7

Response: INLINECODE19

Documents must reach phase: "complete" before reading/asking. Use wait: true on upload (MCP) or poll status.

---

Read Content

CLI

CODEBLOCK8

MCP

CODEBLOCK9

INLINECODE22 accepts: doc-abc123, arxiv:2307.09288, or https://arxiv.org/pdf/2307.09288.

HTTP

# Full markdown
curl https://api.okrapdf.com/v1/documents/doc-abc123/full.md \
  -H "Authorization: Bearer $OKRA_API_KEY"

# Specific page
curl "https://api.okrapdf.com/v1/documents/doc-abc123/pages/3" \
  -H "Authorization: Bearer $OKRA_API_KEY"

# All pages as JSON
curl https://api.okrapdf.com/v1/documents/doc-abc123/pages \
  -H "Authorization: Bearer $OKRA_API_KEY"

---

Ask Questions

CLI

CODEBLOCK11

MCP

CODEBLOCK12

Returns answer with page citations (page number + supporting snippet).

HTTP (OpenAI-compatible)

CODEBLOCK13

Supports "stream": true for SSE streaming.

---

Extract Structured Data

CLI

CODEBLOCK14

MCP

CODEBLOCK15

HTTP

curl -X POST https://api.okrapdf.com/document/doc-abc123/chat/completions \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Extract all line items"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "invoice",
        "schema": {
          "type": "object",
          "properties": {
            "line_items": {"type": "array", "items": {"type": "object", "properties": {"description": {"type": "string"}, "amount": {"type": "number"}}}},
            "total": {"type": "number"}
          }
        },
        "strict": true
      }
    },
    "stream": false
  }'

---

Tables and Entities

CLI

CODEBLOCK17

HTTP

curl https://api.okrapdf.com/v1/documents/doc-abc123/entities/tables \
  -H "Authorization: Bearer $OKRA_API_KEY"

curl https://api.okrapdf.com/v1/documents/doc-abc123/entities \
  -H "Authorization: Bearer $OKRA_API_KEY"

---

Collections

Group documents and query across all of them at once.

Create and manage

CLI:
CODEBLOCK19

HTTP:
CODEBLOCK20

Query across documents

Two modes:

Mode	Behavior	Best for
INLINECODE27 (default)	Separate completion per document, NDJSON stream	Per-document answers
INLINECODE28

Single LLM with grep/Python over all docs | Cross-doc search, comparisons |

CLI:
CODEBLOCK21

HTTP (fanout):
CODEBLOCK22

Response (NDJSON):
CODEBLOCK23

HTTP (sandbox):
CODEBLOCK24

Export

# NDJSON stream
curl -N "https://api.okrapdf.com/v1/collections/col-xxx/export?format=markdown" \
  -H "Authorization: Bearer $OKRA_API_KEY"

# Zip archive
curl -L "https://api.okrapdf.com/v1/collections/col-xxx/export?format=zip" \
  -H "Authorization: Bearer $OKRA_API_KEY" -o collection.zip

---

Exports

CODEBLOCK26

---

Page Images

Deterministic, CDN-cached URLs:

CODEBLOCK27

---

Document Management

CLI

CODEBLOCK28

HTTP

curl "https://api.okrapdf.com/v1/documents?limit=20" -H "Authorization: Bearer $OKRA_API_KEY"

---

Subagent & Parallel Patterns

OkraPDF is built for agent-to-agent use. Each document is an isolated Durable Object with its own SQLite — queries to different documents never contend. Run them in parallel freely.

As tools inside an agent loop

Map each document to a callable tool. The orchestrating agent picks which docs to query:

CODEBLOCK30

Fan-out: same question across N documents

CODEBLOCK31

CODEBLOCK32

CODEBLOCK33

MCP subagent pattern (Claude Code)

When Claude Code spawns subagents, each can independently call OkraPDF MCP tools:

CODEBLOCK34

When to use which pattern

Pattern	Best for
MCP tools	Agent picks which docs to query dynamically
SDK Promise.all

You know the doc set upfront, want max parallelism | | Collections query | Same question across a predefined group, server handles fan-out | | okra chat --doc | Quick CLI comparison of 2-5 docs |

---

Piping and Scripting

CODEBLOCK35

---

Available Processors

Processor	Best For	Speed
textlayer	Native PDFs with selectable text	Fast
llamaparse

Complex layouts, mixed content | Medium |
| unstructured | General purpose | Medium |
| azure-di | Forms, invoices, receipts | Medium |
| docai | High-accuracy OCR | Slow |
| gemini | Vision-based extraction | Medium |
| qwen | Open-source VLM extraction | Medium |

---

Error Codes

Status	Meaning
202	Accepted, processing async
400

Bad request |
| 401 | Missing or invalid API key |
| 404 | Document not found |
| 409 | Conflict (document exists) |
| 429 | Rate limited |

Links

• - Documentation
• API Reference
• MCP Endpoint
• SDK