API Specification

Status: stable draft — this contract is what Week 2 builds against. Changes require a DECISIONS.md entry.

Base URL: https://<host>/v1 — all routes are versioned under /v1 (decision 2026-07-12). /v2 is the future escape hatch; nothing lives at the root.

Authentication

Every endpoint except GET /v1/health requires an API key.

The auth middleware resolves either channel to an internal principal (key id, plan, quota state). Handlers never see platform-specific headers.

Resolution order (production): a request carrying X-RapidAPI-Proxy-Secret is RapidAPI traffic — an invalid secret is rejected outright (origin-direct requests forging RapidAPI headers never fall through to key auth). Otherwise X-API-Key resolves against our issued keys. Otherwise 401. The web tool's /web/extract path is separate (anonymous, rate-limited). The response envelope is identical on every channel. Quotas: direct keys are metered here (vision pages at 3x); RapidAPI plan limits are enforced by RapidAPI's gateway — we record consumption for telemetry only.

Missing/invalid credentials → 401. Exhausted monthly page quota → 429 with code quota_exceeded. Request-rate throttling → 429 with code rate_limited and a Retry-After header.

GET /v1/health

Unauthenticated liveness probe.

Response 200:

{ "status": "ok", "version": "0.1.0" }

POST /v1/extract

Extract tables from a single PDF.

Request

Two accepted content types:

1. multipart/form-data (preferred)

2. application/json (for callers that can't do multipart)

{
  "file_base64": "<base64-encoded PDF bytes>",
  "filename": "report.pdf",
  "pages": "1,3,5-10",
  "format": "json,markdown"
}

pages and format may also be given as query parameters with either content type; query parameters take precedence over body fields.

Parameters

pages — which pages to process. Default "all". 1-indexed. Comma-separated page numbers and inclusive ranges: "1,3,5-10". Out-of-range pages → 400 invalid_pages. Pages are billed only for pages actually processed.

format — which representations each table carries. Default "json". Comma-separated set of:

Structural metadata (page_range, confidence, extraction_layer, notes) is always present regardless of format. Unknown format value → 400 invalid_format.

Limits

The vision-page cap bounds worst-case latency and cost for the synchronous API. Requests that would exceed it fail fast with guidance to split the document or narrow pages; nothing is billed. (Async processing for large scanned documents: see POST /v1/jobs, planned.)

Response 200

{
  "document": {
    "filename": "report.pdf",
    "page_count": 42,
    "pages_processed": 8
  },
  "tables": [
    {
      "id": "t1",
      "page_range": [3, 4],
      "extraction_layer": "fast_path",
      "confidence": 0.94,
      "headers": ["Region", "Q1 2026", "Q2 2026"],
      "rows": [
        ["EMEA", "1,204", "1,377"],
        ["APAC", "980", "1,041"]
      ],
      "spans": [
        { "row": 0, "col": 1, "rowspan": 1, "colspan": 2 }
      ],
      "markdown": "<!-- pages 3-4 -->\n| Region | Q1 2026 | Q2 2026 |\n| --- | --- | --- |\n| EMEA | 1,204 | 1,377 |\n| APAC | 980 | 1,041 |",
      "csv": "Region,Q1 2026,Q2 2026\r\nEMEA,\"1,204\",\"1,377\"\r\nAPAC,980,\"1,041\"\r\n",
      "notes": ["stitched_across_pages", "merged_cells_resolved"]
    }
  ],
  "warnings": [],
  "usage": {
    "pages_billed": 10,
    "vision_pages": 1,
    "vision_page_multiplier": 3
  },
  "processing_time_ms": 843,
  "request_id": "req_8f2c1a"
}

Field reference

document

tables[] — ordered by first page, then vertical position.

warnings[] — document/page-level conditions, structured (decision 2026-07-14):

{ "code": "vision_unavailable", "message": "page 7: vision fallback not configured; fast-path results returned (may be low quality)", "page": 7 }

Scoping rule: warnings are document/page level; table-scoped conditions are machine-readable flags in each table's notes. When a table-level condition is worth surfacing at document level (e.g. ambiguous_merge), the warning carries the page and the table keeps its note — clients rendering per-table UI should read notes; clients triaging whole documents should read warnings. The two mechanisms never replace each other.

Warning code vocabulary:

usage

A PDF with no detectable tables is a success: 200 with tables: [] and an explanatory warning.

Response headers

Errors

All errors use one envelope:

{
  "error": {
    "code": "file_too_large",
    "message": "PDF is 61.2 MB; the limit is 50 MB.",
    "request_id": "req_8f2c1a"
  }
}

message is neutral, human-readable prose — no marketing copy, and wording may change; switch on code. An optional docs_url field may appear when there is a relevant pointer (e.g. rate_limited includes where to get an API key); it is omitted otherwise.

Billing rule: pages are billed only on 2xx responses, per the formula in usage above.

POST /v1/jobs — planned, not implemented

Reserved for async processing of documents that exceed the synchronous vision-page cap (decision 2026-07-12). Do not build against this section; it exists so adding async later is non-breaking. Intended shape:

• POST /v1/jobs — same payload as /v1/extract → 202 with { "job_id": "job_...", "status": "queued" }
• GET /v1/jobs/{job_id} — { "status": "queued" | "processing" | "done" | "failed", ... } with the standard extract response embedded under result when done.

Open design questions (deliberately unresolved): result retention window vs. the process-and-discard invariant, webhook completion callbacks, job-level page limits.

Plans (for reference)