Documentation

Everything you need to parse PDFs into structured markdown and JSON.

Docule turns PDFs into clean markdown and richly-structured JSON. The API is asynchronous: you submit a file, poll a status endpoint, then download the result when it's ready.

What you'll find here

Base URL

All API requests use the following base URL:

https://docule.dev/api/v1

How it works

1. Submit a PDF to POST /parse. You get a job_id back immediately.
2. Poll GET /status/{job_id} until status becomes "completed".
3. Download the parsed output from GET /result/{job_id} in JSON, markdown, or plain text.

Quick start

Parse your first PDF in three steps.

# Upload your PDF
curl -X POST https://docule.dev/api/v1/parse \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@report.pdf"

# Response (HTTP 202)
{
  "job_id": "20260407_120530_a1b2c3d4e5f6g7h8",
  "status": "queued",
  "created_at": "2026-04-07T12:05:30.123Z",
  "message": "Job submitted. Poll GET /api/v1/status/{job_id}"
}

# Poll until completed
curl https://docule.dev/api/v1/status/JOB_ID \
  -H "X-API-Key: YOUR_KEY"

# Download the parsed result
curl https://docule.dev/api/v1/result/JOB_ID?format=json \
  -H "X-API-Key: YOUR_KEY"

Authentication

Authenticate every request with your API key.

All API requests require an API key passed via the X-API-Key HTTP header.

curl https://docule.dev/api/v1/health \
  -H "X-API-Key: pp_live_your_key_here"

Getting your key

After signing up, generate a key from the API keys dashboard. You can create multiple keys and revoke them at any time.

Keep your key secret

Your API key grants full access to your account's parsing quota. Treat it like a password:

• Never commit keys to git or paste them into client-side code.
• Use environment variables in production.
• Rotate keys if you suspect compromise.

Errors

Parse a document

Upload a PDF for parsing. Returns a job ID for status polling.

Processing is asynchronous — you'll get a job_id back immediately, then poll /status until the job completes.

Request

Send the PDF as multipart/form-data. All other parameters are optional query strings:

Response (HTTP 202)

{
  "job_id": "20260407_120530_a1b2c3d4e5f6g7h8",
  "status": "queued",
  "created_at": "2026-04-07T12:05:30.123Z",
  "message": "Job submitted. Poll GET /api/v1/status/{job_id}"
}

Limits

• Maximum file size: 50 MB
• Maximum concurrent jobs: 1 per user (returns HTTP 429 if exceeded)
• Monthly page quota varies by plan — see rate limits

Check job status

Poll for job progress and quality metrics.

Returns the current job status, progress, and (when complete) quality and cost metrics.

Response

{
  "job_id": "20260407_120530_a1b2c3d4e5f6g7h8",
  "status": "completed",
  "created_at": "2026-04-07T12:05:30.123Z",
  "started_at": "2026-04-07T12:05:31.456Z",
  "completed_at": "2026-04-07T12:05:45.789Z",
  "progress": 1.0,
  "total_pages": 42,
  "pages_processed": 42,
  "quality_score": 97.5,
  "quality_warning": false,
  "cost_usd": 0.0234,
  "api_calls": 8,
  "document_type": "report",
  "error": null
}

Fields

Get results

Retrieve the parsed output of a completed job.

Returns the structured result wrapped in a response envelope with metadata.

Parameters

Response (format=json)

{
  "job_id": "20260407_120530_a1b2c3d4e5f6g7h8",
  "status": "completed",
  "result": { /* full parsed JSON — see JSON structure */ },
  "markdown": null,
  "text": null,
  "quality_score": 97.5,
  "metadata": {
    "filename": "report.pdf",
    "pages": 42,
    "cost_usd": 0.0234,
    "api_calls": 8
  },
  "document_type": "report"
}

When requesting format=md, the markdown field contains the full document text and result is null. Same for format=txt with the text field.

Download raw file

Download the raw output file directly, without the JSON envelope.

Returns the file content with the appropriate Content-Type — useful for piping straight to disk.

Parameters

Example

# Download markdown directly to a file with page markers
curl "https://docule.dev/api/v1/result/JOB_ID/raw?format=md&include_page_markers=true" \
  -H "X-API-Key: YOUR_KEY" \
  -o report.md

Content types

• format=json → application/json
• format=md → text/plain
• format=txt → text/plain

List jobs

List your recent parsing jobs, newest first.

Parameters

Response

[
  {
    "job_id": "20260407_120530_a1b2c3d4e5f6g7h8",
    "status": "completed",
    "filename": "report.pdf",
    "created_at": "2026-04-07T12:05:30.123Z",
    "completed_at": "2026-04-07T12:05:45.789Z",
    "pages": 42,
    "quality_score": 97.5,
    "cost_usd": 0.0234
  }
]

Health check

Check API status and queue depth. No authentication required.

Response

{
  "status": "ok",
  "version": "0.1.0",
  "active_jobs": 3,
  "queued_jobs": 0
}

Fields

Output formats

Three formats for three different use cases.

Every parsed document can be retrieved in three formats. Specify which to generate using the formats parameter on /parse:

POST /api/v1/parse?formats=json,md,txt

JSON (json)

Structured data that defaults to strict content export (pages, text, markdown, items) with optional metadata toggles when you need extra context.

Best for: programmatic access, RAG pipelines, search indexing with rich metadata.

See the full schema at JSON structure.

Markdown (md)

Clean, readable text with tables in pipe format. Page markers are optional via query parameter.

Best for: human review, LLM context windows, documentation pipelines.

Plain text (txt)

Raw text without formatting or markers.

Best for: full-text search indexing, simple analytics.

JSON structure

The full schema returned by the parser.

The JSON output (the result field of the /result response) defaults to strict content mode:

{
  "pages": [
    {
      "text": "Income Statement\nItem 2025 2024...",
      "markdown": "### Income Statement\n| Item | 2025 | 2024 |\n...",
      "items": [
        {
          "type": "heading",
          "markdown": "### Income Statement",
          "text": "Income Statement",
          "level": 3
        },
        {
          "type": "table",
          "markdown": "| Item | 2025 | 2024 |\n|---|---|---|\n...",
          "text": "Item 2025 2024...",
          "table": {
            "rows": [["Revenue", "1,200", "1,050"]]
          }
        }
      ]
    }
  ]
}

Optional metadata can be added with query params on /result or /result/{job_id}/raw:

GET /api/v1/result/{job_id}?format=json&include_page_metadata=true&include_item_metadata=true
GET /api/v1/result/{job_id}?format=json&include_source_path=true&include_document_metadata=true
GET /api/v1/result/{job_id}?format=json&include_processing_metadata=true

To include page boundary markers in text outputs:

GET /api/v1/result/{job_id}?format=md&include_page_markers=true
GET /api/v1/result/{job_id}/raw?format=txt&include_page_markers=true

Page metadata fields (optional)

Each page is classified into a semantic type for smarter processing:

Top-level metadata fields (optional)

Item types

The items array contains structured content blocks:

Python example

Upload a PDF, wait for parsing, and save the result.

This complete example uses only the requests library — no SDK required.

Pythonimport requests
import time

API_KEY = "pp_live_your_key_here"
BASE = "https://docule.dev/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# 1. Upload PDF
with open("report.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE}/parse",
        headers=HEADERS,
        files={"file": f},
        params={"formats": "json,md"},
    )
    resp.raise_for_status()

job_id = resp.json()["job_id"]
print(f"Job submitted: {job_id}")

# 2. Poll until complete
while True:
    status = requests.get(
        f"{BASE}/status/{job_id}", headers=HEADERS
    ).json()

    print(f"  {status['status']} — {status['progress']:.0%}")

    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        raise RuntimeError(f"Job failed: {status['error']}")

    time.sleep(2)

# 3. Get JSON result
result = requests.get(
    f"{BASE}/result/{job_id}",
    headers=HEADERS,
    params={"format": "json"},
).json()

print(f"Pages: {result['metadata']['pages']}")
print(f"Quality: {result['quality_score']}")

for page in result["result"]["pages"]:
    print(page["markdown"][:200])

# 4. Download markdown to file (with page markers)
md = requests.get(
    f"{BASE}/result/{job_id}/raw?format=md&include_page_markers=true",
    headers=HEADERS,
).text

with open("report.md", "w") as f:
    f.write(md)
print("Saved report.md")

cURL example

End-to-end shell script using cURL and jq.

Bash#!/bin/bash
# Submit a PDF and download the parsed markdown

API_KEY="YOUR_KEY"
BASE="https://docule.dev/api/v1"

# Submit the PDF
JOB=$(curl -s -X POST $BASE/parse \
  -H "X-API-Key: $API_KEY" \
  -F "file=@report.pdf" | jq -r '.job_id')

echo "Job: $JOB"

# Poll until done
while true; do
  STATUS=$(curl -s $BASE/status/$JOB \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Failed!" && exit 1
  sleep 2
done

# Download the markdown with optional page markers
curl -s "$BASE/result/$JOB/raw?format=md&include_page_markers=true" \
  -H "X-API-Key: $API_KEY" -o report.md

echo "Saved report.md"

Rate limits

Plan tiers, quotas, and overage pricing.

How counting works

• One page equals one credit. A 42-page PDF consumes 42 credits.
• Quotas reset on the first day of each calendar month.
• Free accounts have no overage — requests are rejected once the quota is hit.
• Paid plans can opt in to on-demand usage from Settings → Billing. When enabled, any pages beyond the plan's monthly allowance are added to your next Stripe invoice automatically at the overage rate above. We email you once per month the first time a job crosses into on-demand usage.
• Opt-in is off by default, so you can never be billed beyond your plan without explicitly turning it on.

Concurrency

Maximum 1 concurrent job per user across all plans. Submitting a second while one is in progress returns HTTP 429.

What triggers HTTP 429

• Exceeding your requests-per-second limit
• Exceeding your monthly page quota (free plan only)
• Submitting more than 1 job concurrently

Error codes

HTTP status codes and how to handle them.

Error response format

All error responses share this shape:

{
  "error": "Rate limit exceeded",
  "detail": "Rate limit exceeded (3 req/sec). Upgrade your plan for higher limits."
}

Recommended handling

• 429: back off and retry. Use exponential backoff starting at 1 second.
• 409 on /result: the job isn't ready — keep polling /status.
• 5xx: retry with backoff. Check /health if errors persist.
• 4xx (other): fix your request — these will not succeed on retry.