Skip to main content
This page applies to Onyx versions before v4.7. For Onyx v4.7 and later, see Overview & Auth.
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

​
Authentication

Every request authenticates with a Bearer token in the Authorization header.

​
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. Each key is created with a role, and there are three:
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
Only Admins can create and manage API keys. See Service Accounts before v4.7 for setup instructions.

​
Personal Access Tokens

Personal Access Tokens (PATs) let any user authenticate API requests as themselves. Any user can create one. To create a token, go to Settings > Accounts & Access and click Create New Token. Give it a name, choose an expiration (7 days, 30 days, 365 days, or never), and choose its permissions: A limited token can pick from these scopes:
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:
You can view, audit, and revoke your tokens at any time from Settings > Accounts & Access.

​
API Reference and Playground

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.