Skip to main content
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

1

Navigate to Settings

In the dashboard, go to your team settings.
2

API Keys Section

Click on API Keys in the sidebar.
3

Create Key

Click Create API Key and give it a name.
4

Copy Key

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

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

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

​
Rate Limits

API requests are rate limited per API key:
PlanRate Limit
Free60 requests/minute
Pro300 requests/minute
Enterprise1000 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

​
Next Steps

Authentication

Learn about API authentication

Bot Management

API endpoints for bots (coming soon)

Agent Loops API

Trigger agents programmatically (coming soon)