openparser-sdk

Parse and extract structured data from documents with the OpenParser API.

Install the PyPI distribution openparser-sdk; import the client as openparser.

Documentation · OpenParser

Install

pip install openparser-sdk

Use Python 3.10 or newer. Create an API key in the OpenParser dashboard.

Quick Start

import os
from pathlib import Path
from openparser import OpenParserClient

client = OpenParserClient(api_key=os.environ["OPENPARSER_API_KEY"])

result = client.parse.sync(
    {"ocr_model": "paddleocr-vl-1.6", "output_format": "openparser@1"},
    file=Path("invoice.pdf"),
)

print(result.page_count)

Set OPENPARSER_API_KEY to create the client without constructor arguments. Set OPENPARSER_BASE_URL to use a different API origin.

Parse

The API holds synchronous requests for up to 300 seconds. It returns the result when processing finishes or a durable job reference when the wait expires.

# Sync: hold the connection until the result or timeout.
parsed = client.parse.sync(
    {"ocr_model": "paddleocr-vl-1.6"},
    file=Path("document.pdf"),
)

# Async: create a job and poll it later.
accepted = client.parse.async_(
    {"ocr_model": "paddleocr-vl-1.6"},
    file=Path("document.pdf"),
)
job = client.wait_for_job(accepted.id)

# Reuse a file-pool upload instead of inline bytes.
uploaded = client.files.upload(Path("document.pdf"))
parsed = client.parse.sync({"ocr_model": "paddleocr-vl-1.6", "file_id": uploaded.id})

The SDK adds an Idempotency-Key header to every parse and extract request. Pass idempotency_key= when you need to control retries.

Extract

extracted = client.extract.sync(
    {
        "ocr_model": "paddleocr-vl-1.6",
        "llm_model": "openai/gpt-4.1-mini",
        "schema": {
            "type": "object",
            "properties": {"total": {"type": "number"}},
        },
    },
    file=Path("invoice.pdf"),
)

suggested = client.extract.suggest_schema(
    {
        "parse_job_id": "opj_...",
        "hint": "Invoice number, vendor, and total",
    }
)

OpenParserClient is synchronous. Methods named async_ submit durable jobs without waiting for processing to finish.

Jobs

jobs_page = client.jobs.list(status="succeeded", limit=25)
first_job_id = jobs_page.data[0].id
job = client.jobs.get("opj_...")
parse_result = client.jobs.result("opj_...", format="openparser@1")
source_bytes = client.jobs.source("opj_...")

jobs.result() returns parse representations. Extract output is available on the job returned by jobs.get().

Files

uploaded = client.files.upload(Path("contract.pdf"))
metadata = client.files.get(uploaded.id)
content = client.files.download(uploaded.id)
client.files.delete(uploaded.id)

Uploads accept pathlib.Path, a file handle, or {"content": bytes, "filename": str, "mime_type": str?}.

Models

ocr_models = client.models.list_ocr()
llm_models = client.models.list_llm(mode="search", q="claude")
first_ocr_model = ocr_models.data[0]
first_llm_model = llm_models.data[0]

Pipelines

pipeline = client.pipelines.create(
    {
        "name": "invoice-extract",
        "ocr_model": "paddleocr-vl-1.6",
        "llm_model": "anthropic/claude-sonnet-4",
        "schema": {
            "type": "object",
            "properties": {"vendor": {"type": "string"}},
            "required": ["vendor"],
        },
    }
)

listed = client.pipelines.list()
first_pipeline = listed.items[0]
current = client.pipelines.get(pipeline.id)
updated = client.pipelines.update(pipeline.id, {"name": "invoice-v2"})
client.pipelines.delete(pipeline.id)

Errors

Every non-2xx response raises a typed subclass of OpenParserError:

Each error exposes the API response through error.envelope: code, message, request_id, and retryable.

Development

After changing the OpenAPI specification, regenerate the client and run its checks:

packages/openparser-sdk-python/scripts/codegen.sh
packages/openparser-sdk-python/scripts/check-codegen.sh
uv run --project packages/openparser-sdk-python pytest

License

Apache-2.0