API Introduction

The Chatbot Platform API provides programmatic access to all platform features, allowing you to integrate bot management, agent loops, and conversations into your applications.

Base URL

All API requests are made to:

https://api.chatbotplatform.io/v1

Authentication

API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

Navigate to Settings

In the dashboard, go to your team settings.

API Keys Section

Click on API Keys in the sidebar.

Create Key

Click Create API Key and give it a name.

Copy Key

Copy the generated key - it won’t be shown again.

Store Securely

Store the key in your environment variables or secrets manager.

Keep your API key secret. Anyone with the key has full access to your team’s resources.

Making Requests

Example: List Bots

curl https://api.chatbotplatform.io/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "bot_abc123",
      "name": "Support Bot",
      "description": "Customer support chatbot",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

Example: Create Bot

curl -X POST https://api.chatbotplatform.io/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "description": "Handles sales inquiries"
  }'

Response:

{
  "data": {
    "id": "bot_xyz789",
    "name": "Sales Bot",
    "description": "Handles sales inquiries",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Available Resources

Bots

Manage chatbot instances:

GET /bots - List all bots
POST /bots - Create a bot
GET /bots/{id} - Get bot details
PATCH /bots/{id} - Update bot
DELETE /bots/{id} - Delete bot

Integrations

Configure AI backend connections:

GET /bots/{bot_id}/integrations - List integrations
POST /bots/{bot_id}/integrations - Create integration
GET /integrations/{id} - Get integration details
PATCH /integrations/{id} - Update integration
DELETE /integrations/{id} - Delete integration

Channels

Connect to messaging platforms:

GET /bots/{bot_id}/channels - List channels
POST /bots/{bot_id}/channels - Create channel
GET /channels/{id} - Get channel details
PATCH /channels/{id} - Update channel
DELETE /channels/{id} - Delete channel

Conversations

Access conversation history:

GET /bots/{bot_id}/conversations - List conversations
GET /conversations/{id} - Get conversation details
GET /conversations/{id}/messages - Get messages
DELETE /conversations/{id} - Delete conversation

Agent Loops

Manage autonomous workflows:

GET /agent-loops - List agent loops
POST /agent-loops - Create agent loop
GET /agent-loops/{id} - Get details
POST /agent-loops/{id}/run - Execute agent loop
GET /agent-loops/{id}/executions - List executions
PATCH /agent-loops/{id} - Update agent loop
DELETE /agent-loops/{id} - Delete agent loop

Pagination

List endpoints support pagination using query parameters:

GET /bots?page=2&per_page=50

Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 20, max: 100)

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 125,
    "total_pages": 3
  }
}

Filtering

Some endpoints support filtering:

GET /conversations?user_id=user_123&status=active

Check endpoint-specific documentation for available filters.

Error Handling

API errors return appropriate HTTP status codes and JSON error objects:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Bot with ID bot_123 not found",
    "details": {
      "resource_type": "bot",
      "resource_id": "bot_123"
    }
  }
}

Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limit Exceeded
500	Internal Server Error

Rate Limits

API requests are rate limited per API key:

Plan	Rate Limit
Free	60 requests/minute
Pro	300 requests/minute
Enterprise	1000 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1705320000

When rate limited, you’ll receive a 429 response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retry_after": 45
  }
}

Webhooks

The API also sends webhooks for certain events:

Bot message received
Integration failed
Agent loop completed
Channel disconnected

See Authentication for webhook signature verification.

SDKs and Libraries

Official SDKs (coming soon):

JavaScript/TypeScript
Python
Go
Ruby

Support

Documentation: Full API reference at docs.chatbotplatform.io/api-reference
Issues: Report bugs on GitHub
Email: support@chatbotplatform.io

Next Steps

Authentication

Learn about API authentication

Bot Management

API endpoints for bots (coming soon)

Agent Loops API

Trigger agents programmatically (coming soon)

Get Started

Bots

Agent Loops

MCP Servers

Use Cases

Base URL

Authentication

Getting an API Key

Making Requests

Example: List Bots

Example: Create Bot

Available Resources

Bots

Integrations

Channels

Conversations

Agent Loops

Filtering

Error Handling

Status Codes

Rate Limits

Webhooks

SDKs and Libraries

Support

Next Steps

Authentication

Bot Management

Agent Loops API

​Base URL

​Authentication

​Getting an API Key

​Making Requests

​Example: List Bots

​Example: Create Bot

​Available Resources

​Bots

​Integrations

​Channels

​Conversations

​Agent Loops

​Pagination

​Filtering

​Error Handling

​Status Codes

​Rate Limits

​Webhooks

​SDKs and Libraries

​Support

​Next Steps

Authentication

Bot Management

Agent Loops API

Base URL

Authentication

Getting an API Key

Making Requests

Example: List Bots

Example: Create Bot

Available Resources

Bots

Integrations

Channels

Conversations

Agent Loops

Pagination

Filtering

Error Handling

Status Codes

Rate Limits

Webhooks

SDKs and Libraries

Support

Next Steps