Settings API

Endpoints for managing conversion settings.

Session-Based Storage

Settings are stored per-user session in the database. Each user's settings are isolated and don't affect other users, making Duckling safe for multi-user deployments.

Deploy-time options (DUCKLING_API_KEY, orchestration engine, logging) are documented in Server Configuration.

Pipeline and PDF settings

Duckling exposes docling-serve–aligned pipeline and PDF endpoints:

GET/PUT /api/settings/pipeline — standard, vlm, or asr pipeline kind; VLM preset selection
GET/PUT /api/settings/pdf — PDF backend, image export mode, heading hierarchy

Get pipeline settings

GET /api/settings/pipeline

{
  "pipeline": {
    "kind": "standard",
    "vlm_preset": "default",
    "vlm_custom_config": null,
    "force_backend_text": false
  },
  "options": {
    "kind": ["standard", "vlm", "asr"],
    "vlm_presets": ["default"],
    "allow_custom_vlm_config": false
  }
}

Update pipeline settings

PUT /api/settings/pipeline
Content-Type: application/json

{
  "kind": "vlm",
  "vlm_preset": "default"
}

Field	Values	Notes
`kind`	`standard`, `vlm`, `asr`	ASR applies to audio/video inputs when Docling ASR classes are available
`vlm_preset`	Docling preset name	Used when `kind=vlm`
`vlm_custom_config`	object	Applied only when server flag `allow_custom_vlm_config` is enabled

Get PDF settings

GET /api/settings/pdf

{
  "pdf": {
    "pdf_backend": "docling_parse",
    "image_export_mode": "placeholder",
    "do_pdf_heading_hierarchy": false,
    "pdf_heading_hierarchy_options": {
      "use_bookmarks": true,
      "use_numbering": true,
      "use_style": true,
      "max_level": 6
    }
  },
  "options": {
    "pdf_backend": ["docling_parse", "pypdfium2"],
    "image_export_mode": ["placeholder", "embedded", "referenced"]
  }
}

Update PDF settings

PUT /api/settings/pdf
Content-Type: application/json

{
  "pdf_backend": "pypdfium2",
  "image_export_mode": "embedded",
  "do_pdf_heading_hierarchy": true
}

Advanced chunking settings

GET/PUT /api/settings/chunking supports hybrid and hierarchical Docling chunkers:

Field	Type	Default	Description
`enabled`	boolean	`false`	Generate `.chunks.json` during conversion
`chunker`	string	`hybrid`	`hybrid` or `hierarchical`
`max_tokens`	integer	`512`	Target chunk size
`merge_peers`	boolean	`true`	Merge adjacent small chunks
`tokenizer`	string	`sentence-transformers/all-MiniLM-L6-v2`	Hugging Face tokenizer id
`use_markdown_tables`	boolean	`false`	Serialize tables as markdown in chunks
`use_markdown_images`	boolean	`false`	Serialize images as markdown in chunks
`image_placeholder`	string	`[image]`	Placeholder text for images in chunks
`include_raw_text`	boolean	`false`	Include `raw_text` field on chunk objects

Example

curl -X PUT http://localhost:5001/api/settings/chunking \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "chunker": "hierarchical",
    "max_tokens": 768,
    "include_raw_text": true
  }'

The Settings UI exposes enabled, max_tokens, and merge_peers; advanced fields are available via API.

Get All Settings

GET /api/settings

Response

{
  "ocr": {
    "enabled": true,
    "language": "en",
    "backend": "easyocr",
    "mode": "default",
    "scale": 3.0,
    "force_full_page_ocr": false,
    "use_gpu": false,
    "confidence_threshold": 0.5
  },
  "tables": {
    "enabled": true,
    "structure_extraction": true,
    "mode": "accurate",
    "do_cell_matching": true
  },
  "images": {
    "extract": true,
    "classify": true,
    "generate_page_images": false,
    "generate_picture_images": true,
    "generate_table_images": true,
    "images_scale": 1.0
  },
  "enrichment": {
    "code_enrichment": false,
    "formula_enrichment": false,
    "picture_classification": false,
    "picture_description": false
  },
  "output": {
    "default_format": "markdown"
  },
  "performance": {
    "device": "auto",
    "num_threads": 4,
    "document_timeout": null
  },
  "chunking": {
    "enabled": false,
    "max_tokens": 512,
    "merge_peers": true
  }
}

Update Settings

PUT /api/settings
Content-Type: application/json

Request Body

{
  "ocr": {
    "language": "de",
    "backend": "tesseract"
  },
  "tables": {
    "mode": "fast"
  }
}

Response

Returns the updated settings object.

Reset Settings to Defaults

POST /api/settings/reset

Response

Returns the default settings object.

Get Supported Formats

GET /api/settings/formats

Response

{
  "input_formats": [
    {"id": "pdf", "name": "PDF Document", "extensions": [".pdf"], "icon": "document"},
    {"id": "docx", "name": "Microsoft Word", "extensions": [".docx"], "icon": "document"},
    {"id": "image", "name": "Image", "extensions": [".png", ".jpg", ".jpeg", ".tiff"], "icon": "image"}
  ],
  "output_formats": [
    {"id": "markdown", "name": "Markdown", "extension": ".md", "mime_type": "text/markdown"},
    {"id": "html", "name": "HTML", "extension": ".html", "mime_type": "text/html"},
    {"id": "json", "name": "JSON", "extension": ".json", "mime_type": "application/json"},
    {"id": "text", "name": "Plain Text", "extension": ".txt", "mime_type": "text/plain"},
    {"id": "doctags", "name": "DocTags", "extension": ".doctags", "mime_type": "text/plain"},
    {"id": "doclang", "name": "DocLang", "extension": ".dclg.xml", "mime_type": "application/xml"},
    {"id": "document_tokens", "name": "Document Tokens", "extension": ".tokens.json", "mime_type": "application/json"}
  ]
}

OCR Settings

Get OCR Settings

GET /api/settings/ocr

Update OCR Settings

PUT /api/settings/ocr
Content-Type: application/json

Query Parameters:

Parameter	Type	Description
`auto_install`	boolean	If `true`, automatically install pip-installable backends

Response/Request

{
  "ocr": {
    "enabled": true,
    "language": "en",
    "backend": "easyocr",
    "mode": "default",
    "scale": 3.0,
    "force_full_page_ocr": false,
    "use_gpu": false,
    "confidence_threshold": 0.5
  },
  "available_languages": [
    {"code": "en", "name": "English"},
    {"code": "de", "name": "German"},
    {"code": "fr", "name": "French"}
  ],
  "available_backends": [
    {"id": "easyocr", "name": "EasyOCR", "description": "General-purpose OCR with GPU support"},
    {"id": "tesseract", "name": "Tesseract", "description": "Classic OCR engine"},
    {"id": "ocrmac", "name": "macOS Vision", "description": "Native macOS OCR (Mac only)"},
    {"id": "rapidocr", "name": "RapidOCR", "description": "Fast OCR with ONNX runtime"}
  ]
}

OCR Backend Management

Get All Backend Status

GET /api/settings/ocr/backends

Returns installation status for all OCR backends.

Response

{
  "backends": [
    {
      "id": "easyocr",
      "name": "EasyOCR",
      "description": "General-purpose OCR with GPU support",
      "installed": true,
      "available": true,
      "error": null,
      "pip_installable": true,
      "requires_system_install": false,
      "platform": null,
      "note": "First run will download language models (~100MB per language)"
    },
    {
      "id": "tesseract",
      "name": "Tesseract",
      "description": "Classic OCR engine",
      "installed": false,
      "available": false,
      "error": "Package not installed",
      "pip_installable": true,
      "requires_system_install": true,
      "platform": null,
      "note": "Requires Tesseract to be installed on your system"
    }
  ],
  "current_platform": "darwin"
}

Check Specific Backend

GET /api/settings/ocr/backends/{backend_id}/check

Response

{
  "backend": "easyocr",
  "installed": true,
  "available": true,
  "error": null,
  "pip_installable": true,
  "requires_system_install": false,
  "note": "First run will download language models"
}

Install Backend

POST /api/settings/ocr/backends/{backend_id}/install

Installs a pip-installable OCR backend.

Response (Success)

{
  "message": "Successfully installed easyocr",
  "success": true,
  "installed": true,
  "available": true,
  "note": "First run will download language models"
}

Response (Already Installed)

{
  "message": "easyocr is already installed and available",
  "already_installed": true
}

Response (Requires System Install)

{
  "message": "Failed to install tesseract",
  "success": false,
  "error": "tesseract requires system-level installation",
  "requires_system_install": true
}

Table Settings

Get Table Settings

GET /api/settings/tables

Update Table Settings

PUT /api/settings/tables
Content-Type: application/json

Request/Response

{
  "tables": {
    "enabled": true,
    "structure_extraction": true,
    "mode": "accurate",
    "do_cell_matching": true
  }
}

Image Settings

Get Image Settings

GET /api/settings/images

Update Image Settings

PUT /api/settings/images
Content-Type: application/json

Request/Response

{
  "images": {
    "extract": true,
    "classify": true,
    "generate_page_images": false,
    "generate_picture_images": true,
    "generate_table_images": true,
    "images_scale": 1.0
  }
}

Enrichment Settings

Get Enrichment Settings

GET /api/settings/enrichment

Response

{
  "enrichment": {
    "code_enrichment": false,
    "formula_enrichment": false,
    "picture_classification": false,
    "picture_description": false
  },
  "options": {
    "code_enrichment": {
      "description": "Enhance code blocks with language detection and syntax highlighting",
      "default": false,
      "note": "May increase processing time"
    },
    "formula_enrichment": {
      "description": "Extract LaTeX representations from mathematical formulas",
      "default": false,
      "note": "Enables better formula rendering in exports"
    },
    "picture_classification": {
      "description": "Classify images by type (figure, chart, diagram, photo, etc.)",
      "default": false,
      "note": "Adds semantic tags to extracted images"
    },
    "picture_description": {
      "description": "Generate descriptive captions for images using AI vision models",
      "default": false,
      "note": "Requires additional model download, significantly increases processing time"
    }
  }
}

Update Enrichment Settings

PUT /api/settings/enrichment
Content-Type: application/json

Request

{
  "code_enrichment": true,
  "formula_enrichment": true
}

Response

{
  "message": "Enrichment settings updated",
  "enrichment": {
    "code_enrichment": true,
    "formula_enrichment": true,
    "picture_classification": false,
    "picture_description": false
  }
}

Field	Type	Description
`code_enrichment`	boolean	Enhance code blocks with language detection
`formula_enrichment`	boolean	Extract LaTeX from mathematical formulas
`picture_classification`	boolean	Classify images by semantic type
`picture_description`	boolean	Generate AI captions for images

Processing Time

Enabling formula_enrichment and especially picture_description can significantly increase document processing time.

Performance Settings

Get Performance Settings

GET /api/settings/performance

Update Performance Settings

PUT /api/settings/performance
Content-Type: application/json

Request/Response

{
  "performance": {
    "device": "auto",
    "num_threads": 4,
    "document_timeout": null
  }
}

Chunking Settings

Get Chunking Settings

GET /api/settings/chunking

Update Chunking Settings

PUT /api/settings/chunking
Content-Type: application/json

Request/Response

{
  "chunking": {
    "enabled": false,
    "max_tokens": 512,
    "merge_peers": true
  }
}

Output Settings

Get Output Settings

GET /api/settings/output

Update Output Settings

PUT /api/settings/output
Content-Type: application/json

Request/Response

{
  "output": {
    "default_format": "markdown"
  }
}