ChatbotX REST API — Overview and Authentication

The ChatbotX API is a RESTful HTTP API that gives you programmatic access to every resource in your Workspace — contacts, tags, custom fields, conversations, broadcasts, flows, sequences, and more. You can use the API to build integrations, automate workflows, import data, send messages, and trigger automation from any system that can make HTTP requests.

Authentication

The ChatbotX API uses Bearer token authentication. All requests must include your API Access Token in the Authorization header.

Getting Your API Token

Navigate to Settings → Integrations → ChatbotX API Access Token in your Workspace to generate or retrieve your token.

Using the Token

Include the token in every API request as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://app.chatbotx.io/api/v1/workspaces

Treat your API token like a password. Do not expose it in client-side code, public repositories, or URLs that appear in browser history.

Base URLs

Environment	Base URL
ChatbotX Cloud	`https://app.chatbotx.io/api`
Self-Hosted	`https://{YOUR_DOMAIN}/api`

All endpoint paths in this documentation are relative to the base URL. For example, GET /api/v1/contacts maps to https://app.chatbotx.io/api/v1/contacts on cloud.

Rate Limits

The API enforces a limit of 10,000 requests per minute across all endpoints. Each API call counts as one request regardless of how many records it affects. Where possible, use bulk endpoints to maximize efficiency within this limit.

Example Authentication Request

curl --request GET \
  --url https://app.chatbotx.io/api/v1/workspaces \
  --header "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://app.chatbotx.io/api/v1/workspaces"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

const options = {
  method: 'GET',
  headers: { Authorization: 'Bearer YOUR_API_TOKEN' }
};

fetch('https://app.chatbotx.io/api/v1/workspaces', options)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Available Resources

List Contacts

Paginate and filter your contact database with keyword search and channel filters.

Create Contact

Add a new contact to your Workspace with phone, email, and profile fields.

Get Contact

Retrieve a single contact by internal ID, email address, or phone number.

Update Contact

Modify profile fields on an existing contact record.

Delete Contact

Permanently remove a contact and all associated records.

Upsert Contact

Create a contact if they don’t exist, or update their fields if they do.

Import Contacts

Bulk-import contacts from an uploaded file with column field mapping.

Send Message

Send a text message, file, or flow node to a contact on any active channel.

Send Flow

Trigger an automation flow for a specific contact.

Contact Tags

Add, remove, and list tags on a contact.

Contact Custom Fields

Read and write custom field values for a contact.

List Custom Fields

Retrieve all custom field definitions in your Workspace.

Create Custom Field

Define a new custom field with a name and data type.

Update Custom Field

Rename or move a custom field to a different folder.

Delete Custom Field

Permanently remove a custom field and all its stored values.

List Tags

Retrieve all tags defined in your Workspace.

Create Tag

Create a new tag for labelling and segmenting contacts.

Update Tag

Rename an existing tag in your Workspace.

Delete Tag

Permanently remove a tag from your Workspace.

List Flows

Retrieve all automation flows in your Workspace.

List Sequences

Retrieve all message sequences with engagement metrics.

Get Sequence

Fetch full details for a single message sequence.

List Broadcasts

Retrieve all broadcasts with scheduling and reach details.

Get Broadcast

Fetch a single broadcast by ID or name.

List Channels

Retrieve all connected messaging channels in your Workspace.

Get Workspace

Fetch your Workspace configuration and settings.

Workspace Members

List and retrieve workspace members with their permissions.

Workspace Teams

Retrieve all agent teams in your Workspace.

List AI Agents

Retrieve all AI agents configured in your Workspace.

​Authentication

​Getting Your API Token

​Using the Token

​Base URLs

​Rate Limits

​Example Authentication Request

​Available Resources

List Contacts

Create Contact

Get Contact

Update Contact

Delete Contact

Upsert Contact

Import Contacts

Send Message

Send Flow

Contact Tags

Contact Custom Fields

List Custom Fields

Create Custom Field

Update Custom Field

Delete Custom Field

List Tags

Create Tag

Update Tag

Delete Tag

List Flows

List Sequences

Get Sequence

List Broadcasts

Get Broadcast

List Channels

Get Workspace

Workspace Members

Workspace Teams

List AI Agents

Authentication

Getting Your API Token

Using the Token

Base URLs

Rate Limits

Example Authentication Request

Available Resources