Skip to main content

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

license

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-6-luna",
        "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",
    }
)

Grounding and lineage

Set "grounding": "field" to receive verified citations and a lineage@1 derivation DAG:

extracted = client.extract.sync(
    {
        "ocr_model": "mistral-ocr-4",
        "llm_model": "openai/gpt-6-luna",
        "grounding": "field",
        "schema": {
            "type": "object",
            "properties": {"total": {"type": "number"}},
        },
    },
    file=Path("invoice.pdf"),
)

lineage = extracted.to_dict().get("lineage")
if lineage is not None:
    print(lineage["outputs"])

The graph connects each output value to its source evidence and the operations that produced it. Evidence carries the closest recognition confidence supplied by the selected OCR model. Applications can append normalization, calculation, inference, and human-review activities without replacing the original machine result.

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-5.5",
        "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:

HTTP Class
400 OpenParserValidationError
401 OpenParserAuthError
402 OpenParserPaymentRequiredError
403 OpenParserForbiddenError
404 OpenParserNotFoundError
409 OpenParserConflictError
413 OpenParserLimitExceededError
415 OpenParserUnsupportedMediaError
422 OpenParserUnprocessableError
429 OpenParserRateLimitError
503 OpenParserServiceUnavailableError
504 OpenParserGatewayTimeoutError
5xx OpenParserServerError

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

Metadata

Release files for openparser-sdk 1.0.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openparser-sdk 1.0.22
File Size Uploaded Provenance Actions
openparser_sdk-1.0.22.tar.gz 100.5 kB With provenance Details for openparser_sdk-1.0.22.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openparser-sdk 1.0.22
File Interpreter ABI Platform Actions
openparser_sdk-1.0.22-py3-none-any.whl Python 3 none any Details for openparser_sdk-1.0.22-py3-none-any.whl

Total release size: 378.6 kB

Release files / openparser_sdk-1.0.22.tar.gz

Download URL openparser_sdk-1.0.22.tar.gz
Size 100.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f12024f495050a405c6a723321ae6e0f05409b3ce68aee25f35ce4c3453c82a2
BLAKE2b-256 checksum
How to use checksums
24f88171725b812c41b2b3e53d255a71fa8c6654579278ad1371dc39bb83e706
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / openparser_sdk-1.0.22-py3-none-any.whl

Download URL openparser_sdk-1.0.22-py3-none-any.whl
Size 278.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a68f3d77500950a0da71e84a4fe978416395ef2f6e6d086eb9492bbd3c853ef
BLAKE2b-256 checksum
How to use checksums
a56ee4df422496264c57dbae304bf96694348865498fabcce7175b93e2390763
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for openparser-sdk 1.0.22

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for openparser_sdk-1.0.22.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.22 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page