# How to Use the Onyx API: FastAPI Endpoints, Authentication, and Client Generation

> Learn how to use the Onyx API with FastAPI. This guide covers endpoints, Bearer token authentication, and client generation for chat, search, and document ingestion.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: api-reference
- Published: 2026-03-28

---

**The Onyx API is a FastAPI-based HTTP interface that exposes chat, search, document ingestion, and admin functionality at `{WEB_DOMAIN}/api`, authenticated via Bearer tokens (API keys or personal access tokens) and implemented across modular routers in `backend/onyx/server/`.**

Onyx provides a comprehensive programmatic interface for its enterprise knowledge management platform. Whether you are automating chat interactions, syncing documents, or managing users, understanding how to use the Onyx API requires familiarity with its router-based architecture, authentication dependencies, and OpenAPI schema generation capabilities.

## Base URL and Configuration

The API is served by the FastAPI `app` object defined in **[`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py)**. By default, the base URL follows this pattern:

```

{WEB_DOMAIN}/api

```

The `WEB_DOMAIN` variable is defined in **[`backend/onyx/configs/app_configs.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/app_configs.py)** and defaults to `http://localhost:3000`. If you configure the environment variable `API_PREFIX="/api"`, the prefix is automatically prepended to all routes via the `include_router_with_global_prefix_prepended` utility in [`main.py`](https://github.com/onyx-dot-app/onyx/blob/main/main.py), yielding the complete endpoint `http://localhost:3000/api`.

## Authentication Methods

All protected endpoints rely on the `check_api_key_usage` dependency defined in **[`backend/onyx/server/api_key_usage.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/api_key_usage.py)**. This dependency validates credentials and enforces optional usage limits when `USAGE_LIMITS_ENABLED` is true (see **[`backend/onyx/server/usage_limits.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/usage_limits.py)**).

Onyx supports four authentication mechanisms:

- **API Key**: Pass `Authorization: Bearer <hashed_key>`. The system validates the key against the database and tracks usage limits via `api_key_usage.check_api_key_usage`.
- **Personal Access Token (PAT)**: Uses the same `Authorization: Bearer <hashed_pat>` header and validation logic as API keys.
- **Session Cookies**: Managed by `fastapi_users` routers mounted under `/auth` in **[`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py)**. The browser sends the `session` cookie automatically.
- **OAuth / OIDC**: Browser redirects handled by the router created in `onyx.auth.users.create_onyx_oauth_router`, accessible at `/auth/oauth` or `/auth/oidc`.

## Core API Endpoints

The Onyx API is organized into logical router groups under `backend/onyx/server/`. Each router is registered in [`main.py`](https://github.com/onyx-dot-app/onyx/blob/main/main.py) with specific prefixes.

### Chat and Conversations

The chat router (`APIRouter(prefix="/chat")`) in **[`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py)** provides:

- `POST /chat/create-chat-session`: Initialize a new conversation
- `POST /chat`: Send messages with streaming support via `StreamingResponse`
- `GET /chat/get-user-chat-sessions`: List sessions with pagination using `page_size` and `before` parameters

### Search and Query

The query router (`APIRouter(prefix="/query")`) in **[`backend/onyx/server/query_and_chat/query_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/query_backend.py)** exposes:

- `POST /query`: Execute RAG-based search queries
- `GET /query/history`: Retrieve query history (admin only)

### Document Ingestion

The ingestion router (`APIRouter(prefix="/onyx-api")`) in **[`backend/onyx/server/onyx_api/ingestion.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/onyx_api/ingestion.py)** handles:

- `POST /onyx-api/ingestion`: Upload files or connector batches
- `GET /onyx-api/connector-docs/{cc_pair_id}`: List documents for a specific connector

### User and Admin Management

Administrative endpoints reside in **[`backend/onyx/server/manage/users.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/manage/users.py)** and related files:

- `GET /manage/users`: List all users (admin only)
- `POST /manage/users/test-upsert-user`: Create test users programmatically
- `POST /admin/api-key`: Create API keys (via **[`backend/onyx/server/api_key/api.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/api_key/api.py)**)
- `POST /search-settings/set-new-search-settings`: Update RAG configuration (via **[`backend/onyx/server/manage/search_settings.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/manage/search_settings.py)**)

## Practical Usage Examples

### Creating a Chat Session with cURL

Authenticate using your API key in the Bearer header:

```bash
curl -X POST "http://localhost:3000/api/chat/create-chat-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "persona_id": null,
        "name": "Demo session",
        "project_id": null
      }'

```

The response returns a JSON object containing `session_id` and timestamps.

### Streaming Chat Responses with Python

To receive tokens as they are generated, set `stream: true` in the payload and iterate over the response:

```python
import requests
import json

url = "http://localhost:3000/api/chat"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "chat_session_id": "b5e2e9c2-7f1a-4d4e-9c2a-123456789abc",
    "message": "What is the weather in Paris?",
    "origin": "user",
    "stream": True
}

with requests.post(url, headers=headers, json=payload, stream=True) as r:
    for line in r.iter_lines():
        if line:
            chunk = json.loads(line.decode())
            print(chunk["delta"]["content"], end="")

```

The request model is defined in **[`backend/onyx/server/query_and_chat/models.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/models.py)**, where `origin` accepts values from the `MessageOrigin` enum.

### Executing Search Queries

```python
import requests

resp = requests.post(
    "http://localhost:3000/api/query",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"query": "latest quarterly earnings", "search_settings_id": 2},
)
print(resp.json())

```

## OpenAPI Schema and Client Generation

Onyx ships with a CLI utility in **[`tools/ods/internal/openapi/openapi_schema.py`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/openapi/openapi_schema.py)** that generates an OpenAPI 3.1 schema and a typed Python client without requiring a running server.

Generate the schema file:

```bash
python -m tools.ods.internal.openapi.openapi_schema schema -o openapi.json

```

Generate a Python client using `openapi-generator-cli`:

```bash
python -m tools.ods.internal.openapi.openapi_schema client -i openapi.json -o ./client

```

### Using the Generated Client

Once generated, the client provides fully typed methods:

```python
from onyx_openapi_client import DefaultApi, ApiClient, Configuration

config = Configuration(host="http://localhost:3000/api")
api_client = ApiClient(configuration=config)
client = DefaultApi(api_client)

client.api_key = "YOUR_API_KEY"
sessions = client.get_user_chat_sessions()
print(sessions)

```

## Advanced Patterns and Configuration

### Pagination

List endpoints like `get_user_chat_sessions` support cursor-based pagination using `page_size` and `before` (ISO-8601 timestamp) query parameters.

### Rate Limiting and Usage Tracking

When `USAGE_LIMITS_ENABLED` is configured, the `check_api_key_usage` dependency automatically enforces limits defined in **[`backend/onyx/server/usage_limits.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/usage_limits.py)**. Additionally, **[`backend/onyx/server/middleware/rate_limiting.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/middleware/rate_limiting.py)** integrates `fastapi_limiter` with Redis for request throttling.

### Multi-Tenancy

In multi-tenant deployments, the tenant ID propagates via `shared_configs.contextvars.get_current_tenant_id`. All database queries automatically scope to the current tenant context.

### Performance Monitoring

Enable per-endpoint latency logging by setting the environment variable `LOG_ENDPOINT_LATENCY=true`. The middleware in **[`backend/onyx/server/middleware/latency_logging.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/middleware/latency_logging.py)** injects timing data for every request.

## Summary

- **The Onyx API** is a FastAPI application mounted at `{WEB_DOMAIN}/api` via **[`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py)**.
- **Authentication** requires `Authorization: Bearer <token>` headers validated by `check_api_key_usage` in **[`backend/onyx/server/api_key_usage.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/api_key_usage.py)**.
- **Core functionality** is split across routers: chat ([`chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/chat_backend.py)), search ([`query_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/query_backend.py)), ingestion ([`ingestion.py`](https://github.com/onyx-dot-app/onyx/blob/main/ingestion.py)), and admin (`manage/` package).
- **Streaming responses** use FastAPI's `StreamingResponse` for real-time chat tokens.
- **Client generation** is available via [`tools/ods/internal/openapi/openapi_schema.py`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/openapi/openapi_schema.py) for type-safe Python integration.

## Frequently Asked Questions

### How do I authenticate requests to the Onyx API?

Include the header `Authorization: Bearer YOUR_API_KEY` or `Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN` in every request. The system validates these against the database using the `check_api_key_usage` dependency and optionally enforces usage limits defined in **[`backend/onyx/server/usage_limits.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/usage_limits.py)**.

### What is the default base URL for the Onyx API?

The default base URL is `http://localhost:3000/api`, derived from the `WEB_DOMAIN` variable in **[`backend/onyx/configs/app_configs.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/configs/app_configs.py)**. You can modify the global prefix by setting the `API_PREFIX` environment variable before starting the server.

### How do I handle streaming chat responses?

Set `"stream": true` in your JSON payload when calling `POST /api/chat`. The server returns a `StreamingResponse` where each line is a JSON object containing a `delta` field. Parse these chunks iteratively to display tokens as they arrive, as shown in the Python `requests` example above.

### Can I generate a typed Python client for the Onyx API?

Yes. Run `python -m tools.ods.internal.openapi.openapi_schema schema -o openapi.json` to export the OpenAPI specification, then generate a client with the same script's `client` command. The resulting package provides type-hinted methods matching every endpoint defined in **`backend/onyx/server/`**.