Chat

Send messages to 20+ AI models including GPT, Claude, Gemini, DeepSeek, and more. By default, Kolbo's Smart Select automatically picks the best model for each message — no model management needed.

Smart Select (Recommended)

Omit the model field and Kolbo automatically analyzes your prompt and routes it to the best available model. Smart Select adapts to your message type (code, creative writing, analysis, etc.) and always uses the latest models.

This is the recommended approach for most use cases.

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 from `GET /api/v1/models?type=chat`. Default: `auto` (Smart Select picks the best model for your prompt). For image/video/audio analysis, use `gemini-2.5-pro` or omit to auto-route.
`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`)
`media_urls`	string[]	No	Public URLs of images, videos, or audio files to analyze. The API auto-routes to a vision-capable model (e.g. Gemini) when media is present. Use `POST /api/v1/media/upload` to get a CDN URL for local files first.

Examples

Basic (Smart Select)

# No "model" field — Smart Select automatically picks the best model
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

If you need a specific model instead of Smart Select, fetch the available models first and use an identifier from the response:

# First, list available chat models to get valid identifiers
curl "https://api.kolbo.ai/api/v1/models?type=chat" \
  -H "X-API-Key: kolbo_live_..."
# Response: { "models": [{ "identifier": "deepseek-chat", ... }, { "identifier": "claude-sonnet-4-6", ... }] }

# Then use a valid identifier from the response above
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": "deepseek-chat"
  }'

Important: Model identifiers are Kolbo-specific and change over time. Do not guess or hardcode model names like gpt-4o or anthropic/claude-3-5-sonnet — these will return a 400 MODEL_NOT_FOUND error. Always fetch identifiers from GET /api/v1/models?type=chat first.

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
  }'

Image / Video / Audio Analysis

Pass public media URLs in media_urls. The API automatically routes to a vision-capable model (Gemini) when media is present — no need to specify the model manually.

# Analyze an image
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 shown in this image? Describe all the text and visual elements.",
    "media_urls": ["https://cdn.kolbo.ai/your-image.jpg"]
  }'

# Analyze a video (auto-routes to gemini-2.5-pro)
curl -X POST https://api.kolbo.ai/api/v1/chat \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Describe what happens in this video and read any text shown on screen.",
    "model": "gemini-2.5-pro",
    "media_urls": ["https://cdn.kolbo.ai/your-video.mp4"]
  }'

For local files, upload first via POST /api/v1/media/upload to get a stable CDN URL, then pass that URL in media_urls.

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 = "kolbo_live_..."; // Replace with your API key
const BASE = "https://api.kolbo.ai/api";

// Smart Select: omit "model" to auto-pick the best model
async function chat(message, sessionId) {
  const body = { message };
  if (sessionId) body.session_id = sessionId;

  const res = await fetch(`${BASE}/v1/chat`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!data.success) throw new Error(data.error);

  // Poll until complete
  let status;
  do {
    await new Promise((r) => setTimeout(r, 2000));
    const poll = await fetch(`${BASE}${data.poll_url}`, {
      headers: { "X-API-Key": API_KEY },
    });
    status = await poll.json();
  } while (status.state === "processing");

  return { content: status.result.content, session_id: data.session_id };
}

// Usage
async function main() {
  const first = await chat("Explain the theory of relativity");
  console.log(first.content);

  // Continue the conversation
  const followUp = await chat("Can you simplify that?", first.session_id);
  console.log(followUp.content);
}
main();

Python

import requests, time

API_KEY = "kolbo_live_..."  # Replace with your API key
BASE = "https://api.kolbo.ai/api"
HEADERS = {"X-API-Key": API_KEY}

def chat(message, session_id=None):
    """Send a chat message. Omits 'model' so Smart Select picks the best one."""
    body = {"message": message}
    if session_id:
        body["session_id"] = session_id

    data = requests.post(f"{BASE}/v1/chat", headers=HEADERS, json=body).json()
    assert data["success"], data.get("error", "Request failed")

    # Poll until complete
    while True:
        time.sleep(2)
        status = requests.get(f"{BASE}{data['poll_url']}", headers=HEADERS).json()
        if status["state"] != "processing":
            break

    return {"content": status["result"]["content"], "session_id": data["session_id"]}

# Usage
first = chat("Explain the theory of relativity")
print(first["content"])

# Continue the conversation
follow_up = chat("Can you simplify that?", first["session_id"])
print(follow_up["content"])

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": "auto",
    "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": "auto"
  }
}

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": "auto",
        "name": "Auto",
        "provider": "Kolbo.AI"
      },
      "created_at": "2026-03-10T10:30:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "pages": 1
  }
}

Finding Models

To use a specific model instead of Smart Select, fetch valid identifiers from the Models endpoint:

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

Use the identifier field from the response as the model value in your chat request. Model identifiers are Kolbo-specific and may differ from the provider's naming. Passing an invalid identifier returns a 400 MODEL_NOT_FOUND error.

Tips

Smart Select is the default: Omit the model field and Kolbo picks the best model for each message. No need to manage model names — this is the recommended approach.
Don't hardcode model names: Models are added and updated frequently. If you need a specific model, fetch identifiers from GET /api/v1/models?type=chat at startup and cache them.
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.
Media analysis: Pass media_urls with public image/video/audio URLs to analyze them. The API auto-routes to a vision-capable model. For local files, upload via POST /api/v1/media/upload first to get a CDN URL.

On this page