Classic298
e08e395937
People wiring scripts, bots and agents into Open WebUI keep hitting the same wall: they send a prompt with tool_ids, get a raw tool_calls object back, and have no way to execute a builtin tool like web search or the code interpreter from their own process. Nothing in the docs said which request fields decide whether Open WebUI runs the tools for you. The new Reference page spells that out. `/api/chat/completions` behaves in three different ways and the request body picks which one: the native multi-round loop needs `chat_id`, `id` and `stream: true` and returns its answer through the chat record rather than the HTTP body; `session_id` is what makes the builtin tools available at all; legacy function calling runs one round inline and returns everything in the response. It also flags that a model's configured terminal is applied by the frontend, so an API caller has to send `terminal_id` itself. It is written as two end-to-end paths, full agentic loop and single request, each with the calls in order, both streaming and non-streaming, both with and without the chat being saved, and a reusable Python script at the end. Reference lives in Reference rather than Tutorials because this is core API behaviour, not a community integration.
5.9 KiB
sidebar_position, title
| sidebar_position | title |
|---|---|
| 150 | Reference |
import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl';
Reference
<ThemedImage alt="Open WebUI Reference: canonical technical map for environment variables, API endpoints, HTTPS, monitoring, and network diagrams" sources={{ light: useBaseUrl('/images/banners/reference-light.svg'), dark: useBaseUrl('/images/banners/reference-dark.svg'), }} style={{ width: '100%', margin: '0.25rem 0 1.75rem' }} />
The technical details behind every knob, endpoint, and configuration option.
Open WebUI is highly configurable. This section is the canonical source of truth for environment variables, API endpoints, network architecture, reverse proxy setups, and production monitoring. Whether you're tuning a single setting or architecting a multi-node deployment, start here.
⚙️ Environment Variable Configuration
Every flag, path, and secret Open WebUI reads at startup, in one place.
Over 200 environment variables control authentication, model routing, storage, logging, and more. Understand ConfigVar behavior, troubleshoot ignored settings, and find the exact variable you need.
| 🔐 Authentication & signup | ENABLE_SIGNUP, ENABLE_LOGIN_FORM, WEBUI_ADMIN_EMAIL, OIDC/LDAP/SCIM |
| 🤖 Model connections | Ollama, OpenAI, direct pipeline URLs, timeouts, load balancing |
| 💾 Storage & databases | SQLite, PostgreSQL, S3/GCS/Azure Blob, Redis |
| 📊 Logging & audit | GLOBAL_LOG_LEVEL, JSON logging, audit log levels and paths |
| 🧠 RAG & retrieval | Chunk size, overlap, embedding engines, reranking, vector DB selection |
Browse all environment variables →
🔌 API Endpoints
OpenAI-compatible and Anthropic-compatible APIs, plus RAG, file management, and Ollama proxy routes.
Open WebUI exposes a full REST API authenticated via Bearer tokens or JWTs. Use the same endpoints the web UI uses to build automations, chatbots, and custom integrations.
| 💬 Chat completions | POST /api/chat/completions, OpenAI-compatible |
| 🔮 Anthropic messages | POST /api/v1/messages, works with the Anthropic SDK and Claude Code |
| 🦙 Ollama proxy | /ollama/api/*, passthrough to native Ollama endpoints |
| 📄 File & knowledge | Upload files, build knowledge collections, query via RAG |
| 🔧 Filters (inlet/stream/outlet) | Inlet, stream, and outlet hooks for every request |
🤖 Server-Side Tool Calling
Send a prompt, have Open WebUI run the tools, get the finished answer back.
Every request you need to make the model call built-in tools, workspace tools, MCP servers and Open Terminal on the server, with your user's own permissions. Streaming and non-streaming, with and without saving the chat, ending in a reusable script.
| 🔁 Full agentic loop | Multi-round native tool calling, result read back from the chat |
| ⚡ Single-request mode | One HTTP call in, one completion out, tool results already applied |
| 🧭 Field-by-field | chat_id, id, session_id, tool_ids, terminal_id, features |
🔒 HTTPS Configuration
Terminate TLS in front of Open WebUI with Nginx, Caddy, or HAProxy.
Step-by-step reverse proxy configurations for securing your deployment with HTTPS. Each guide includes certificate handling, WebSocket support, and production-hardened settings.
| 🟢 Nginx | Full config with SSL termination, WebSocket proxying, and headers |
| ⚡ Caddy | Automatic HTTPS with minimal configuration |
| 🔄 HAProxy | Enterprise-grade load balancing with TLS offloading |
| ☁️ Cloudflare Tunnel | Expose Open WebUI securely without opening ports |
| 🔒 Tailscale | Private encrypted access across your devices, no public exposure |
| 🧪 ngrok | Instant HTTPS tunnels for development and testing |
🔑 API Keys
Programmatic access to Open WebUI for scripts, bots, and integrations.
Generate personal access tokens that let external code call the same endpoints the web UI uses. Each key inherits the permissions of the user who created it.
| 🔐 Bearer token auth | Standard Authorization: Bearer header, works with any HTTP client |
| 🛡️ Scoped to user | Key inherits your role and group permissions |
| 🚫 Endpoint restrictions | Optionally limit which API routes a key can access |
📊 Monitoring
Observe your deployment with Uptime Kuma, OpenTelemetry, Prometheus, and Grafana.
Production monitoring guides covering health checks, model connectivity verification, distributed tracing, metrics, and structured logs. Integrate with your existing observability stack or set up a new one from scratch.
| ✅ Health checks | Basic, model connectivity, and deep health checks with Uptime Kuma |
| 📡 OpenTelemetry | Traces, metrics, and logs piped to any OTLP-compatible backend |
| 📈 Dashboards | Prometheus + Grafana for real-time system and model metrics |
🌐 Network Diagrams
See how Open WebUI, Ollama, and Docker communicate across different deployment topologies.
Visual C4 diagrams covering host networking, Docker Compose stacks, separate networks, and platform-specific differences. Useful for debugging connectivity issues or planning your architecture.
| 🖥️ macOS / Windows | Host Ollama, Compose stack, separate networks, host-network pitfalls |
| 🐧 Linux | Same topologies with Linux-specific networking behavior |