Document Input Methods#

Docling and docling-serve support five primary input mechanisms for feeding documents into the conversion pipeline: file paths/URLs, in-memory streams (DocumentStream), HttpSource (URL + custom headers), multipart file uploads, and base64-encoded payloads (FileSource). The right choice depends on whether you're using the Python library directly or the REST API.

Python Library: DocumentConverter#

DocumentConverter.convert() and convert_all() accept a Union[Path, str, DocumentStream, HttpSource] per source 1. There is also convert_string() for Markdown, HTML, and DocLang content passed directly as a Python string.

DocumentStream wraps a BytesIO object with a name field 2. It is the common currency across the stack — every other input type is ultimately resolved to a DocumentStream before processing.

HttpSource adds a headers: dict[str, Any] field on top of the URL 3. Per-source headers in convert_all() override the batch-level headers argument on a per-key basis 4.

URL resolution lives in docling_core/utils/file.py. resolve_source_to_stream() handles HTTP download (with redirect-safety validation, Google Docs URL rewriting, and optional max_file_size enforcement), while resolve_source_to_path() wraps it to write the result to disk. Filename derivation for remote sources prefers the Content-Disposition header, then falls back to the URL path basename, then to "file" 5.

REST API: docling-serve Endpoints#

docling-serve exposes two distinct endpoint families depending on how the document bytes arrive 6:

/v1/convert/source — JSON body sources#

The sources array in the request body is a tagged union; each element carries a kind discriminator. Supported source kinds 7:

• HttpSource (kind: "http") — a URL with optional custom headers 8. The server fetches the document on behalf of the caller.
• FileSource (kind: "file") — base64-encoded file bytes plus a filename 9. Use base64 -w 0 /path/to/file.pdf to encode. The server decodes it to a DocumentStream via FileSource.to_document_stream().
• Cloud storage coordinates — S3Coordinates, AzureBlobCoordinates, GoogleCloudStorageCoordinates, GoogleDriveCoordinates 10. Each carries the necessary credentials and a key prefix to enumerate and fetch documents from the respective storage backend.

/v1/convert/file — multipart upload#

The process_file handler 11 accepts a list[UploadFile] via multipart/form-data. Each uploaded file is read into a BytesIO buffer and wrapped in a DocumentStream using the upload's filename 12. Conversion options are passed as additional form fields alongside the file(s). The maximum number of files per request is enforced by the service policy (max_sources_per_request).

Source Resolution Flow#

Client input
  ├── Path / str URL → resolve_source_to_stream() → DocumentStream
  ├── DocumentStream → passes through directly
  ├── HttpSource → resolve_source_to_stream() with headers → DocumentStream
  ├── FileSource (base64) → base64.b64decode() → BytesIO → DocumentStream
  └── UploadFile (multipart) → file.read() → BytesIO → DocumentStream

All paths converge on DocumentStream before reaching any pipeline backend 2.

Key Source Files#