Implementation:Ucbepic Docetl ServerConvertRoutes

Knowledge Sources	Ucbepic_Docetl
Domains	Data_Processing, Web_API, Document_Conversion
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for FastAPI routes that convert uploaded documents to Markdown using multiple backends provided by DocETL.

Description

The convert routes module provides a FastAPI endpoint (/api/convert-documents) for converting uploaded documents (PDF, DOCX, TXT, MD) into Markdown format. It supports a tiered conversion strategy: first attempting a custom Docling server URL (if provided via header), then the hosted Modal endpoint (if use_docetl_server is true), and finally falling back to local processing using the Docling library with pypdfium2 backend. The module also includes Azure Document Intelligence integration with both the prebuilt-read and prebuilt-layout models for OCR and layout analysis of PDFs, with a 200-page limit check. Text and Markdown files are handled directly without conversion.

Usage

Use this endpoint from the DocETL web UI to convert uploaded documents (PDFs, DOCX files) into Markdown text that can then be used as pipeline input data.

Code Reference

Source Location

• Repository: Ucbepic_Docetl
• File: server/app/routes/convert.py
• Lines: 1-399

Signature

router = APIRouter()

def get_pdf_page_count(file_path: str) -> int: ...

def process_document_with_azure_read(file_path: str, endpoint: str, key: str) -> str: ...

def process_document_with_azure_layout(file_path: str, endpoint: str, key: str) -> str: ...

@router.post("/api/convert-documents")
async def convert_documents(
    files: list[UploadFile] = File(...),
    use_docetl_server: str = "false",
    custom_docling_url: str | None = Header(None),
): ...

Import

from server.app.routes.convert import router

I/O Contract

Inputs

Name	Type	Required	Description
files	list[UploadFile]	Yes	List of uploaded document files to convert
use_docetl_server	str	No	"true" or "false" to use the hosted Modal endpoint (default: "false")
custom_docling_url	str or None	No	Custom Docling server URL (passed via HTTP header)
file_path	str	Yes	Local path to a PDF file (for Azure processing functions)
endpoint	str	Yes	Azure Document Intelligence endpoint URL
key	str	Yes	Azure API key

Outputs

Name	Type	Description
documents	list[dict]	List of {"filename": str, "markdown": str} objects with converted content
error	str	Error message if conversion failed
extracted_text	str	Raw extracted text from Azure Document Intelligence

Usage Examples

import httpx

# Convert uploaded PDF documents to Markdown
async with httpx.AsyncClient() as client:
    with open("report.pdf", "rb") as f:
        response = await client.post(
            "http://localhost:8000/api/convert-documents",
            files=[("files", ("report.pdf", f, "application/pdf"))],
            data={"use_docetl_server": "false"},
        )

    result = response.json()
    for doc in result["documents"]:
        print(f"Converted {doc['filename']}: {len(doc['markdown'])} chars")

Related Pages

• Environment:Ucbepic_Docetl_Python_Runtime