Bot API Reference

Base URL

<your-api-url>

Replace <your-api-url> with your actual API endpoint URL provided by the AI Commons team.

Endpoints Overview

POST /conversation

Create a new conversation or send a follow-up message.

Request Body

{
  "conversation_id": "01KPPB65REFEQGM49YS9YWPAP0",
  "message": {
    "content": [
      {
        "content_type": "text",
        "body": "Your message here"
      }
    ],
    "model": "claude-v4.6-sonnet"
  },
  "continue_generate": false,
  "enable_reasoning": false,
  "inference_params": {
    "temperature": 0.7,
    "max_tokens": 4096,
    "top_p": 0.999,
    "top_k": 250,
    "stop_sequences": []
  }
}

Parameters

Response (202 Accepted)

{
  "conversation_id": "01KPPB65REFEQGM49YS9YWPAP0",
  "message_id": "msg_001"
}

GET /conversation/{id}

Retrieve a conversation and its messages.

Response (200 OK - Complete)

{
  "id": "01KPPB65REFEQGM49YS9YWPAP0",
  "title": "Conversation Title",
  "create_time": 1713456789.123,
  "message_map": {
    "msg_001": {
      "role": "user",
      "content": [...],
      "model": "claude-v4.6-sonnet",
      "children": ["msg_002"],
      "parent": null
    },
    "msg_002": {
      "role": "assistant",
      "content": [...],
      "model": "claude-v4.6-sonnet",
      "children": [],
      "parent": "msg_001"
    }
  },
  "last_message_id": "msg_002",
  "status": "complete"
}

Response (202 Accepted - Processing)

{
  "id": "01KPPB65REFEQGM49YS9YWPAP0",
  "status": "processing",
  "create_time": 1713456789.123
}

Response (404 Not Found)

Conversation is still being processed. Continue polling with adaptive backoff.

GET /conversations

List all conversations for the authenticated user.

Response

[
  {
    "id": "01KPPB65REFEQGM49YS9YWPAP0",
    "title": "Quantum Computing Discussion",
    "create_time": 1713456789.123,
    "model": "claude-v4.6-sonnet",
    "bot_id": null
  }
]

GET /conversations/search

Search conversations by keyword.

Parameters

Example Request

curl -X GET "<your-api-url>/conversations/search?query=quantum" \
  -H "x-api-key: <your-api-key>"

Response

[
  {
    "id": "01KPPB65REFEQGM49YS9YWPAP0",
    "title": "Quantum Computing Discussion",
    "last_updated_time": 1713456789.123,
    "highlights": [
      {
        "field_name": "Title",
        "fragments": ["Quantum Computing Discussion"]
      }
    ]
  }
]

GET /token-usage

Get current token usage statistics for the authenticated user.

Response

{
  "input_tokens": 45000,
  "output_tokens": 32000,
  "total_tokens": 77000,
  "token_limit": 1000000
}

Response Fields

• input_tokens: Number of tokens used for input messages in current month
• output_tokens: Number of tokens used for AI responses in current month
• total_tokens: Combined input + output tokens for current month
• token_limit: Maximum tokens allowed per month for your account

GET /health

Health check endpoint to verify API availability.

Response

{
  "status": "ok"
}

Note: This endpoint does not require authentication.

Content Types

The API supports multiple content types within messages:

Text Content

{
  "content_type": "text",
  "body": "Your text message here"
}

Image Content

{
  "content_type": "image", 
  "media_type": "image/png",
  "body": "base64_encoded_image_data"
}

Supported formats: PNG, JPEG, GIF, WebP

Attachment Content

{
  "content_type": "attachment",
  "file_name": "document.pdf",
  "body": "base64_encoded_file_data"
}

Supported formats: PDF, CSV, DOC, DOCX, XLS, XLSX, HTML, TXT, MD

Tool Use

{
  "content_type": "toolUse",
  "body": {
    "tool_use_id": "tool_123",
    "name": "search_tool",
    "input": {"query": "search term"}
  }
}

Tool Result

{
  "content_type": "toolResult",
  "body": {
    "tool_use_id": "tool_123",
    "status": "success",
    "content": [{"text": "Tool execution result"}]
  }
}

Reasoning

{
  "content_type": "reasoning",
  "text": "Step-by-step reasoning process",
  "signature": "reasoning_signature"
}

Inference Parameters

Control the AI model's behavior with these parameters:

Temperature Guidelines

• 0.0-0.3: Precise, factual responses
• 0.4-0.7: Balanced creativity and consistency
• 0.8-1.0: Creative, diverse responses

Adaptive Polling Strategy

The API uses asynchronous processing. After creating a conversation, poll the GET endpoint using exponential backoff for optimal performance.

Recommended Configuration

Polling Sequence

Attempt 1: Wait 0.3s  → Poll
Attempt 2: Wait 0.45s → Poll (0.3 × 1.5)
Attempt 3: Wait 0.68s → Poll (0.45 × 1.5)
Attempt 4: Wait 1.0s  → Poll (0.68 × 1.5)
Attempt 5: Wait 1.5s  → Poll (1.0 × 1.5)

Status Codes During Polling

Performance Benefits

• Fast responses: Retrieved in ~0.3-1.0s for quick generations
• Efficient: Reduces API calls by 40-60% vs fixed 2s polling
• Adaptive: Automatically adjusts to processing time