Get started

OpenParser ships four ways to call the same API. Pick the surface that fits your workflow; endpoint parameters and response schemas live in the API reference.

Install

curl --version

npm i -g @openparser/cli

npm i @openparser/sdk

pip install openparser

Authenticate

Create an API key with ocr:full scope. Every client sends it as Authorization: Bearer <key>. The key scopes requests to your organization — there is no separate tenant header. The CLI can store the key in a named profile; the SDKs can read OPENPARSER_API_KEY and OPENPARSER_BASE_URL from the environment.

export OPENPARSER_API_KEY='op_live_...'
curl 'https://api.openparser.dev/models/ocr' \
  -H "Authorization: Bearer $OPENPARSER_API_KEY"

openparser auth login

import { OpenParserClient } from '@openparser/sdk';

const client = new OpenParserClient({
  apiKey: process.env.OPENPARSER_API_KEY,
  // baseUrl defaults to https://api.openparser.dev
});

import os
from openparser import OpenParserClient

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

CLI named profiles

The CLI stores API keys in named profiles at ~/.config/openparser/credentials.json. Use profiles when you switch between environments on one machine. SDKs and direct HTTP calls do not read CLI profiles; they use environment variables or constructor options. auth logout with no profile name removes the active profile.

openparser auth login
openparser auth login --profile staging --base-url https://sapi.openparser.dev
openparser auth list
openparser auth use staging
openparser auth logout
openparser auth logout staging

Environment variables

CLI resolution order: --base-url / --profile flags → OPENPARSER_API_KEY / OPENPARSER_BASE_URL / OPENPARSER_PROFILE → active profile → defaults.

When OPENPARSER_API_KEY is set, the CLI does not read stored profiles for the API key or base URL.

export OPENPARSER_API_KEY='op_live_...'
export OPENPARSER_BASE_URL='https://api.openparser.dev'

# CLI only: select a stored profile instead of exporting a key.
export OPENPARSER_PROFILE='staging'

Parse your first document

Choose a PDF, PNG, or JPEG file up to 50 MiB. The request is multipart: request carries the parse configuration as application/json, and file carries the document bytes.

ocr_model is required. Use an ID from GET /models/ocr. The openparser@1 output format is versioned, so its response shape stays stable as the underlying OCR model changes.

curl -X POST 'https://api.openparser.dev/parse' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || openssl rand -hex 16)" \
  -F 'request={"ocr_model":"paddleocr-vl-1.6","output_format":"openparser@1"};type=application/json' \
  -F 'file=@./document.pdf'

openparser parse sync ./document.pdf

const parsed = await client.parse.sync(
  { ocr_model: 'paddleocr-vl-1.6', output_format: 'openparser@1' },
  file,
);

from pathlib import Path

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

Most requests finish with 200 OK and a ParsedDocument. Longer work returns 202 Accepted with a job ID — poll GET /jobs/{id} or follow the Location header. See Jobs.

Next steps

• Model catalogs — list OCR and LLM models
• Errors and retries — safe admission retries
• Jobs — admit work and poll for results
• Files — inline uploads and the reusable file pool
• Typed errors — SDK exception classes and the ErrorResponse envelope