Developer Introduction

The Chatsby AI API gives you programmatic access to the entire platform. Create and manage AI customer support agents, ingest knowledge sources, handle conversations, and build production-grade integrations — all through a clean, RESTful interface.

This guide walks you through the fundamentals so you can go from zero to your first API call in minutes.

What You Can Build

The API is designed for flexibility. Here are the most common patterns developers use:

• Custom chat interfaces — Embed Chatsby-powered conversations into your own frontend, mobile app, or kiosk display with full control over styling and behavior.
• Internal tools and dashboards — Build admin panels that let your support team create agents, review conversations, and manage knowledge bases without touching the Chatsby dashboard.
• Automated workflows — Connect Chatsby to your CRM, helpdesk, or ticketing system. Automatically route conversations, create tickets from chats, or sync lead data.
• Multi-tenant SaaS applications — Build products on top of Chatsby where each of your customers gets their own agent, sources, and conversation history.
• Analytics pipelines — Pull conversation data into your data warehouse for custom reporting, sentiment analysis, or quality monitoring.

API Architecture

The Chatsby API follows REST conventions and communicates exclusively over HTTPS. Every request and response body is encoded as JSON with Content-Type: application/json.

Key architectural decisions:

Authentication Overview

Every API request requires a valid API key passed as a Bearer token in the Authorization header.

curl https://api.chatsby.co/v1/agents \
  -H "Authorization: Bearer chtb_live_abc123def456"

You can generate and manage API keys from your Chatsby Dashboard under Settings > API Keys. Chatsby issues two types of keys:

• Production keys (chtb_live_...) — Full access to your live data. Use these in your deployed applications.
• Test keys (chtb_test_...) — Isolated test environment. Safe for development and CI pipelines.

Rate Limiting

The API enforces rate limits to ensure fair usage and platform stability.

Every response includes headers that tell you where you stand:

When you exceed the limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your retry logic — wait 1 second, then 2, then 4, and so on.

Quick Start

Send your first API request in under a minute. Replace YOUR_API_KEY with a key from your dashboard and YOUR_AGENT_ID with an agent ID from your account.

curl -X POST https://api.chatsby.co/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_1a2b3c4d5e",
    "message": "What are your business hours?"
  }'

const response = await fetch('https://api.chatsby.co/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'agent_1a2b3c4d5e',
    message: 'What are your business hours?',
  }),
});
 
const data = await response.json();
console.log(data.reply);

import requests
 
response = requests.post(
    "https://api.chatsby.co/v1/conversations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": "agent_1a2b3c4d5e",
        "message": "What are your business hours?",
    },
)
 
data = response.json()
print(data["reply"])

A successful response looks like this:

{
  "id": "conv_xyz789",
  "agent_id": "agent_1a2b3c4d5e",
  "reply": "Our business hours are Monday through Friday, 9 AM to 6 PM EST.",
  "sources_used": [
    { "id": "src_abc123", "title": "Contact Us Page" }
  ],
  "conversation_id": "conv_xyz789",
  "created_at": "2025-03-15T14:30:00Z"
}

SDKs

Official SDKs handle authentication, retries, pagination, and type safety for you.

Install the Node.js SDK:

npm install @chatsby/sdk

See the Node.js SDK reference for full documentation.

Error Handling

The API returns consistent, structured error responses so your code can handle failures predictably. Every error response includes a top-level error object:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'agent_id' field is required.",
    "code": "missing_required_field",
    "param": "agent_id",
    "status": 400
  }
}

The type field tells you the error category, message gives a human-readable explanation, and param identifies the offending field when applicable. See the Error Codes reference for the full list.

Pagination

All list endpoints use cursor-based pagination. This approach is efficient and stable even when new records are being created during iteration.

# First page
curl "https://api.chatsby.co/v1/agents?page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Next page
curl "https://api.chatsby.co/v1/agents?page_size=10&cursor=eyJpZCI6ImFnZW50XzEwIn0" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes pagination metadata:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImFnZW50XzEwIn0"
}

When has_more is false, you have reached the last page.

Webhooks

Webhooks let your application receive real-time notifications when events occur in your Chatsby account — new conversations, messages, trained sources, and more.

Configure webhook endpoints in your Dashboard or via the API. Every webhook delivery includes an HMAC-SHA256 signature so you can verify that the payload came from Chatsby. See the Webhooks guide for setup instructions, payload formats, and security best practices.

Versioning and Changelog

The API is versioned via the URL path. The current version is v1. Our versioning policy:

• Non-breaking changes (new fields, new endpoints, new enum values) are added to the current version without a version bump.
• Breaking changes (removed fields, changed response shapes, removed endpoints) are released under a new version.
• Deprecation notices are published at least 90 days before a version is retired.
• Changelog updates are posted to the Chatsby Blog and emailed to developers with active API keys.

Support and Community

If you run into issues or have questions:

• Documentation — You are here. Browse the sidebar for detailed guides on every API resource.
• Email support — Reach the engineering team at [email protected].
• Discord community — Join the Chatsby Discord to chat with other developers and the Chatsby team.
• GitHub — Report SDK bugs or request features on our GitHub repositories.
• Status page — Check status.chatsby.co for real-time platform health.