API Introduction

Overview of the Open WebUI REST API

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 Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal 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

Filtering and Search

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