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

# Onyx Integration: Enterprise Search and Chat for Agents

> Agents can search your company knowledge in Onyx, chat with Onyx agents, and manage documents and connectors. Connect with an API key or access token.

## Overview

OneCLI connects AI agents to [Onyx](https://onyx.app) Cloud with an API key or personal access token. Agents can search the company knowledge Onyx has indexed, chat with your Onyx agents, and add documents through the ingestion API. The gateway injects the key into requests to `cloud.onyx.app`, so your agent never sees it.

This suits agents that need company context before they act: checking the runbook before touching production, or citing the policy doc behind an answer.

Connecting takes about a minute.

<a id="self-hosted" style={{ scrollMarginTop: "8rem" }} />

## Connect Onyx

<Steps>
  <Step title="Create a key in Onyx">
    Onyx has two kinds of key. Pick the one that matches what the agent should reach.

    | Key | Where to create it | What it reaches |
    | - | - | - |
    | **API key** | **Admin Panel** > **Service Accounts** (admins only) | Whatever the groups you assign to it allow. Each key is its own service account |
    | **Personal access token** | **Settings** > **Accounts & Access** > **Create New Token** | Your own access, or less if you choose **Limited access** and pick scopes |

    Copy the key right away. Onyx shows it only once.

    <Tip>
      For an agent that only searches, create a service account in the **Basic** group, or a personal token limited to `read:search`. A key in the **Admin** group reaches every endpoint, including connector and user management.
    </Tip>
  </Step>

  <Step title="Paste it in OneCLI">
    In the OneCLI dashboard, open **Connections** > **Onyx** and paste the key into **API key or access token**.

    <Frame caption="The Onyx connect window in OneCLI.">
      <img src="https://mintcdn.com/chartdbinc/7IV-es-83z77gSFO/images/integrations/onyx/onecli-connect-onyx.png?fit=max&auto=format&n=7IV-es-83z77gSFO&q=85&s=34a0caa4ddae44ced38d6563b0c4753e" alt="OneCLI connect window for Onyx, showing the setup guide link, the API key or access token field with a How to create a key link, and the Connect Onyx button." width="944" height="1177" data-path="images/integrations/onyx/onecli-connect-onyx.png" />
    </Frame>

    Select **Connect Onyx**. OneCLI checks the key with Onyx before saving it, so a wrong key is rejected right away.
  </Step>
</Steps>

<Note>
  This connection covers Onyx Cloud at `cloud.onyx.app`. The gateway adds the key only to the API (`/api/`) and the hosted MCP server (`/mcp/`), never to the Onyx web app on the same host. Self-hosted Onyx, which runs on your own domain, is not covered.
</Note>

## What agents can do

| Area | What agents can do |
| - | - |
| **Search** | Search the documents Onyx has indexed from your connected sources, and read past searches |
| **Chat** | Start a chat session and send messages to an Onyx agent, list and read past sessions, and delete one |
| **Agents** | List and read Onyx agents (personas), and create, change, or delete them |
| **Documents** | List document sets and documents sent through the ingestion API, and add, update, or delete documents |
| **Connectors** | List connectors and their indexing status, create one, run it now, change it, or delete it |
| **Projects** | List and read projects |
| **MCP server** | Search and chat through the hosted Onyx MCP server at `cloud.onyx.app/mcp` |

The key's own Onyx permissions still apply. A Basic key can search and chat, but Onyx refuses its connector and admin calls whatever OneCLI allows.

## Quick example

No `Authorization` header is needed, the gateway adds it:

```bash theme={null}
# Search company knowledge
curl -s -X POST "https://cloud.onyx.app/api/search/send-search-message" \
  -H "Content-Type: application/json" \
  -d '{"search_query": "on-call escalation policy"}'

# Check what this key can do
curl -s "https://cloud.onyx.app/api/me/permissions"
```

For every endpoint, see the [Onyx API docs](https://docs.onyx.app/developers/overview) or the OpenAPI explorer at `https://cloud.onyx.app/api/docs`.

## Controlling access

[Grant](/docs/guides/agent-access) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked.

A good default is to let agents search freely and gate everything else. **Chat with Onyx** spends your Onyx LLM budget on every message, and the ingestion and connector tools change what every Onyx user finds when they search, so put those behind approval or block them.

Organization [rules](/docs/guides/rules) add guardrails on top. A blocked request never reaches Onyx.

To disconnect, remove the connection in **Connections** > **Onyx**, then revoke the key in Onyx: under **Admin Panel** > **Service Accounts** for an API key, or **Settings** > **Accounts & Access** for a personal token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.