> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview & Auth

> Overview of Onyx APIs

**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`

<Note>
  Onyx follows [SemVer 2.0.0](https://semver.org/). Breaking changes will be indicated by major version increments.
</Note>

## 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:

<AccordionGroup>
  <Accordion title="Admin API Keys" icon="shield-check">
    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.
  </Accordion>

  <Accordion title="Basic API Keys" icon="key">
    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.
  </Accordion>

  <Accordion title="Limited API Keys" icon="lock">
    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
  </Accordion>
</AccordionGroup>

See [API Keys](/admins/user_management/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).

<Warning>
  Your token is displayed only once at creation. Copy it immediately and store it securely.
</Warning>

Use the token as a Bearer token in the `Authorization` header:

```bash theme={null}
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](/developers/api_reference/chat/get_chat_session),
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](/developers/guides/chat_new_guide).

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`

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/developers/core_concepts">
    Learn the fundamental concepts and terminology for working with Onyx APIs
  </Card>

  <Card title="Guide: Send a Chat Message" icon="comment" href="/developers/guides/chat_new_guide">
    Simple example of sending a message programmatically
  </Card>
</CardGroup>