API Reference

All endpoints are served from https://docling-api.com. API keys use the format doc_ + 64 hex characters.

Authentication

Pass your API key in the X-Api-Key header or as a query parameter.

curl -H "X-Api-Key: doc_your_key_here" https://docling-api.com/api/v1/convert

Session endpoints (dashboard, key management) use Authorization: Bearer <jwt> obtained from /api/auth/login.

Error Codes

Code	Meaning
401	Invalid or missing API key / session
429	Rate limit exceeded
413	File too large (max 10MB free tier)
400	Invalid parameters
404	Task not found
503	Processing failed, retry

Rate Limits (Free Tier)

Limit	Value
Pages per day	50
Pages per hour	10
Max file size	10 MB

Auth Endpoints

POST/api/auth/register

Create an account and receive an API key. No authentication required.

Request Body

{
  "email": "you@example.com",
  "password": "min-8-characters",
  "name": "Optional Name"
}

Response (200)

{
  "api_key": "doc_a1b2c3d4e5f6...",
  "message": "Account created. Save your API key."
}

POST/api/auth/forgot-password

Request a password reset email. Always returns success to prevent email enumeration.

{"email": "you@example.com"}

Response (200)

{"message": "If that email is registered, a reset link has been sent."}

Key Management

GET/api/keys

List all API keys. Requires session JWT.

Response (200)

[{
  "id": "abc123...",
  "key_prefix": "doc_",
  "label": "Default",
  "is_active": true,
  "created_at": "2026-06-29T00:00:00",
  "last_used_at": null
}]

POST/api/keys/create

Generate a new API key. Full key returned once. Requires session JWT.

{"label": "Production"}

Response (200)

{
  "id": "abc123...",
  "key": "doc_abc123def456...",
  "key_prefix": "doc_",
  "message": "Save this key."
}

DELETE/api/keys/:id

Revoke a key. Stops working immediately. Requires session JWT.

Response (200)

{"message": "Key revoked"}

Usage

GET/api/usage

Get usage stats. Requires session JWT.

Response (200)

{
  "pages_today": 12,
  "pages_this_hour": 3,
  "total_tasks": 47,
  "limit_pages_per_hour": 10,
  "limit_pages_per_day": 50
}

Conversion

POST/api/v1/convert

Submit a PDF for processing. Requires API key.

Parameters (multipart/form-data)

Parameter	Values	Default
`file`	PDF file (required)	—
`output_format`	json, docx, md, html	json
`ocr_lang`	eng, ara, ara,eng	eng
`table_mode`	fast, accurate	accurate

Curl Example

curl -X POST https://docling-api.com/api/v1/convert \
  -H "X-Api-Key: doc_your_key" \
  -F "file=@invoice.pdf" \
  -F "output_format=json" \
  -F "ocr_lang=ara,eng"

Python Example

import requests
res = requests.post(
    "https://docling-api.com/api/v1/convert",
    headers={"X-Api-Key": "doc_your_key"},
    files={"file": open("invoice.pdf", "rb")},
    data={"output_format": "json", "ocr_lang": "ara,eng"}
)
print(res.json())  # {"task_id": "tsk_a1b2c3d4", "status": "queued"}

Response (200)

{"task_id": "tsk_a1b2c3d4", "status": "queued"}

GET/api/v1/result/:task_id

Poll for result. Requires API key.

curl -H "X-Api-Key: doc_your_key" \
  https://docling-api.com/api/v1/result/tsk_a1b2c3d4

Response — Processing

{"task_id": "tsk_a1b2c3d4", "status": "processing", "processing_time": null}

Response — Done (JSON)

{
  "task_id": "tsk_a1b2c3d4",
  "status": "done",
  "document": {
    "tables": [{ "page": 1, "headers": ["Item","Qty"],
      "rows": [["Widget","5"]] }],
    "markdown": "## Invoice\n\n..."
  },
  "processing_time": 3.2
}

Response — Failed

{
  "task_id": "tsk_a1b2c3d4",
  "status": "failed",
  "error_message": "Docling failed: ..."
}

GET/api/v1/download/:task_id

Download a DOCX result. Requires API key.

curl -H "X-Api-Key: doc_your_key" \
  https://docling-api.com/api/v1/download/tsk_a1b2c3d4 \
  -o result.docx