rc-doc API

PDF or image in; markdown and layout blocks out. Spec: /openapi.json (OpenAPI 3.1).

Auth

Authorization: Bearer <key> on every /v1 request. Missing or wrong key: 401.

POST /v1/parse

Synchronous: the response is the finished parse. One of three inputs:

Content-Type	Body
`application/pdf`, `image/png`, `image/jpeg`	The file bytes. Max 4.5 MB.
`multipart/form-data`	Field `file`. Max 4.5 MB.
`application/json`	`{"url": "https://…"}`. For files over 4.5 MB: https only, public host, no redirects, max 100 MB. Presigned S3/GCS URLs work.

Response 200

{
  "markdown": "# Title\n\n…",            // all pages, blank-line joined; tables are HTML
  "pages": [{
    "page": 1,                          // 1-based index in the file
    "markdown": "…",                    // without running headers/footers/page numbers
    "printed_page": "iv",               // printed page number, when found
    "layout": [{
      "label": "Section-header",        // Caption Footnote Formula List-item Page-footer Page-header
                                        // Picture Section-header Table Text Title
      "bbox": [0.08, 0.11, 0.84, 0.03], // x, y, w, h as page fractions, origin top-left
      "content": "## Results"
    }]
  }],
  "usage": {"pages": 9, "seconds": 39.6}
}

A page with "degraded": true was read with reduced quality; retry the request.

Errors

JSON {"error": "…"}.

`400`	No document, unreadable file, bad URL, over the page limit.
`401`	Missing or wrong key.
`413`	Body over 4.5 MB (send a `url`) or fetched file over 100 MB.
`500`	Parse failed.
`504`	Request over 300 s (about 35 pages). Split the document.

Limits

Body	4.5 MB direct; 100 MB via `url`
Pages	200 per request
Time	300 s per request
Inputs	PDF, PNG, JPEG (an image is one page)

Examples

export RCDOC=https://api.roughconsensus.com KEY=…

# file body
curl -sS -H "Authorization: Bearer $KEY" -H 'Content-Type: application/pdf' \
     --data-binary @doc.pdf "$RCDOC/v1/parse" | jq .usage

# multipart
curl -sS -H "Authorization: Bearer $KEY" -F file=@scan.png "$RCDOC/v1/parse"

# URL (files over 4.5 MB)
curl -sS -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
     -d '{"url":"https://example.com/report.pdf"}' "$RCDOC/v1/parse" | jq -r .markdown

# Python (requests)
import requests
r = requests.post(f"{RCDOC}/v1/parse", headers={"Authorization": f"Bearer {KEY}"},
                  files={"file": open("doc.pdf", "rb")}, timeout=310)
r.raise_for_status()
doc = r.json()
for p in doc["pages"]:
    tables = [b for b in p.get("layout", []) if b["label"] == "Table"]

Set client timeouts to at least 310 s. GET /health returns ok without auth.