Skip to content

A fast, helpful, and open-source document parser

docs: add liteparse server docs

Clelia (Astra) Bertelliea414ab81bf9
diff --git a/docs/src/content/docs/liteparse/guides/server-usage.md b/docs/src/content/docs/liteparse/guides/server-usage.md
new file mode 100644
index 0000000..8a32385
--- /dev/null
+++ b/docs/src/content/docs/liteparse/guides/server-usage.md
@@ -0,0 +1,166 @@
+---
+title: Server Usage
+description: Run LiteParse as an HTTP service with liteparse-server.
+sidebar:
+ order: 7
+---
+
+[`liteparse-server`](https://github.com/run-llama/liteparse-server) is an Express server that exposes [`@llamaindex/liteparse`](https://www.npmjs.com/package/@llamaindex/liteparse) as an HTTP parsing backend. It lets you run LiteParse as a standalone service, which is useful when your application isn't Node.js, when you want to share one parsing instance across multiple clients, or when you need a parsing endpoint behind your own infrastructure.
+
+The server ships in two flavours:
+
+- **Slim** — a minimal build with no external dependencies, ideal for getting started or embedding in your own stack.
+- **Full** — an all-in-one setup with built-in **Redis caching and rate limiting**, **OpenTelemetry tracing** (Jaeger), and **metrics** (Prometheus + Grafana), wired together with Docker Compose.
+
+Both expose the same two endpoints: `POST /parse` and `POST /screenshots`.
+
+## Requirements
+
+- [Bun](https://bun.sh) ≥ 1.0 (or Node.js)
+- [Docker](https://docs.docker.com/get-docker/) and Docker Compose (only required for the full server setup)
+
+## Slim server
+
+[`src/slim.ts`](https://github.com/run-llama/liteparse-server/tree/main/src/slim.ts) is a minimal version of the server that removes caching and observability while keeping rate limiting and logging. It needs no Redis, no OpenTelemetry collector, and no supporting services.
+
+### Running locally
+
+After cloning the GitHub repository:
+
+```bash
+git clone https://github.com/run-llama/liteparse-server
+cd liteparse-server
+```
+
+You can run the API server with either Bun or Node:
+
+```bash
+bun run start-slim:bun
+# or with Node
+npm run start-slim:node
+```
+
+The server listens on **port 5000**.
+
+### Running with Docker
+
+**Pre-built image**
+
+You can pull the pre-built LiteParse (slim) server image from the GitHub Container Registry:
+
+```bash
+docker pull ghcr.io/run-llama/liteparse-server:main
+```
+
+You can then run it exposing port 5000:
+
+```bash
+docker run -p 5000:5000 ghcr.io/run-llama/liteparse-server:main
+```
+
+**Build locally**
+
+If you clone the repository, the provided [`slim.Dockerfile`](https://github.com/run-llama/liteparse-server/tree/main/slim.Dockerfile) produces a self-contained image:
+
+```bash
+# Build the image
+docker build -f slim.Dockerfile -t liteparse-server-slim .
+
+# Run exposing port 5000
+docker run -p 5000:5000 liteparse-server-slim
+```
+
+The API is then available at **http://localhost:5000**.
+
+## Full server
+
+For a production-style deployment with caching, rate limiting, distributed tracing, and metrics, follow the Docker Compose example in [`examples/docker-compose`](https://github.com/run-llama/liteparse-server/tree/main/examples/docker-compose). It brings up the server alongside Redis, the OpenTelemetry Collector, Jaeger, Prometheus, and Grafana.
+
+## API specification
+
+Base URL: `http://localhost:5000`
+
+### `POST /parse` — parse a single file
+
+Parses a single document and returns either structured page data or plain text.
+
+**Form fields:**
+
+| Field | Type | Required | Description |
+| -------- | ------ | -------- | ----------------------------------------- |
+| `file` | file | Yes | The document to parse |
+| `config` | string | No | JSON-serialized `LiteParseConfig` options |
+
+**Query parameters:**
+
+| Parameter | Type | Default | Description |
+| --------- | ------- | ------- | ---------------------------------------------------------------------------------- |
+| `text` | boolean | `false` | If `true`, returns `text/plain`; otherwise `application/json` with a `pages` array |
+
+**Responses:**
+
+- `200 text/plain` — extracted text (when `text=true`)
+- `200 application/json` — `{ "pages": [...] }` (when `text=false`)
+- `400` — missing `file`
+- `429` — rate limit exceeded (only if rate limiting is configured)
+
+### `POST /screenshots` — screenshot pages of a document
+
+Renders document pages as PNG images and streams them back as newline-delimited JSON (NDJSON).
+
+**Form fields:**
+
+| Field | Type | Required | Description |
+| -------- | ------ | -------- | ----------------------------------------- |
+| `file` | file | Yes | The document to screenshot |
+| `config` | string | No | JSON-serialized `LiteParseConfig` options |
+
+**Query parameters:**
+
+| Parameter | Type | Default | Description |
+| --------- | ------ | ------- | ----------------------------------------------------------------- |
+| `pages` | string | all | Comma-separated 1-based page numbers to screenshot (e.g. `1,2,3`) |
+
+**Response `200 application/x-ndjson`** — one JSON object per line:
+
+```json
+{
+ "index": 0,
+ "mimetype": "image/png",
+ "data": "<base64>",
+ "page_number": 1,
+ "height": 1056,
+ "width": 816
+}
+```
+
+## Example usage with `curl`
+
+Parse a file and get JSON pages:
+
+```bash
+curl -X POST http://localhost:5000/parse \
+ -F "file=@path/to/document.pdf"
+```
+
+Parse a file and get plain text:
+
+```bash
+curl -X POST "http://localhost:5000/parse?text=true" \
+ -F "file=@path/to/document.pdf"
+```
+
+Pass a `LiteParseConfig` (e.g. enable OCR):
+
+```bash
+curl -X POST http://localhost:5000/parse \
+ -F "file=@path/to/document.pdf" \
+ -F 'config={"ocrEnabled":true}'
+```
+
+Screenshot specific pages and stream NDJSON:
+
+```bash
+curl -X POST "http://localhost:5000/screenshots?pages=1,2,3" \
+ -F "file=@path/to/document.pdf"
+```