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

# Chat with your Agents using the Cassidy Agents API

> Use an API key to start chats with your Agents, send them messages, and read chat history from your own apps, internal tools, and backend services.

The Cassidy Agents API lets your applications chat with your [Agents](https://docs.cassidyai.com/agents/overview.md). Start a chat with an Agent, send it messages, read the replies, and mint tokens for [secure embedded chats](https://docs.cassidyai.com/agents/deploy/embed.md#restrict-access-with-secure-tokens).

> [!NOTE]
>
> You need an API key. To create one, follow the steps in [Deploy via
> API](https://docs.cassidyai.com/agents/deploy/api.md).

## Authenticate

An API key acts as the user who created it, with that user's permissions. Send it as a bearer token in the `Authorization` header:

```bash theme={null}
-H 'Authorization: Bearer YOUR_API_KEY'
```

> [!WARNING]
>
> Keep your API key secure. Call the API from your backend, never from browser
> or mobile code, and don't commit the key to version control.

## Make your first request

Create a chat with an Agent. The Agent's ID is shown on its **Deploy via API** tab:

```bash theme={null}
curl -X POST 'https://app.cassidyai.com/api/assistants/thread/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"assistant_id": "YOUR_AGENT_ID"}'
```

The response contains a `thread_id`. Use it to send a message. The response contains the Agent's reply:

```bash theme={null}
curl -X POST 'https://app.cassidyai.com/api/assistants/message/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"thread_id": "YOUR_THREAD_ID", "message": "Summarize our refund policy"}'
```

Each endpoint has its own page in the API reference with its parameters and response format.

## Download the API specification

The OpenAPI specification describes every endpoint. Use it to load the API into another tool, such as Postman or a code generator:

```bash theme={null}
curl 'https://app.cassidyai.com/api/openapi.json'
```

## API keys vs. Admin API keys

To pull organization-wide usage and activity into your own reports instead, use an [Admin API key](https://docs.cassidyai.com/reference/admin-api.md). Admin API keys act as your organization, not as a user, and can only read organization-wide data.


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