Skip to main content

​
API Introduction

The Open WebUI API provides programmatic access to manage users, chats, models, documents, and AI interactions. Built with FastAPI, the API follows RESTful principles and returns JSON-formatted responses.

​
Base URL

The API is served from the same domain as your Open WebUI installation: 
http://localhost:8080/api/v1
For production deployments, replace localhost:8080 with your actual domain: 
https://your-domain.com/api/v1
The API is mounted at /api/v1 within the main application. All endpoint paths are relative to this base URL.

​
API Versioning

Open WebUI uses URL-based versioning with /v1 as the current stable API version. This ensures backward compatibility as new features are added. Current Version: v1 All API endpoints follow this structure: 
/api/v1/{resource}

​
Version History

  • v1 - Current stable version (introduced with Open WebUI 0.1.0)
    • Full CRUD operations for users, chats, models, and documents
    • RAG (Retrieval Augmented Generation) support
    • WebSocket support for real-time chat streaming
    • OAuth and LDAP authentication

​
OpenAPI Documentation

Open WebUI automatically generates interactive API documentation when running in development mode:
  • Swagger UI: http://localhost:8080/docs
  • OpenAPI JSON: http://localhost:8080/openapi.json
API documentation endpoints (/docs and /openapi.json) are only available when ENV=dev. These are disabled in production for security.

​
Content Type

All API requests and responses use JSON format unless otherwise specified: 
Content-Type: application/json
For file uploads (documents, images, audio), use multipart/form-data.

​
Rate Limiting

The API implements rate limiting on authentication endpoints to prevent abuse:
  • Sign-in endpoint: 5 requests per 3 minutes per email address
  • Rate limits are tracked using Redis when available
  • Exceeding limits returns 429 Too Many Requests
Other API endpoints do not have global rate limits by default, but can be restricted using the Pipelines plugin framework.

​
Error Responses

The API uses standard HTTP status codes to indicate success or failure:
Status CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing authentication
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Error Response Format

Error responses include a detail field with a human-readable message: 
{
  "detail": "Invalid credentials"
}

​
Request Headers

Common request headers used across API endpoints:
​
Authorization
string
required
Bearer token or API key for authentication. Format: Bearer {token} or Bearer sk-{api_key}
​
Content-Type
string
default:"application/json"
Media type of the request body. Use multipart/form-data for file uploads.
​
x-api-key
string
Alternative authentication header for Anthropic Messages API compatibility (specific routes only)

​
Response Headers

Common response headers:
  • X-Process-Time: Request processing time in seconds
  • Content-Type: Response media type (typically application/json)

​
WebSocket Support

For real-time chat streaming and events, Open WebUI provides WebSocket endpoints: 
ws://localhost:8080/ws/socket.io
WebSocket support requires Redis for multi-worker deployments. Enable with ENABLE_WEBSOCKET_SUPPORT=true.

​
API Key Restrictions

Administrators can restrict API key access to specific endpoints:
  • Enable restrictions: ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS=true
  • Configure allowed endpoints: API_KEYS_ALLOWED_ENDPOINTS=/api/v1/chat,/api/v1/models
When enabled, API keys (prefixed with sk-) can only access whitelisted endpoints.

​
CORS Configuration

CORS (Cross-Origin Resource Sharing) is configured via environment variables: 
CORS_ALLOW_ORIGIN=https://example.com,https://app.example.com
For local development, CORS typically allows all origins. Configure appropriately for production.

​
Pagination

List endpoints support pagination using query parameters:
​
limit
integer
default:"50"
Maximum number of items to return
​
skip
integer
default:"0"
Number of items to skip (offset)
Example: 
GET /api/v1/chats?limit=20&skip=40
Some endpoints support filtering via query parameters. Refer to individual endpoint documentation for available filters.

​
Next Steps

Authentication

Learn how to authenticate API requests with JWT tokens, API keys, or OAuth

Endpoints

Explore available API endpoints and their usage

Build docs developers (and LLMs) love

Get started for freeTalk to us