Deploy and Host MarkItDown API on Railway

MarkItDown API is a lightweight REST API server built with FastAPI that accepts file uploads and converts them to Markdown using Microsoft's MarkItDown library. It supports documents, spreadsheets, presentations, PDFs, and more, returning clean Markdown via a simple HTTP endpoint protected by bearer token authentication.

About Hosting MarkItDown API

Hosting MarkItDown API involves running a Python-based FastAPI application served by Uvicorn. The service runs on port 8490 and requires one environment variable — API_BEARER_TOKEN — to be configured before the server will start. Uploaded files are written to a temporary directory during conversion, then removed immediately after. A pre-built Docker image is published to GitHub Container Registry, making containerized deployment the simplest and recommended path to getting the service running.

Common Use Cases

• Extract and index text from uploaded documents (PDF, DOCX, PPTX, XLSX) into a searchable knowledge base
• Automate conversion of business files to Markdown for ingestion into LLM pipelines or RAG systems
• Provide a shared internal service that normalizes diverse file formats into a single Markdown output for downstream processing

Dependencies for MarkItDown API Hosting

• Python 3.11+ runtime (or Docker)
• API_BEARER_TOKEN environment variable configured to a secure secret value

Deployment Dependencies

• MarkItDown (Microsoft) — the core document conversion library
• FastAPI — the web framework powering the API
• Uvicorn — the ASGI server used to run the application
• Pre-built Docker image on GHCR — ghcr.io/dezoito/markitdown-api:latest

Implementation Details

Start the container with the required token set as an environment variable on port 8490. Once running, send files via a multipart POST request with the token passed as a bearer credential in the request header.

The following Python snippet demonstrates a complete conversion request:

import requests

url = "http://localhost:8490/process_file"
token = "your_secret_token"
file_path = "/path/to/document.pdf"

with open(file_path, "rb") as f:
    response = requests.post(
        url,
        headers={"Authorization": f"Bearer {token}"},
        files={"file": (file_path, f)},
    )

markdown_content = response.json().get("markdown")

The endpoint returns a JSON object containing the converted Markdown:

{ "markdown": "# Document Title\n\nConverted content..." }

Why Deploy MarkItDown API on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying MarkItDown API on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.