PDF in, structured JSON out

Parse is okraPDF's core API. One call turns a PDF into clean, structured JSON — every value keeps its page and position with a confidence score, so each one traces back to where it sits on the page.

Start for $0

The problem: a PDF is a bag of glyphs, not a document

A PDF stores ink positions, not structure. There are no paragraphs, no table cells, no reading order, and nothing tying a number back to where it sits on the page. So every team rebuilds the same brittle layer: layout heuristics, OCR fallbacks for scans, table reconstruction, and glue code to feed a model. Parse collapses that layer into one request. You send a PDF and get back clean, structured JSON that preserves layout and tables, keeps the page and position of every value, and scores how confident it is — so you can route the uncertain parts to review instead of trusting them blind.

Upload a PDF, read structured JSON

One POST to /v1/parse returns a job; poll job.url for the result. Send file bytes inline (base64) or reference an upload from /v1/files. Scanned pages are OCR'd in the same path, so a photographed invoice and a born-digital report return the same shape. Add a JSON Schema to the request to get structured extraction back instead of raw blocks.

# 1. Start a parse job — file bytes inline (<=20MB), or pass {"id"} from POST /v1/files
JOB=$(curl -s -X POST https://api.okrapdf.com/v1/parse \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file\":{\"data\":\"$(base64 < report.pdf)\"},\"parser\":\"okra\"}")

# 2. Poll the returned job (job.url) for the structured result
curl -s "https://api.okrapdf.com$(echo "$JOB" | jq -r .url)" \
  -H "Authorization: Bearer $OKRA_API_KEY"

What comes back

The result is grouped by page: every item has a type and value, its position on the page, and a confidence score from 0 to 1, plus run metadata. Because the position travels with the value, the citation survives into your vector store or agent context.

{
  "pages": [
    {
      "pageNumber": 3,
      "blocks": [
        {
          "type": "heading",
          "value": "Consolidated Balance Sheet",
          "bbox": { "x": 0.09, "y": 0.11, "w": 0.42, "h": 0.03 },
          "confidence": 0.99
        },
        {
          "type": "table_cell",
          "value": "1,204,318",
          "bbox": { "x": 0.48, "y": 0.21, "w": 0.10, "h": 0.02 },
          "confidence": 0.94
        }
      ]
    }
  ],
  "metadata": { "vendor": "okra", "pageCount": 12, "confidence": 0.97, "durationMs": 4120 }
}

Capabilities

Layout preserved: headings, paragraphs, and tables come back as structure, not a flat wall of text.
Grounded to the page: every value keeps its page number and position, so it points back to exactly where it came from.
Confidence on every value: a 0 to 1 score you can threshold to auto-accept the clean parts and send the rest to review.
OCR for scans: photographed and scanned PDFs return the same JSON shape as born-digital files.
JSON or Markdown: structured JSON for pipelines, Markdown when you are passing the document straight to an LLM.
Parse once, query many: the result is yours to keep and query, so you do not re-parse the same PDF for every question.

Where Parse fits

Parse is the foundation for RAG and agent pipelines that have to cite sources. Because every value carries its page and position, an agent can answer with a quote and a precise region instead of an unattributed paraphrase, and a reviewer can verify it in one click. It is also the front end for higher-level okraPDF jobs: feed the parsed output into schema-based extraction, build collections you query across documents, or anchor citations to the exact box a value came from. You can try parsing on the free public web tier with no account, reach it from agents over MCP with a free login, and run it programmatically with an okra_ API key when you move to production.

Frequently asked questions

What does a Parse response contain?

Clean, structured JSON for the PDF: headings, paragraphs, and tables with their layout preserved, the page number and position of every value, and a confidence score between 0 and 1. You can request the same output as JSON or Markdown.

Does Parse handle scanned PDFs?

Yes. Scanned and photographed pages are OCR'd in the same request path, so a scanned document returns the same structured output as a born-digital one. There is no separate OCR endpoint to wire up.

How does Parse keep answers traceable to the source?

Every value keeps its page number and position on the page. That means an agent or RAG pipeline can cite the exact source of a claim, and a reviewer can verify it against the original.

Do I need an account to use Parse?

It depends on the surface. The public web tier is free with no login, agents can reach Parse over MCP with a free account, and programmatic API access uses an okra_ API key. Mint a key from your dashboard when you are ready to call it from your own backend.