Getting Started

Welcome to ChatRoutes API! Our conversation branching platform enables you to create sophisticated AI conversations with branching capabilities, checkpoints, and parallel response generation.

🚀 Quick Start

Get up and running in minutes with our simple API keys and endpoints.

🌳 Branching Conversations

Create conversation trees with multiple paths and parallel AI responses.

⏱️ Checkpoints

Save conversation states and restore them later for time-travel capabilities.

New

🤖 Multi-LLM Support

Integrate with OpenAI, Anthropic Claude, and other leading AI models.

Base URL

https://api.chatroutes.com

Quick Example

curl -H "Authorization: ApiKey cr_prod_sk_your-api-key" \
     https://api.chatroutes.com/api/v1/conversations

Authentication

ChatRoutes uses API keys for authentication. All API requests must include your API key in the Authorization header.

API Key Format

cr_prod_sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Authentication Methods

Method 1: Authorization Header (Recommended)

Authorization: ApiKey cr_prod_sk_your-api-key

Method 2: X-API-Key Header

X-API-Key: cr_prod_sk_your-api-key

Method 3: JWT Bearer Token (User Sessions)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Security: Keep your API keys secure and never expose them in client-side code. Use environment variables or secure key management systems.

Rate Limits

Free Plan: 1,000 calls/month
Starter Plan: 100,000 calls/month
Pro Plan: 1,000,000 calls/month
Enterprise: Custom limits

Conversations API

Core conversation management endpoints for creating, retrieving, updating, and deleting conversations.

GET /api/v1/conversations

List all conversations for the authenticated user with full branch data.

Query Parameters

page integer (optional, default: 1)

Page number for pagination

limit integer (optional, default: 10)

Number of conversations per page

Response

{
  "conversations": [
    {
      "id": "conv_123abc",
      "title": "AI Research Discussion",
      "messageCount": 8,
      "totalMessages": 8,
      "branchCount": 3,
      "branches": [
        {
          "id": "br_main_112mno",
          "title": "Main",
          "messageCount": 8,
          "createdAt": "2025-10-10T10:00:00.000Z"
        }
      ],
      "createdAt": "2025-10-10T10:00:00.000Z",
      "updatedAt": "2025-10-10T12:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

POST /api/v1/conversations

Create a new conversation with optional model configuration.

Request Body

title string (required)

Title for the conversation

model string (optional)

AI model to use (gpt-4, gpt-4-turbo, claude-3-5-sonnet-20241022, etc.)

systemPrompt string (optional)

System prompt for AI behavior customization

temperature float (optional, default: 0.7)

Model temperature (0.0-2.0)

maxTokens integer (optional, default: 2048)

Maximum tokens in response

GET /api/v1/conversations/{id}

Get a specific conversation with all branches and main branch messages.

PATCH /api/v1/conversations/{id}

Update conversation metadata (title, model settings, archive status).

DELETE /api/v1/conversations/{id}

Delete a conversation and all associated data.

Messages

POST /api/v1/conversations/{id}/messages

Add a message to a conversation and get AI response.

Request Body

content string (required)

The message content

branchId string (optional)

Branch to add message to (defaults to main branch)

parentMessageId string (optional)

Parent message ID for branching from specific point

POST /api/v1/conversations/{id}/messages/stream

Send message with streaming response (Server-Sent Events).

GET /api/v1/conversations/{id}/messages

Get all messages for conversation (main branch only).

PATCH /api/v1/messages/{id}

Update message content (for editing).

DELETE /api/v1/messages/{id}

Delete a specific message.

Branching API

Create and manage conversation branches for exploring multiple conversation paths.

Branching Concept: Each conversation starts with a "main" branch. You can create child branches at any message point to explore alternative conversation directions. Messages are completely isolated between branches.

GET /api/v1/conversations/{id}/branches

List all branches in a conversation.

POST /api/v1/conversations/{id}/branches

Create a new branch from a specific message.

Request Body

forkPointMessageId string (required)

Message ID to branch from

title string (required)

Title for the new branch

contextMode string (optional, default: "FULL")

Context inheritance mode: "FULL" (all ancestor messages), "PARTIAL" (limited context), "NONE" (start fresh)

GET /api/v1/conversations/{id}/branches/{branchId}/messages

Get all messages for a specific branch with inherited context.

PATCH /api/v1/conversations/{id}/branches/{branchId}

Update branch metadata (title, archived status).

DELETE /api/v1/conversations/{id}/branches/{branchId}

Delete a branch (main branch cannot be deleted).

POST /api/v1/conversations/{id}/branches/{branchId}/merge

Merge a branch back into its parent with specified strategy.

Request Body

strategy string (optional, default: "append")

Merge strategy: "append", "replace", or "cherry-pick"

POST /api/v1/conversations/{id}/fork

Quick fork operation using forkPointMessageId parameter.

GET /api/v1/conversations/{id}/tree

Get complete conversation tree structure showing all branches and their relationships.

Checkpoints API

Save and restore conversation states at any point in time for version control and time-travel capabilities.

New Feature: Pragmatic Immutability system allows you to create snapshots of conversations and restore them later, enabling undo/redo and exploratory workflows.

GET /api/v1/conversations/{conversationId}/checkpoints

List all checkpoints for a conversation.

Query Parameters

branchId string (optional)

Filter checkpoints by specific branch

Response

{
  "success": true,
  "data": {
    "checkpoints": [
      {
        "id": "ckpt_123abc",
        "conversationId": "conv_456def",
        "branchId": "br_main_789ghi",
        "anchorMessageId": "msg_012jkl",
        "checkpointType": "manual",
        "metadata": {},
        "createdAt": "2025-10-12T10:30:00.000Z"
      }
    ]
  }
}

POST /api/v1/conversations/{conversationId}/checkpoints

Create a new checkpoint at a specific message.

Request Body

branchId string (required)

Branch to create checkpoint for

anchorMessageId string (required)

Message to anchor the checkpoint to

metadata object (optional)

Additional metadata for the checkpoint

POST /api/v1/checkpoints/{checkpointId}/recreate

Restore a conversation to a checkpoint state, creating a new branch with the checkpoint's context.

Response

Returns the restored conversation state with a new branch containing messages up to the checkpoint.

DELETE /api/v1/checkpoints/{checkpointId}

Delete a checkpoint (does not affect conversation data).

Use Cases

Version Control: Save important conversation states before making experimental changes
Undo/Redo: Return to previous conversation states
A/B Testing: Create checkpoints and explore different conversation directions
Collaboration: Share specific conversation states with team members

Usage Tracking API

Track token usage, costs, and API consumption across your account, conversations, and branches.

GET /api/v1/usage

Get comprehensive account-level usage overview with timeframes.

Query Parameters

timeframe string (optional)

Filter by timeframe: "today", "week", "month", "all"

GET /api/v1/usage/summary

Quick simplified usage summary for dashboards.

GET /api/v1/usage/conversations/{conversationId}

Get token usage for a specific conversation (all branches).

Query Parameters

branchId string (optional)

Filter by specific branch within conversation

GET /api/v1/usage/branches/{branchId}

Get token usage for a specific branch.

GET /api/v1/usage/messages/{messageId}

Get token usage for a specific message.

GET /api/v1/usage/pricing

Get model token pricing for frontend cost calculations.

Parallel Responses API

Generate multiple AI responses simultaneously for comparison and selection.

POST /api/v1/conversations/{id}/parallel-responses

Generate multiple parallel responses from different models or with different parameters.

Request Body

content string (required)

Message content to send

models array (optional)

Array of model names to use for parallel generation

count integer (optional, default: 3)

Number of parallel responses to generate

GET /api/v1/response-sessions/{sessionId}

Get parallel response session with all generated candidates.

POST /api/v1/response-sessions/{sessionId}/choose

Choose one response candidate to add to the conversation.

Request Body

candidateId string (required)

ID of the response candidate to select

Billing & Plans API

Manage subscription plans and billing information.

GET /api/v1/billing

Get account billing information and subscription status.

GET /api/v1/plans

List available subscription plans with features and pricing.

Available Models

GET /api/v1/models

Get list of available AI models with streaming capabilities and pricing.

UI & Guest Mode

Information about the web interface and guest mode for UI users.

Note: This section is for users accessing ChatRoutes through the web interface at chatroutes.com. API users do not have access to guest mode endpoints as they require API keys.

Guest Mode (UI Only)

Guest mode allows users to try ChatRoutes without creating an account through the web interface. This feature is designed for the UI and provides:

24-Hour Sessions: Try the platform without signup
Limited Usage: 250 tokens, 3 branches, 20 messages per session
Easy Conversion: Convert guest sessions to full accounts
Rate Limiting: 3 sessions/hour, 10/day per IP

API Users: Guest mode endpoints are not available for API key authentication. All API access requires a registered account with valid API keys.

Web Interface Features

Interactive conversation builder
Visual branch exploration
Checkpoint management UI
Usage analytics dashboard
Real-time streaming responses

For API-based integration, use the endpoints documented in the sections above with your API key authentication.

JavaScript SDK

Our JavaScript SDK makes it easy to integrate ChatRoutes into your applications.

Installation

npm install @chatroutes/sdk

Quick Setup

import { ChatRoutesClient } from '@chatroutes/sdk';

const client = new ChatRoutesClient({
  apiKey: 'cr_prod_sk_your-api-key',
  baseUrl: 'https://api.chatroutes.com'
});

// Create a conversation
const conversation = await client.conversations.create({
  title: 'My First Conversation',
  model: 'gpt-4'
});

// Add a message
const message = await client.conversations.addMessage(conversation.id, {
  content: 'Hello, world!'
});

console.log(message.aiResponse);

Advanced Features

Creating Checkpoints

// Create a checkpoint
const checkpoint = await client.checkpoints.create(conversationId, {
  branchId: 'br_main_123',
  anchorMessageId: 'msg_456'
});

// Restore from checkpoint
const restored = await client.checkpoints.recreate(checkpoint.id);

Branching

// Create a branch
const branch = await client.branches.create(conversationId, {
  forkPointMessageId: 'msg_123',
  title: 'Alternative Path',
  contextMode: 'FULL'
});

// Send message to branch
await client.conversations.addMessage(conversationId, {
  content: 'Exploring alternative direction',
  branchId: branch.id
});

Usage Tracking

// Get usage summary
const usage = await client.usage.summary();
console.log('Tokens used:', usage.tokensUsed);
console.log('Cost this month:', usage.costThisMonth);

// Get conversation usage
const convUsage = await client.usage.getConversationUsage(conversationId);

Framework Support

React

Hooks and components for React applications

useConversation

useBranches

useCheckpoints

Vue 3

Composition API utilities for Vue applications

Composables

Reactivity

Node.js

Server-side utilities and webhook handling

Webhooks

TypeScript

Support & Resources

📧 Email Support

Get help from our technical support team

support@chatroutes.com

🌐 Main Website

Learn more about ChatRoutes platform

chatroutes.com

📚 GitHub SDK

Open source SDK and code examples

github.com/chatroutes/sdk

Common Issues

Authentication Errors: Ensure your API key starts with "cr_prod_sk_" and use the format "Authorization: ApiKey your-key" or "X-API-Key: your-key".

Rate Limiting: If you exceed your rate limits, wait a few minutes or upgrade your plan. Check your usage at /api/v1/usage.

Best Practices: Store API keys securely in environment variables, handle errors gracefully, implement exponential backoff for retries, and use checkpoints for important conversation states.

Status & Monitoring

Check our system status at status.chatroutes.com

Health Check

GET /api/v1/health

Check API health status (no authentication required).

GET /api/v1/status

Get detailed service status with all endpoint listings.