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. The API has no separate paths or response shapes: a script calls the same endpoints the Onyx web app calls. Make API requests to: 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 the Authorization header:
Onyx has two kinds of token. An API Key belongs to a service account. A Personal Access Token belongs to you.

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.
A key in the Admin group has unrestricted access to your Onyx instance. Prefer a group that grants only the permissions your integration needs.
Service accounts and User Groups need a Business plan or higher. Custom roles with configurable permissions need an Enterprise plan.
See Service Accounts for setup instructions.

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.
Your token is displayed only once at creation. Copy it immediately and store it securely.
Changing your password revokes all of your tokens.

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.
Endpoint pages and 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:
A request that fails a permission check returns 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.
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.

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