https://cloud.onyx.app/api or https://your-self-hosted-onyx.com/api
Onyx releases follow SemVer 2.0.0. Breaking changes are indicated by major version increments.
The endpoints in the API Reference are the supported surface.
Other endpoints can change between releases without notice.
This page applies to Onyx v4.7 and later, which replaced API key roles with group-based permissions.
For older versions, see Overview & Auth before v4.7.
Authentication
Every request authenticates with a Bearer token in theAuthorization header:
API Keys
Admins create API Keys in the Admin Panel under Integrations > Service Accounts. Each key exists as a distinct service account user in Onyx, so you can trace activity, keep chat sessions private, and scope resources to a specific key. A service account has no permissions of its own. Its access comes from the groups you assign to it when you create the key.
Permissions add together. A key in several groups receives the union of their permissions.
Service accounts and User Groups need a Business plan or higher.
Custom roles with configurable permissions need an Enterprise plan.
Personal Access Tokens
Personal Access Tokens (PATs) let a user authenticate API requests as themselves. To create a token, go to Settings > Accounts & Access and click New Access Token. Choose when the token expires and choose its permissions:
A limited token can pick from these scopes:
Scopes only narrow access. A limited token receives the scopes you selected and your own permissions,
never more than you can do yourself. A limited token is also rejected on any endpoint outside its scopes,
even one you can reach in the browser.
Creating a token requires the Create User Access Token permission. The Basic group grants it by default.
An admin can turn it off from the Basic group’s page or grant it to another group. Admins always have it.
On Onyx Cloud, access tokens require a paid plan.
Trial workspaces see an Upgrade Plan prompt instead of the token list.
Permissions
Every endpoint page in the API Reference states the permission it requires. Permissions come from the groups a user or service account belongs to:basic from the Basic group that every user joins, and admin from the Admin group, which passes every check.
This permission model applies to Onyx v4.7 and later. For how groups, group permissions, and Group Managers work,
see Understanding Permissions.
GET /me/permissions identify a permission by its value.
Each value maps to a permission an admin grants to a group in the Admin Panel:
A management permission also grants the reads it needs —
manage:connectors includes read:connectors —
so a caller resolves to more permissions than were granted.
Checking what a token can do
GET /me/permissions returns the caller’s resolved permissions:
403:
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
On self-hosted deployments the explorer is off by default.
Set
ENABLE_PUBLIC_DOCS=true on the API server to serve /api/docs, /api/redoc, and /api/openapi.json.Other Ways to Integrate
The same tokens unlock three integration surfaces that sit next to the REST API: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