rust-pandoc-server

A high-performance Rust REST API that converts any document format to any other format using Pandoc.

Features

• ✅ Full Pandoc API compatibility — mirrors the official pandoc-server JSON API
• ✅ Binary format support — docx, epub, odt, pptx (base64 encoded)
• ✅ Concurrent batch conversion — POST /batch runs all jobs in parallel
• ✅ Swagger UI — interactive docs with X-API-KEY authorization
• ✅ API key auth — X-API-KEY header, configured via .env
• ✅ Docker Compose ready

---

Project Structure

src/
├── main.rs            # Entry point
├── config.rs          # AppConfig from environment
├── error.rs           # PandocError + AppError (axum responder)
├── router.rs          # Route assembly
├── middleware/
│   └── auth.rs        # X-API-KEY validation middleware
├── pandoc/
│   └── engine.rs      # Async pandoc subprocess engine
└── api/
    ├── mod.rs         # OpenAPI spec (utoipa)
    ├── models.rs      # Request / response types
    └── handlers/
        ├── convert.rs # POST /
        ├── batch.rs   # POST /batch
        ├── version.rs # GET /version
        └── babelmark.rs # GET /babelmark

---

Quick Start

Local (requires pandoc installed)

cp .env.example .env
# Edit .env and set API_KEY

cargo run
# Server starts at http://localhost:3000
# Swagger UI at http://localhost:3000/swagger-ui

Docker Compose

cp .env.example .env
# Edit .env and set API_KEY

docker compose up --build

---

API Reference

Authentication

Protected endpoints require an X-API-KEY header:

X-API-KEY: your-secret-key

Endpoints

Method	Path	Auth	Description
POST	/	✅	Convert a single document
POST	/batch	✅	Convert multiple documents at once
GET	/version	❌	Get pandoc version string
GET	/babelmark	❌	Babelmark-compatible endpoint
GET	/swagger-ui	❌	Interactive Swagger UI

Convert: POST /

curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: dev-secret-key" \
  -d '{"text": "# Hello World", "from": "markdown", "to": "html"}'

Response:

{"output": "<h1 id=\"hello-world\">Hello World</h1>\n"}

Binary Format Example (docx → markdown)

BASE64=$(base64 -w 0 document.docx)
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: dev-secret-key" \
  -d "{\"text\": \"$BASE64\", \"from\": \"docx\", \"to\": \"markdown\"}"

Batch: POST /batch

curl -X POST http://localhost:3000/batch \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: dev-secret-key" \
  -d '[{"text":"# A"},{"text":"# B","to":"latex"}]'

Version: GET /version

curl http://localhost:3000/version
# pandoc 3.6.1

Babelmark: GET /babelmark

curl "http://localhost:3000/babelmark?text=# Hello&from=markdown&to=html"

---

Configuration

Variable	Default	Description
API_KEY	required	Secret key for X-API-KEY auth
HOST	0.0.0.0	Bind address
PORT	3000	Bind port
RUST_LOG	info	Log verbosity

---

Supported Formats

All formats supported by your installed pandoc version. See GET /version or run:

pandoc --list-input-formats
pandoc --list-output-formats