API Spec Introduction

API Specification

The CBK API provides a comprehensive set of endpoints for building, managing, and deploying AI agents. This specification outlines the complete API interface, authentication methods, and usage patterns.

Base URL

All API requests should be made to:

https://api.chatbotkit.com/v1

bash

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header:

"Authorization": "Bearer YOUR_API_KEY"

json

API Concepts

The API is organized around these core concepts:

  • Bots: Conversational agents that can be customized and deployed
  • Conversations: Individual chat sessions between users and bots
  • Messages: Individual exchanges within conversations
  • Skillsets: Specialized capabilities that can be added to bots
  • Dataset: Training data and knowledge bases for bots

Request Format

API requests should be made using JSON format. Set the following headers:

"Content-Type": "application/json"
"Accept": "application/json"

json

Response Format

All responses are returned in JSON format. A typical response structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    // Metadata about the response
  }
}

json

Rate Limiting

The API implements rate limiting based on your subscription tier. Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests per hour
  • X-RateLimit-Remaining: Remaining requests for the current period
  • X-RateLimit-Reset: Time when the rate limit will reset

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

  • 2xx: Success
  • 4xx: Client errors (invalid requests)
  • 5xx: Server errors

Error responses include detailed information:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}
  }
}

javascript

Versioning

The API version is specified in the URL path. The current version is v1. We maintain backwards compatibility and provide advance notice for breaking changes.

Getting Started

To begin using the API:

  1. Sign up for a ChatBotKit account
  2. Generate an API key from the dashboard
  3. Make your first API request using the authentication token.
  4. Explore the detailed endpoint documentation below

Support

For technical support or questions about the API, contact our developer support team or visit our community forums.

Note: This specification is regularly updated. Check the changelog for the latest changes and improvements to the API.

Go to cbk.ai