---
title: "Deploy MarkItDown API"
description: "Converts files to Markdown via REST API, secured with Bearer auth."
category: "Other"
url: https://railway.com/deploy/markitdown-api
---

# Deploy MarkItDown API

Converts files to Markdown via REST API, secured with Bearer auth.

**[Deploy MarkItDown API on Railway](https://railway.com/template/markitdown-api)**

- **Creator:** SuperSlowSloth
- **Category:** Other
- **Total deploys:** 7

## Template content

### MarkItDown API

- **Image:** ghcr.io/bon5co/markitdown-api-auth:latest
- **Health check:** /
- **Public domain:** Yes

## Documentation

# 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)](https://github.com/microsoft/markitdown) — the core document conversion library
- [FastAPI](https://fastapi.tiangolo.com/) — the web framework powering the API
- [Uvicorn](https://www.uvicorn.org/) — the ASGI server used to run the application
- [Pre-built Docker image on GHCR](https://github.com/dezoito/markitdown-api/pkgs/container/markitdown-api) — `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:

```python
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:

```json
{ "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.



## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/markitdown-api