> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# 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
```

<Info>
  The API is mounted at `/api/v1` within the main application. All endpoint paths are relative to this base URL.
</Info>

## 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`

<Warning>
  API documentation endpoints (`/docs` and `/openapi.json`) are only available when `ENV=dev`. These are disabled in production for security.
</Warning>

## Content Type

All API requests and responses use JSON format unless otherwise specified:

```http theme={null}
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`

<Note>
  Other API endpoints do not have global rate limits by default, but can be restricted using the Pipelines plugin framework.
</Note>

## 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:

```json theme={null}
{
  "detail": "Invalid credentials"
}
```

## Request Headers

Common request headers used across API endpoints:

<ParamField header="Authorization" type="string" required>
  Bearer token or API key for authentication. Format: `Bearer {token}` or `Bearer sk-{api_key}`
</ParamField>

<ParamField header="Content-Type" type="string" default="application/json">
  Media type of the request body. Use `multipart/form-data` for file uploads.
</ParamField>

<ParamField header="x-api-key" type="string">
  Alternative authentication header for Anthropic Messages API compatibility (specific routes only)
</ParamField>

## 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
```

<Info>
  WebSocket support requires Redis for multi-worker deployments. Enable with `ENABLE_WEBSOCKET_SUPPORT=true`.
</Info>

## 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:

```bash theme={null}
CORS_ALLOW_ORIGIN=https://example.com,https://app.example.com
```

<Tip>
  For local development, CORS typically allows all origins. Configure appropriately for production.
</Tip>

## Pagination

List endpoints support pagination using query parameters:

<ParamField query="limit" type="integer" default="50">
  Maximum number of items to return
</ParamField>

<ParamField query="skip" type="integer" default="0">
  Number of items to skip (offset)
</ParamField>

Example:

```http theme={null}
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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to authenticate API requests with JWT tokens, API keys, or OAuth
  </Card>

  <Card title="Endpoints" icon="code" href="/api/endpoints">
    Explore available API endpoints and their usage
  </Card>
</CardGroup>