> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.
# ChatbotX REST API — Overview and Authentication
> Authenticate with the ChatbotX API using Bearer tokens, review base URLs for cloud and self-hosted instances, and explore all available resource endpoints.
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:
```bash theme={null}
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
```bash curl theme={null}
curl --request GET \
--url https://app.chatbotx.io/api/v1/workspaces \
--header "Authorization: Bearer YOUR_API_TOKEN"
```
```python Python theme={null}
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())
```
```javascript JavaScript theme={null}
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
Paginate and filter your contact database with keyword search and channel filters.
Add a new contact to your Workspace with phone, email, and profile fields.
Retrieve a single contact by internal ID, email address, or phone number.
Modify profile fields on an existing contact record.
Permanently remove a contact and all associated records.
Create a contact if they don't exist, or update their fields if they do.
Bulk-import contacts from an uploaded file with column field mapping.
Send a text message, file, or flow node to a contact on any active channel.
Trigger an automation flow for a specific contact.
Add, remove, and list tags on a contact.
Read and write custom field values for a contact.
Retrieve all custom field definitions in your Workspace.
Define a new custom field with a name and data type.
Rename or move a custom field to a different folder.
Permanently remove a custom field and all its stored values.
Retrieve all tags defined in your Workspace.
Create a new tag for labelling and segmenting contacts.
Rename an existing tag in your Workspace.
Permanently remove a tag from your Workspace.
Retrieve all automation flows in your Workspace.
Retrieve all message sequences with engagement metrics.
Fetch full details for a single message sequence.
Retrieve all broadcasts with scheduling and reach details.
Fetch a single broadcast by ID or name.
Retrieve all connected messaging channels in your Workspace.
Fetch your Workspace configuration and settings.
List and retrieve workspace members with their permissions.
Retrieve all agent teams in your Workspace.
Retrieve all AI agents configured in your Workspace.