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

# Conduit API

> Programmatic access to your Conduit workspace data.

<Warning>
  The Conduit API is only available on the **v3 plan**. Contact [support@conduit.ai](mailto:support@conduit.ai) to enable API access for your workspace.
</Warning>

## Overview

The Conduit API gives you programmatic access to contacts, conversations, tickets, calls, escalations, custom attributes, knowledge base, and workspace metadata. Read and write endpoints are available depending on your token's access level. All endpoints are REST-based and return JSON.

**Base URL**

```
https://api.conduit.ai/v1
```

## Authentication

All requests require a **Bearer token** in the `Authorization` header. Generate API tokens from **Settings > API & MCP**. The setting is personal, so tokens can grant access to one or more workspaces where you are an admin.

```bash theme={null}
curl https://api.conduit.ai/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Tokens are scoped to one or more workspaces. Use the [List Workspaces](/api-reference/workspaces/list) endpoint to discover which workspaces your token can access.

## Pagination

List endpoints return paginated results. Use `limit` (1-100, default 20) and `cursor` to page through results.

```json theme={null}
{
  "data": [...],
  "next_cursor": "page-token",
  "has_more": true
}
```

Pass `next_cursor` as the `cursor` query parameter in your next request to fetch the next page. When `has_more` is `false`, you've reached the end.

## Polling for new activity

Cursors page through a result set once. Keeping an external system in sync needs the opposite: only what has changed since you last looked. Two timestamp filters cover that.

<Steps>
  <Step title="Find threads that moved">
    Call [List Conversations](/api-reference/conversations/list) with `updated_after` set to the highest `updated_at` you have already stored.

    ```
    GET /v1/conversations?workspace_id=WS&updated_after=2026-04-03T03:15:04.000Z
    ```
  </Step>

  <Step title="Fetch only the new messages in each thread">
    For each conversation returned, call [List Conversation Messages](/api-reference/conversations/messages) with `created_after` set to the highest `created_at` you have stored for that thread. This replaces re-paging the whole transcript.

    ```
    GET /v1/conversations/{id}/messages?created_after=2026-04-03T03:15:04.000Z
    ```
  </Step>
</Steps>

Both filters are inclusive (at or after), and `created_at` is truncated to the millisecond, so the message on the boundary is normally returned again. Deduplicate on the message `id` rather than assuming every result is new.

`created_after` filters on `created_at` (when Conduit recorded the message), not `sent_at` (when the channel says it was sent). Those differ for messages imported from a connected channel, and only `created_at` moves forward as Conduit observes messages, so it is the safe watermark. Using `sent_at` as your cursor will eventually skip a backdated import.

### Telling AI replies from operator replies

Every message carries `is_sent_by_autopilot`. It is `true` only when Conduit's AI agent generated and sent the message, and `false` for operator replies, workflow sends, and messages ingested from a connected channel's own UI.

Use the flag directly. Do not infer automation from `sender.user_id`: AI sends usually leave it `null`, but so do host replies typed in an OTA's own UI and messages sent by workflows, and a small number of AI sends do carry a user id.

## Rate Limits

By default, API requests are limited to **120 requests per minute per workspace**. If you exceed the limit, the API returns `429 Too Many Requests` with a `Retry-After` header indicating when you can retry. Some workspaces may have higher limits based on plan or entitlement.

See [Rate Limits](/rate-limits) for details.

## Errors

All errors return a JSON object with an `error` field:

```json theme={null}
{
  "error": "Invalid workspace id"
}
```

| Status | Meaning |
| - | - |
| 400 | Invalid request parameters |
| 401 | Missing or invalid API token |
| 403 | Token does not have access to the requested workspace |
| 404 | Resource not found |
| 429 | Rate limit exceeded |


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