Chat

Send messages to 20+ AI models including GPT-4o, Claude, Gemini, DeepSeek, and more. The API automatically manages conversation sessions for multi-turn conversations.

Send a Message

POST /api/v1/chat

Request Body

Field	Type	Required	Description
`message`	string	Yes	The message to send to the AI model
`model`	string	No	Model identifier (default: auto-select best model)
`session_id`	string	No	Continue an existing conversation. Omit to start a new one
`system_prompt`	string	No	System prompt for new conversations (ignored if `session_id` is provided)
`enhance_prompt`	boolean	No	Enhance prompt for better results (default: `true`)
`web_search`	boolean	No	Enable web search for up-to-date information (default: `false`)
`deep_think`	boolean	No	Enable deep thinking/reasoning mode (default: `false`)

Examples

Basic

curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain quantum computing in simple terms"}'

With Specific Model

curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Write a Python function to sort a list",
    "model": "gpt-4o",
    "system_prompt": "You are a senior Python developer. Write clean, well-documented code."
  }'

Multi-Turn Conversation

# First message (starts new conversation)
curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "What is machine learning?"}'

# Response includes session_id
# {"success": true, "session_id": "abc123", ...}

# Follow-up message (continues conversation)
curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Give me a practical example",
    "session_id": "abc123"
  }'

With Web Search

curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the latest AI developments this week?",
    "web_search": true
  }'

With Deep Thinking

curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Solve this math problem step by step: ...",
    "deep_think": true
  }'

JavaScript

const API_KEY = process.env.KOLBO_API_KEY;
const BASE = 'https://api.kolbo.ai/api';

// Send a message
const response = await fetch(`${BASE}/v1/chat`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Explain the theory of relativity',
    model: 'gpt-4o'
  })
});

const { message_id, session_id, poll_url } = await response.json();

// Poll for the AI response
let result;
do {
  await new Promise(r => setTimeout(r, 2000));
  const status = await fetch(`${BASE}${poll_url}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  result = await status.json();
} while (result.state === 'processing');

console.log('Response:', result.result.content);

// Continue the conversation
const followUp = await fetch(`${BASE}/v1/chat`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Can you simplify that?',
    session_id: session_id
  })
});

Python

import requests
import time

API_KEY = "kolbo_live_..."
BASE = "https://api.kolbo.ai/api"

# Send a message
r = requests.post(f"{BASE}/v1/chat",
    headers={"X-API-Key": API_KEY},
    json={
        "message": "Explain the theory of relativity",
        "model": "gpt-4o"
    })
data = r.json()
session_id = data["session_id"]

# Poll for response
while True:
    time.sleep(2)
    s = requests.get(f"{BASE}{data['poll_url']}",
        headers={"X-API-Key": API_KEY}).json()
    if s["state"] != "processing":
        break

print("Response:", s["result"]["content"])

# Continue conversation
r2 = requests.post(f"{BASE}/v1/chat",
    headers={"X-API-Key": API_KEY},
    json={
        "message": "Can you simplify that?",
        "session_id": session_id
    })

Response

Message Sent

{
  "success": true,
  "message_id": "abc123",
  "session_id": "def456",
  "type": "chat",
  "model": "auto",
  "poll_url": "/api/v1/generate/abc123/status",
  "poll_interval_hint": 2
}

Completed Status (via polling)

{
  "success": true,
  "generation_id": "abc123",
  "type": "chat",
  "state": "completed",
  "progress": 100,
  "result": {
    "content": "Quantum computing uses quantum bits (qubits) that can exist in multiple states simultaneously...",
    "model": "gpt-4o",
    "created_at": "2026-03-10T10:30:00Z"
  }
}

If the model generates images, videos, or audio within the chat, they appear in the result:

{
  "result": {
    "content": "Here's the image you requested...",
    "image_urls": ["https://cdn.kolbo.ai/images/..."],
    "model": "gpt-4o"
  }
}

List Conversations

GET /api/v1/chat/conversations

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 20, max: 50)

curl "https://api.kolbo.ai/api/v1/chat/conversations" \
  -H "X-API-Key: kolbo_live_..."

{
  "success": true,
  "conversations": [
    {
      "session_id": "def456",
      "name": "API Chat - 2026-03-10",
      "last_activity": "2026-03-10T10:30:00Z",
      "created_at": "2026-03-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Get Conversation Messages

GET /api/v1/chat/conversations/:sessionId/messages

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 50, max: 100)

curl "https://api.kolbo.ai/api/v1/chat/conversations/def456/messages" \
  -H "X-API-Key: kolbo_live_..."

{
  "success": true,
  "session_id": "def456",
  "messages": [
    {
      "message_id": "msg1",
      "role": "user",
      "content": "Explain quantum computing",
      "status": "completed",
      "created_at": "2026-03-10T10:30:00Z"
    },
    {
      "message_id": "msg2",
      "role": "assistant",
      "content": "Quantum computing uses quantum bits...",
      "status": "completed",
      "model": {
        "identifier": "gpt-4o",
        "name": "GPT-4o",
        "provider": "openai"
      },
      "created_at": "2026-03-10T10:30:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "pages": 1
  }
}

Finding Models

Use the Models endpoint to discover available chat models:

curl "https://api.kolbo.ai/api/v1/models?type=chat" \
  -H "X-API-Key: kolbo_live_..."

Tips

Auto-select: Omit the model field to let Kolbo's Smart Select choose the best model for your message.
Conversations: Use session_id to maintain context across multiple messages. The AI remembers the full conversation.
Web search: Set web_search: true for questions about current events or recent information.
Deep thinking: Set deep_think: true for complex reasoning tasks (math, logic, analysis). Uses more credits.

On this page