Documentation

Extraction · Inspect

Size up a document before spending any credits on it. Inspection is free — rate-limited, never billed — and tells you exactly what each extraction tier would cost for this document.

Endpoint: POST https://inkrun.dev/api/v1/inspect, authenticated with Authorization: Bearer sk_....
MCP tool: inspect_document.
Cost: free. It is the “inspect first” step of every document workflow — inspect liberally before choosing a tier.

Request body (JSON)

Field	Type	Required	Description
`file_base64`	string	one of	Standard base64 of the PDF bytes. (`file_path` works only on the local stdio MCP server, where the file is read on your machine.)
`file_url`	string	one of	An `http(s)` URL the server downloads the PDF from — cheaper than base64 for agents, which would otherwise emit the whole file as tokens. Must be publicly reachable: private, loopback and link-local addresses are refused, redirects are capped, and the download is size-capped to your plan’s document limit.
`mime`	string	no	Content type hint; PDFs are detected without it.

bash

curl "https://inkrun.dev/api/v1/inspect" \
  -H "Authorization: Bearer $INKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"file_base64\": \"$(base64 -i statement.pdf)\" }"

Response

json

{
  "id": "ext_3c81aa90",
  "pages": 6,
  "size_bytes": 412884,
  "classification": {
    "overall": "mixed",
    "per_page": [
      { "page": 1, "kind": "digital", "chars": 2140 },
      { "page": 2, "kind": "digital", "chars": 1893 },
      { "page": 3, "kind": "scanned", "chars": 0 },
      { "page": 4, "kind": "digital", "chars": 2011 },
      { "page": 5, "kind": "digital", "chars": 1750 },
      { "page": 6, "kind": "scanned", "chars": 0 }
    ]
  },
  "languages": ["en"],
  "form": {
    "type": "acroform",
    "supported": true,
    "fields": [
      { "name": "applicant_name", "type": "text", "has_value": true },
      { "name": "signature", "type": "signature", "has_value": false }
    ]
  },
  "estimates": {
    "inspect": 0,
    "deterministic": 1,
    "model": 4,
    "ocr": {
      "credits": 10,
      "required": true,
      "which_pages": [3, 6],
      "exceeds_sync_cap": false,
      "note": "2 pages have no text layer; extract will skip them unless ocr_fallback is true."
    }
  },
  "duration_ms": 96
}

Field	Description
`pages`	Page count.
`classification`	Overall and per-page `digital` vs `scanned` classification (with extractable character counts) — a heuristic, so the OCR estimate is phrased as a prediction.
`languages`	Detected languages/scripts, best-effort.
`form`	Fillable-form inventory: field names, types and whether each is filled — never the values.
`estimates`	What each extraction tier would cost for this document, in credits — the same numbers `extract` would charge.
`estimates.ocr`	The OCR decision made for you: `required` (are there scanned pages at all), `which_pages`, `exceeds_sync_cap` (too many scanned pages for one call) and the `credits` it would add. This is how you decide whether to pass `ocr_fallback: true` without spending a credit to find out.

The document is processed in memory and never stored. Inspection is free but rate-limited per key — pipelines that hammer it will see 429 rate_limited with a Retry-After header.

Errors

Same envelope and codes as Extract → Errors minus the contract errors: no preset/schema is involved, so the common failures are 413 input_too_large, 415 unsupported_document, 422 document_encrypted and 429 rate_limited.

Machine-readable spec

This page is the human reference; the machine-readable OpenAPI spec for the v1 API is planned as its own piece of work.