Introduction

RunDocling is a managed API service that wraps the powerful Docling library, providing a simple REST API for converting PDFs and documents into structured Markdown or JSON.

With RunDocling, you can:

Convert complex PDFs with tables, images, and layouts
Extract structured data in Markdown or JSON format
Process scanned documents with OCR
Scale without managing infrastructure

Base URL: https://api.rundocling.com

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your dashboard. Keep your API keys secure and never expose them in client-side code.

Quick Start

Convert your first PDF in seconds. We recommend the Async API for reliability.

Note: Typical processing time is 10-30 seconds. For large batches, always use the Async flow.

curl -X POST https://api.rundocling.com/v1/convert/file/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "to_formats=md"

Response:

{
  "task_id": "e076b2e2-f738-48a1-b61d-7e209d1e9a1b",
  "status": "pending",
  "total_pages": 5
}

POST/v1/convert/file

Upload a document for conversion and get the result immediately (Synchronous). Best for small documents.

Request Parameters

Parameter	Type	Required	Description
`files`	File \| List[File]	Yes	The document(s) to convert
`to_formats`	String \| List[String]	No	Default: `md`

Example Request

curl -X POST https://api.rundocling.com/v1/convert/file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "to_formats=md"

Response

{
  "document_result": {
    "status": "success",
    "pages": 5,
    "output": {
        "md": "# Extracted Title\n\nContent..."
    }
  }
}

POST/v1/convert/file/async

Upload a document and receive a Task ID (Asynchronous). Best for large documents or batch processing.

Request Parameters

Parameter	Type	Required	Description
`files`	File \| List[File]	Yes	The document(s) to convert
`to_formats`	String \| List[String]	No	Default: `md`

Example Request

curl -X POST https://api.rundocling.com/v1/convert/file/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "to_formats=json_docling" \
  -F "do_ocr=true"

Response

{
  "task_id": "e076b2e2-f738-48a1-b61d-7e209d1e9a1b",
  "status": "pending",
  "total_pages": 5
}

POST/v1/convert/source

Convert a document from a URL or S3 bucket and get the result immediately (Synchronous).

Example Request

curl -X POST https://api.rundocling.com/v1/convert/source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}],
    "options": {"to_formats": ["md"]}
  }'

Response

{
  "document_result": {
    "status": "success",
    "pages": 5,
    "output": {
        "md": "# Extracted Title\n\nContent..."
    }
  }
}

POST/v1/convert/source/async

Convert a document from a URL or S3 bucket and receive a Task ID (Asynchronous).

Example Request

curl -X POST https://api.rundocling.com/v1/convert/source/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}],
    "options": {"to_formats": ["md"]}
  }'

Response

{
  "task_id": "e076b2e2-f738-48a1-b61d-7e209d1e9a1b",
  "status": "pending",
  "total_pages": 5
}

Convert Parameters

All convert endpoints accept these optional parameters via form data (for file uploads) or JSON body (for source URLs).

Output Options

Parameter	Type	Default	Description
`to_formats`	string[]	["md"]	Output formats: md, json, html, text, doctags
`image_export_mode`	string	embedded	placeholder, embedded, or referenced
`include_images`	boolean	true	Extract images from document
`images_scale`	number	2.0	Scale factor for extracted images

OCR Options

Parameter	Type	Default	Description
`do_ocr`	boolean	true	Process bitmap content with OCR
`force_ocr`	boolean	false	Replace existing text with OCR output
`ocr_engine`	string	easyocr	auto, easyocr (recommended), rapidocr, tesserocr, tesseract
`ocr_lang`	string[]	null	Language codes for OCR (e.g., ["en", "fr"])

Table Options

Parameter	Type	Default	Description
`do_table_structure`	boolean	true	Extract table structure
`table_mode`	string	accurate	fast or accurate

Processing Options

Parameter	Type	Default	Description
`pipeline`	string	standard	Processing pipeline (standard or vlm)
`pdf_backend`	string	dlparse_v4	pypdfium2, dlparse_v1, dlparse_v2, dlparse_v4
`page_range`	[int, int]	[1, max]	Page range to convert [start, end]
`document_timeout`	number	604800	Timeout in seconds per document

Enrichment Options

Parameter	Type	Default	Description
`do_code_enrichment`	boolean	false	Perform code OCR enrichment
`do_formula_enrichment`	boolean	false	Perform formula OCR, return LaTeX
`do_picture_classification`	boolean	false	Classify pictures in documents
`do_picture_description`	boolean	false	Generate descriptions for pictures

Example with Parameters

curl -X POST https://api.rundocling.com/v1/convert/file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "to_formats=md" \
  -F "do_ocr=true" \
  -F "ocr_engine=easyocr" \
  -F "table_mode=accurate" \
  -F "do_table_structure=true"

POST/v1/upload

Upload a file for later conversion. Useful for large files that exceed HTTP body limits. Returns a file_id that can be used with /v1/convert/source endpoints.

curl -X POST https://api.rundocling.com/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

Response

{
  "file_id": "550e8400-e29b-41d4-a716-446655440000"
}

POST/v1/chunk/hierarchical/file

Hierarchical chunking of a document. Chunks are structured based on document hierarchy (headings, sections). Ideal for maintaining document structure in RAG applications.

curl -X POST https://api.rundocling.com/v1/chunk/hierarchical/file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

POST/v1/chunk/hierarchical/file/async

Async version of hierarchical chunking. Returns a task_id for polling.

curl -X POST https://api.rundocling.com/v1/chunk/hierarchical/file/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

POST/v1/chunk/hybrid/file

Hybrid chunking combines hierarchical and token-based approaches. Balances structure preservation with chunk size control.

curl -X POST https://api.rundocling.com/v1/chunk/hybrid/file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

POST/v1/chunk/hybrid/file/async

Async version of hybrid chunking. Returns a task_id for polling.

curl -X POST https://api.rundocling.com/v1/chunk/hybrid/file/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

POST/v1/chunk/hierarchical/source

Hierarchical chunking from a URL source.

curl -X POST https://api.rundocling.com/v1/chunk/hierarchical/source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}]
  }'

POST/v1/chunk/hierarchical/source/async

Async version of hierarchical chunking from URL source.

curl -X POST https://api.rundocling.com/v1/chunk/hierarchical/source/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}]
  }'

POST/v1/chunk/hybrid/source

Hybrid chunking from a URL source.

curl -X POST https://api.rundocling.com/v1/chunk/hybrid/source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}]
  }'

POST/v1/chunk/hybrid/source/async

Async version of hybrid chunking from URL source.

curl -X POST https://api.rundocling.com/v1/chunk/hybrid/source/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}]
  }'

GET/v1/status/poll/{task_id}

Check the status of a conversion job.

curl https://api.rundocling.com/v1/status/poll/e076b2e2-f738-48a1-b61d-7e209d1e9a1b \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "task_id": "e076b2e2-f738-48a1-b61d-7e209d1e9a1b",
  "task_type": "convert",
  "task_status": "in_progress",
  "task_position": null,
  "task_meta": null,
  "error": null,
  "received_at": "2025-12-08T18:07:52Z",
  "started_at": "2025-12-08T18:07:52Z",
  "completed_at": null,
  "duration_seconds": 7.19
}

Status values: pending, in_progress, completed, failed, not_found

GET/v1/result/{task_id}

Retrieve the converted document result.

curl https://api.rundocling.com/v1/result/e076b2e2-f738-48a1-b61d-7e209d1e9a1b \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "document_result": {
    "status": "success",
    "pages": 5,
    "output": {
        "md": "# Title\n\nContent...",
        "json_docling": {...}
    }
  }
}

Error Handling

The API uses standard HTTP status codes. Errors include a JSON body with details:

{
  "error": {
    "code": "invalid_file_type",
    "message": "Unsupported file type. Supported: PDF, DOCX, PPTX, XLSX, HTML, MD, PNG, JPG",
    "status": 400
  }
}

Common Error Codes

Status	Code	Description
400	`invalid_file_type`	Unsupported file format
401	`unauthorized`	Invalid or missing API key
413	`file_too_large`	File exceeds size limit
429	`rate_limited`	Too many requests
500	`processing_error`	Internal processing failure

Rate Limits

Rate limits and quotas vary by your subscription plan:

Plan	Currency	Limits per Request	Monthly Quota
Free	1 concurrent req	20 pages, 20MB max	50 pages
Pro	20 concurrent reqs	400 pages, 200MB max	10,000 pages
Enterprise	Unlimited	Custom	Unlimited