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

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. By default, the base URL follows this pattern:

{WEB_DOMAIN}/api

The WEB_DOMAIN variable is defined in 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, 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. This dependency validates credentials and enforces optional usage limits when USAGE_LIMITS_ENABLED is true (see 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. 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 with specific prefixes.

Chat and Conversations

The chat router (APIRouter(prefix="/chat")) in 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 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 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 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)
• POST /search-settings/set-new-search-settings: Update RAG configuration (via 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:

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:

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, where origin accepts values from the MessageOrigin enum.

Executing Search Queries

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 that generates an OpenAPI 3.1 schema and a typed Python client without requiring a running server.

Generate the schema file:

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

Generate a Python client using openapi-generator-cli:

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:

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. Additionally, 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 injects timing data for every request.

Summary

• The Onyx API is a FastAPI application mounted at {WEB_DOMAIN}/api via backend/onyx/main.py.
• Authentication requires Authorization: Bearer <token> headers validated by check_api_key_usage in backend/onyx/server/api_key_usage.py.
• Core functionality is split across routers: chat (chat_backend.py), search (query_backend.py), ingestion (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 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.

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. 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/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}