---
title: "Developer Overview"
description: "Connect Chatvox to your own systems with the REST API and webhooks: chat with agents, read leads and conversations, manage knowledge, and get notified of events."
sidebar:
  label: Overview
---

:::note[Plan]
The REST API and webhooks are available on the **Standard** plan and above. Only team **Owners** and **Admins** can manage API keys and webhooks.
:::

Chatvox gives developers two ways to connect your agents to other systems:

- **REST API**: your code calls Chatvox. Send messages to an agent, read leads and conversations, and add or remove knowledge.
- **Webhooks**: Chatvox calls your code. Get a signed `POST` request when a lead is captured, a visitor asks for a person, or a Helpdesk ticket is opened.

You can also connect both to **Zapier, Make, or n8n** without writing code. See [Zapier, Make, and n8n](/docs/developers/zapier-make-n8n).

**[API Keys](/docs/developers/api-keys)**

Create keys for the whole team or for selected agents.

**[Agents and Chat](/docs/developers/agents-and-chat)**

Send messages to an agent and get its reply.

**[Knowledge Sources](/docs/developers/knowledge-sources)**

Add text, Q&A, web pages, sitemaps, and files.

**[Webhooks](/docs/developers/webhooks)**

React to leads, handoff requests, and tickets.

## Quick start

1. **Create an API key**

    Go to **Team settings → API & webhooks** and select **Manage**. Under **API keys**, select **Create key**, give it a name, and copy the key. It starts with `cvx_` and is shown only once.

2. **Find your agent's ID**

    List the agents your key can reach:

    ```bash
    curl https://my.chatvox.co/api/v1/agents \
      -H "Authorization: Bearer cvx_your_key"
    ```

    Copy the `id` of the agent you want to use.

3. **Send a message**

    ```bash
    curl -X POST https://my.chatvox.co/api/v1/agents/AGENT_ID/messages \
      -H "Authorization: Bearer cvx_your_key" \
      -H "Content-Type: application/json" \
      -d '{"message": "What are your opening hours?"}'
    ```

    The response contains the agent's reply and a `conversation.id`. Send that ID with your next message to continue the same conversation.

## Basics

| | |
| --- | --- |
| **Base URL** | `https://my.chatvox.co/api/v1` |
| **Authentication** | `Authorization: Bearer cvx_...` on every request. See [API Keys](/docs/developers/api-keys). |
| **Format** | JSON requests and responses. Use `multipart/form-data` only to upload files. |
| **IDs** | Agents, conversations, leads, and knowledge sources use UUIDs. |
| **Dates** | ISO 8601 with a time zone, for example `2026-10-09T18:20:16+00:00`. |
| **Lists** | Paginated with `page` and `per_page` (1–100, default 25). |
| **Credits** | Messages sent through the API use your team's credits, the same as any other channel. |
| **Actions** | API conversations can run [Custom API](/docs/actions/custom-api) and [MCP Server](/docs/actions/mcp-server) actions when their **API** channel is on. See [Where actions run](/docs/actions#where-actions-run). |

### Lists and pagination

List endpoints return the items in `data`, plus `links` and `meta` for paging:

```json
{
  "data": [{ "id": "…", "name": "Support agent", "status": "active", "created_at": "…" }],
  "links": { "first": "…?page=1", "last": "…?page=3", "prev": null, "next": "…?page=2" },
  "meta": { "current_page": 1, "per_page": 25, "total": 61, "last_page": 3 }
}
```

Single items are returned as a plain object, without a `data` wrapper.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/agents` | [List agents](/docs/developers/agents-and-chat#list-agents) |
| `GET` | `/agents/{agent}` | [Get an agent](/docs/developers/agents-and-chat#get-an-agent) |
| `POST` | `/agents/{agent}/messages` | [Send a message](/docs/developers/agents-and-chat#send-a-message) |
| `GET` | `/agents/{agent}/conversations` | [List conversations](/docs/developers/conversations#list-conversations) |
| `GET` | `/agents/{agent}/conversations/{id}` | [Get a conversation](/docs/developers/conversations#get-a-conversation) |
| `GET` | `/agents/{agent}/leads` | [List leads](/docs/developers/leads#list-leads) |
| `GET` | `/agents/{agent}/leads/{id}` | [Get a lead](/docs/developers/leads#get-a-lead) |
| `GET` | `/agents/{agent}/sources` | [List knowledge sources](/docs/developers/knowledge-sources#list-sources) |
| `POST` | `/agents/{agent}/sources` | [Add a knowledge source](/docs/developers/knowledge-sources#add-a-source) |
| `GET` | `/agents/{agent}/sources/{id}` | [Get a knowledge source](/docs/developers/knowledge-sources#get-a-source) |
| `DELETE` | `/agents/{agent}/sources/{id}` | [Delete a knowledge source](/docs/developers/knowledge-sources#delete-a-source) |