markdownbridge

Python SDK for the MarkdownBridge OCR API — convert documents and images to Markdown.

Installation

pip install markdownbridge

Quick Start

frommarkdownbridgeimportMarkdownBridgeclient=MarkdownBridge(api_key="ocrb_prd_xxx")
# One-liner: URL → Markdownresult=client.ocr("https://example.com/invoice.pdf")
print(result.markdown)
# One-liner: local file → Markdownresult=client.ocr("./receipt.png")
print(result.markdown)

Authentication

Pass your API key directly or set the MARKDOWNBRIDGE_API_KEY environment variable:

export MARKDOWNBRIDGE_API_KEY="ocrb_prd_xxx"

client=MarkdownBridge() # reads from env

Client Options

client=MarkdownBridge(
api_key="ocrb_prd_xxx", # or env MARKDOWNBRIDGE_API_KEYbase_url="https://api.markdownbridge.com", # defaulttimeout=30.0, # request timeout in secondsmax_retries=3, # retry 5xx errors with backoff
)

API Reference

client.ocr(source, **opts)

The convenience method — give it a URL or file path, get back a ProcessingResult.

result=client.ocr(
"https://example.com/doc.pdf",
language="en",
output_format="markdown",
enhance_quality=True,
poll_interval=2.0, # seconds between status checkspoll_timeout=300.0, # max wait time
)
print(result.markdown)
print(result.page_count)

client.process_url(file_url, **opts)

Submit a URL for processing without waiting for completion.

proc=client.process_url("https://example.com/doc.pdf")
print(proc.process_id) # use with get_status() / wait_for_completion()

client.process_file(file_path, **opts)

Upload a local file and submit it for processing.

proc=client.process_file("./invoice.pdf")
print(proc.process_id)

client.upload_file(file_path)

Upload a file without processing it.

upload=client.upload_file("./photo.png")
print(upload.document_id)

client.get_status(process_id)

Check the current status of a processing job.

status=client.get_status("uuid-here")
print(status.status) # queued | processing | completed | failedprint(status.progress) # 0–100print(status.stage) # queued | download | ocr | llm_improvement | completed | failed

client.wait_for_completion(process_id, **opts)

Poll until the job completes or fails.

result=client.wait_for_completion(
"uuid-here",
poll_interval=2.0,
poll_timeout=300.0,
on_status_change=lambdas: print(f"Status: {s.status} ({s.stage})"),
)

client.list_results(**filters)

Fetch paginated results.

page=client.list_results(limit=20, offset=0, status="completed")
foriteminpage.data:
print(item.file_name, item.status)
print(f"Total: {page.pagination.total}")

client.iter_results(**filters)

Auto-paginating iterator over all results.

foriteminclient.iter_results(status="completed"):
print(item.file_name)

client.get_result(result_id)

Fetch a specific result by ID.

result=client.get_result("uuid-here")
print(result.result.markdown)

client.info()

Get API version and status.

info=client.info()
print(info.version, info.status)

Async Usage

Every method has an async equivalent via AsyncMarkdownBridge:

importasynciofrommarkdownbridgeimportAsyncMarkdownBridgeasyncdefmain():
asyncwithAsyncMarkdownBridge(api_key="ocrb_prd_xxx") asclient:
result=awaitclient.ocr("https://example.com/invoice.pdf")
print(result.markdown)
# Auto-paginating async iterationasyncforiteminclient.iter_results():
print(item.file_name)
asyncio.run(main())

Error Handling

All exceptions inherit from MarkdownBridgeError and include status_code, error_code, and correlation_id:

frommarkdownbridgeimportMarkdownBridge, RateLimitError, AuthenticationErrorclient=MarkdownBridge(api_key="ocrb_prd_xxx")
try:
result=client.ocr("https://example.com/doc.pdf")
exceptAuthenticationError:
print("Invalid API key")
exceptRateLimitErrorase:
print(f"Rate limited — retry after {e.retry_after}s")
exceptMarkdownBridgeErrorase:
print(f"API error {e.status_code}: {e}")

Exception Hierarchy

Exception	HTTP Status	When
AuthenticationError	401	Invalid or missing API key
ValidationError	400/422	Invalid request parameters
NotFoundError	404	Resource not found
RateLimitError	429	Too many requests
InsufficientCreditsError	402	Account has no credits
ServerError	5xx	Server-side failure
ProcessingError	—	OCR job failed
FileUploadError	—	Upload failed
TimeoutError	—	Polling exceeded timeout

Data Types

All response types are frozen dataclasses:

• ProcessResponse — process_id, status, file_id, stage
• ProcessingStatus — process_id, status, progress, stage, result, error
• ProcessingResult — text, markdown, json, page_count, processing_time
• UploadResponse — file_key, public_url, document_id
• ResultItem — id, process_id, file_name, status, result
• ResultsPage — data, pagination
• Pagination — total, limit, offset, has_more, next_offset
• ApiInfo — version, status, endpoints

License

MIT