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 with a single cURL command:

curl -X POST https://api.rundocling.com/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@document.pdf" \
  -F "output_format=markdown"

Response:

{
  "id": "conv_abc123",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_time": 5
}

POST /v1/convert

Upload a document for conversion. Supports PDF, DOCX, PPTX, XLSX, HTML, Markdown, and images.

Request Parameters

Parameter	Type	Required	Description
`file`	File	Yes	The document to convert (max 50MB)
`output_format`	String	No	`markdown` (default) or `json`
`ocr`	Boolean	No	Enable OCR for scanned documents (default: auto)
`webhook_url`	String	No	URL to receive completion webhook

Example Request

curl -X POST https://api.rundocling.com/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "output_format=json" \
  -F "ocr=true"

Response

{
  "id": "conv_abc123",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_time": 5,
  "file_name": "document.pdf",
  "file_size": 1024000,
  "output_format": "json"
}

GET /v1/status/:id

Check the status of a conversion job.

curl https://api.rundocling.com/v1/status/conv_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "conv_abc123",
  "status": "completed",
  "progress": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z",
  "pages_processed": 12
}

Status values: queued, processing, completed, failed

GET /v1/result/:id

Retrieve the converted document result.

curl https://api.rundocling.com/v1/result/conv_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Markdown Response

{
  "id": "conv_abc123",
  "format": "markdown",
  "content": "# Document Title\n\nThis is the extracted content...",
  "metadata": {
    "pages": 12,
    "tables": 3,
    "images": 5
  }
}

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 50MB limit
429	`rate_limited`	Too many requests
500	`processing_error`	Internal processing failure

Rate Limits

Rate limits vary by plan and are enforced per API key:

Plan	Requests/min	Pages/month	Max file size
Free	10	20	10MB
Pro	60	10,000	50MB
Enterprise	Custom	Unlimited	Custom

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset