# API Server <span class="version-badge">v4.0.0</span>

Kreuzberg runs as an HTTP REST API server (`kreuzberg serve`) or as an MCP server (`kreuzberg mcp`) for AI agent integration.

## HTTP REST API

### Start

=== "CLI"

    --8<-- "snippets/api_server/cli.md"

=== "Docker"

    --8<-- "snippets/api_server/docker.md"

=== "Python"

    --8<-- "snippets/api_server/python.md"

=== "Rust"

    --8<-- "snippets/api_server/rust.md"

=== "Go"

    --8<-- "snippets/api_server/go.md"

=== "Java"

    --8<-- "snippets/api_server/java.md"

=== "C#"

    --8<-- "snippets/api_server/csharp.md"

### Endpoints

#### POST /extract

Extract text from uploaded files via multipart form data.

| Field           | Required         | Description                                      |
| --------------- | ---------------- | ------------------------------------------------ |
| `files`         | Yes (repeatable) | Files to extract                                 |
| `config`        | No               | JSON config overrides                            |
| `output_format` | No               | `plain` (default), `markdown`, `djot`, or `html` |

```bash title="Terminal"
# Single file
curl -F "files=@document.pdf" http://localhost:8000/extract

# Multiple files
curl -F "files=@doc1.pdf" -F "files=@doc2.docx" http://localhost:8000/extract

# With config overrides
curl -F "files=@scanned.pdf" \
     -F 'config={"ocr":{"language":"eng"},"force_ocr":true}' \
     http://localhost:8000/extract
```

```json title="Response"
[
  {
    "content": "Extracted text...",
    "mime_type": "application/pdf",
    "metadata": { "page_count": 10, "author": "John Doe" },
    "tables": [],
    "detected_languages": ["eng"],
    "chunks": null,
    "images": null
  }
]
```

#### POST /embed

Generate vector embeddings. Requires the `embeddings` feature.

| Field    | Required | Description                |
| -------- | -------- | -------------------------- |
| `texts`  | Yes      | Array of strings           |
| `config` | No       | Embedding config overrides |

```bash title="Terminal"
curl -X POST http://localhost:8000/embed \
  -H "Content-Type: application/json" \
  -d '{"texts":["Hello world","Second text"]}'
```

| Preset               | Dimensions | Model              |
| -------------------- | ---------- | ------------------ |
| `fast`               | 384        | AllMiniLML6V2Q     |
| `balanced` (default) | 768        | BGEBaseENV15       |
| `quality`            | 1024       | BGELargeENV15      |
| `multilingual`       | 768        | MultilingualE5Base |

#### POST /chunk

Chunk text for RAG pipelines.

| Field                   | Required | Description                                                 |
| ----------------------- | -------- | ----------------------------------------------------------- |
| `text`                  | Yes      | Text to chunk                                               |
| `chunker_type`          | No       | `"text"` (default), `"markdown"`, `"yaml"`, or `"semantic"` |
| `config.max_characters` | No       | Max chars per chunk (default: 2000)                         |
| `config.overlap`        | No       | Overlap between chunks (default: 100)                       |

```bash title="Terminal"
curl -X POST http://localhost:8000/chunk \
  -H "Content-Type: application/json" \
  -d '{"text":"Long text...","chunker_type":"text","config":{"max_characters":1000,"overlap":50}}'
```

=== "Python"

    --8<-- "snippets/python/api/client_chunk_text.md"

=== "TypeScript"

    --8<-- "snippets/typescript/api/client_chunk_text.md"

=== "Rust"

    --8<-- "snippets/rust/api/client_chunk_text.md"

=== "Go"

    --8<-- "snippets/go/api/client_chunk_text.md"

=== "Java"

    --8<-- "snippets/java/api/client_chunk_text.md"

=== "C#"

    --8<-- "snippets/csharp/client_chunk_text.md"

=== "Ruby"

    --8<-- "snippets/ruby/api/client_chunk_text.md"

#### POST /extract-structured <span class="version-badge">v4.8.0</span>

Extract typed JSON from a document by running an LLM against the extracted text with a JSON schema (requires `liter-llm` feature; `multipart/form-data` request).

| Field               | Required | Description                                                                                        |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `file` (or `files`) | Yes      | The document to extract from                                                                       |
| `schema`            | Yes      | JSON Schema string describing the structured output                                                |
| `model`             | Yes      | LLM model identifier, for example `openai/gpt-4o` or `anthropic/claude-sonnet-4-20250514`          |
| `api_key`           | No       | LLM provider API key. Falls back to provider env vars (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, ...) |
| `prompt`            | No       | Custom Jinja2 prompt template overriding the default                                               |
| `schema_name`       | No       | Schema identifier (default: `extraction`)                                                          |
| `strict`            | No       | `"true"` / `"false"` — enable OpenAI strict mode for exact schema matching                         |
| `config`            | No       | Extraction config overrides as a JSON string                                                       |

```bash title="Terminal"
curl -X POST http://localhost:8000/extract-structured \
  -F "file=@invoice.pdf" \
  -F 'schema={"type":"object","properties":{"invoice_number":{"type":"string"},"total":{"type":"number"}},"required":["invoice_number","total"]}' \
  -F "model=openai/gpt-4o" \
  -F "api_key=$OPENAI_API_KEY" \
  -F "strict=true"
```

```json title="Response"
{
  "structured_output": {
    "invoice_number": "INV-2026-0142",
    "total": 1284.5
  },
  "content": "Invoice INV-2026-0142...",
  "mime_type": "application/pdf"
}
```

Errors follow the same shape as `/extract`. A `501` response indicates the server was built without `liter-llm`.

#### Other Endpoints

| Endpoint          | Method | Description                                                               |
| ----------------- | ------ | ------------------------------------------------------------------------- |
| `/health`         | GET    | `{"status":"healthy","version":"4.6.3"}`                                  |
| `/version`        | GET    | `{"version":"4.6.3"}` <span class="version-badge">v4.5.2</span>           |
| `/detect`         | POST   | MIME type detection (multipart) <span class="version-badge">v4.5.2</span> |
| `/cache/stats`    | GET    | Cache statistics                                                          |
| `/cache/warm`     | POST   | Pre-download models <span class="version-badge">v4.5.2</span>             |
| `/cache/manifest` | GET    | Model manifest with checksums <span class="version-badge">v4.5.2</span>   |
| `/cache/clear`    | DELETE | Clear all cached files                                                    |
| `/info`           | GET    | `{"version":"...","rust_backend":true}`                                   |
| `/openapi.json`   | GET    | OpenAPI 3.0 schema                                                        |

### Client Examples

=== "Python"

    --8<-- "snippets/python/api/client_extract_single_file.md"

=== "TypeScript"

    --8<-- "snippets/typescript/getting-started/client_extract_single_file.md"

=== "Rust"

    --8<-- "snippets/rust/api/client_extract_single_file.md"

=== "Go"

    --8<-- "snippets/go/api/client_extract_single_file.md"

=== "Java"

    --8<-- "snippets/java/api/client_extract_single_file.md"

=== "C#"

    --8<-- "snippets/csharp/client_extract_single_file.md"

=== "Ruby"

    --8<-- "snippets/ruby/api/client_extract_single_file.md"

### Error Handling

```json title="Error response"
{
  "error_type": "ValidationError",
  "message": "Invalid file format",
  "status_code": 400
}
```

| Status | Error type                 | Meaning           |
| ------ | -------------------------- | ----------------- |
| 400    | `ValidationError`          | Invalid input     |
| 422    | `ParsingError`, `OcrError` | Processing failed |
| 500    | Internal errors            | Server errors     |

=== "Python"

    --8<-- "snippets/python/utils/error_handling_extract.md"

=== "TypeScript"

    --8<-- "snippets/typescript/api/error_handling_extract.md"

=== "Rust"

    --8<-- "snippets/rust/api/error_handling_extract.md"

=== "Go"

    --8<-- "snippets/go/api/error_handling_extract.md"

=== "Java"

    --8<-- "snippets/java/api/error_handling_extract.md"

=== "C#"

    --8<-- "snippets/csharp/error_handling_extract.md"

=== "Ruby"

    --8<-- "snippets/ruby/api/error_handling_extract.md"

### Configuration

The server discovers `kreuzberg.toml` in the current and parent directories. Pass `--config path/to/file` to use a different file.

| Variable                       | Default | Description                     |
| ------------------------------ | ------- | ------------------------------- |
| `KREUZBERG_MAX_UPLOAD_SIZE_MB` | `100`   | Max upload size in MB           |
| `KREUZBERG_CORS_ORIGINS`       | `*`     | Comma-separated allowed origins |

!!! Warning Default CORS allows all origins. Set `KREUZBERG_CORS_ORIGINS` explicitly in production.

See [Configuration Guide](configuration.md) for all options.

---

## MCP Server

### Start

```bash title="Terminal"
kreuzberg mcp
kreuzberg mcp --config kreuzberg.toml
```

=== "Python"

    --8<-- "snippets/python/mcp/mcp_server_start.md"

=== "TypeScript"

    --8<-- "snippets/typescript/mcp/mcp_server_start.md"

=== "Rust"

    --8<-- "snippets/rust/mcp/mcp_server_start.md"

=== "Go"

    --8<-- "snippets/go/mcp/mcp_server_start.md"

=== "Java"

    --8<-- "snippets/java/mcp/mcp_server_start.md"

=== "C#"

    --8<-- "snippets/csharp/mcp_server_start.md"

=== "Ruby"

    --8<-- "snippets/ruby/mcp/mcp_server_start.md"

### Tools

| Tool                  | Key parameters                                                                                                                                    | Description                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `extract_file`        | `path`                                                                                                                                            | Extract from file path                                                    |
| `extract_bytes`       | `data` (base64)                                                                                                                                   | Extract from encoded bytes                                                |
| `batch_extract_files` | `paths`                                                                                                                                           | Extract multiple files                                                    |
| `detect_mime_type`    | `path`                                                                                                                                            | Detect file format                                                        |
| `list_formats`        | —                                                                                                                                                 | List supported formats <span class="version-badge">v4.5.2</span>          |
| `get_version`         | —                                                                                                                                                 | Library version <span class="version-badge">v4.5.2</span>                 |
| `cache_stats`         | —                                                                                                                                                 | Cache usage                                                               |
| `cache_clear`         | —                                                                                                                                                 | Remove cached files                                                       |
| `cache_manifest`      | —                                                                                                                                                 | Model checksums <span class="version-badge">v4.5.2</span>                 |
| `cache_warm`          | —                                                                                                                                                 | Pre-download models <span class="version-badge">v4.5.2</span>             |
| `embed_text`          | `texts`                                                                                                                                           | Generate embeddings <span class="version-badge">v4.5.2</span>             |
| `chunk_text`          | `text`                                                                                                                                            | Split text <span class="version-badge">v4.5.2</span>                      |
| `extract_structured`  | `path`, `schema`, `model`; optional `schema_name` (default `"extraction"`), `schema_description`, `prompt`, `api_key`, `strict` (default `false`) | Extract structured JSON via LLM <span class="version-badge">v4.8.0</span> |

All tools accept an optional `config` object. `extract_file` and `extract_bytes` also accept `pdf_password`. `extract_structured` requires the server to be built with the `liter-llm` feature; see the row above for optional fields and defaults.

### AI Agent Integration

=== "Claude Desktop"

    Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "kreuzberg": {
          "command": "kreuzberg",
          "args": ["mcp"]
        }
      }
    }
    ```

=== "Python"

    --8<-- "snippets/python/mcp/mcp_custom_client.md"

=== "LangChain"

    --8<-- "snippets/python/mcp/mcp_langchain_integration.md"

=== "TypeScript"

    --8<-- "snippets/typescript/mcp/mcp_custom_client.md"

=== "Rust"

    --8<-- "snippets/rust/mcp/mcp_custom_client.md"

=== "Go"

    --8<-- "snippets/go/mcp/mcp_custom_client.md"

=== "Java"

    --8<-- "snippets/java/mcp/mcp_client.md"

=== "C#"

    --8<-- "snippets/csharp/mcp_custom_client.md"

=== "Ruby"

    --8<-- "snippets/ruby/mcp/mcp_custom_client.md"

---

For Docker and Kubernetes deployment, see [Docker Guide](docker.md) and [Kubernetes Guide](kubernetes.md).