Skip to main content
Nearly every Onyx feature is accessible through the Onyx API. Onyx APIs are built on REST principles with JSON request/response formats. All endpoints require authentication and follow relatively consistent patterns. Make API requests to: https://cloud.onyx.app/api or https://your-self-hosted-onyx.com/api
Onyx follows SemVer 2.0.0. Breaking changes will be indicated by major version increments.

​
Authentication

​
API Keys

API Keys are created by admins from the Admin Panel. Each key exists as a distinct user in Onyx, meaning you can trace activity, keep chat sessions private, and scope resources to a specific key. There are three types:
Can access all endpoints, including those pre-fixed with admin/.Use cases:
  • Full system administration
  • User management operations
  • Data management and analytics
  • Complete access to all Onyx features
⚠️ Use with caution: Admin keys have unrestricted access to your Onyx instance.
Can access the non-admin endpoints like Search, Chat, Agents, and Actions.Use cases:
  • Building chat applications
  • Implementing search functionality
  • Creating and managing agents
  • Running actions and workflows
✅ Recommended: Most users should use Basic API Keys for application development.
Read-only Agent access. Can post messages to Chat endpoints, but cannot read chat history.Use cases:
  • Highly restricted environments
  • Specific use cases requiring minimal permissions
  • Testing with limited scope
See API Keys for setup instructions.

​
Personal Access Tokens

Personal Access Tokens (PATs) let any user authenticate API requests as themselves. Unlike API Keys, PATs inherit your own role and permissions, so they can access exactly what you can. To create a token, go to Settings > Accounts & Access and click Create New Token. Give it a name and choose an expiration (7 days, 30 days, 365 days, or never).
Your token is displayed only once at creation. Copy it immediately and store it securely.
Use the token as a Bearer token in the Authorization header: 
curl -H "Authorization: Bearer onyx_pat_..." \
  https://cloud.onyx.app/api/chat/get-user-chat-sessions
You can view, audit, and revoke your tokens at any time from Settings > Accounts & Access.

​
API Reference and Playground

In the API Reference, we have curated a subset of useful Onyx API endpoints. You can experiment with the endpoints on each page or follow one of our Guides. You can find all Onyx API endpoints in the built-in OpenAPI explorer: https://cloud.onyx.app/api/docs or https://your-onyx-domain.com/api/docs
The explorer is purely for reference. It is not a fully-featured API client. Ignore the tenant_id parameter and use your API key as a Bearer token.

​
Next Steps

Core Concepts

Learn the fundamental concepts and terminology for working with Onyx APIs

Guide: Send a Chat Message

Simple example of sending a message programmatically