AI Chat SDK Platform API Reference

Table of Contents

Introduction #

The AI Chat SDK Platform provides a comprehensive set of APIs for integrating AI conversational capabilities into your applications. This document serves as a reference for all available API endpoints, WebSocket interactions, and common usage patterns.

Base URLs #

For local development:

Authentication #

API Key Authentication

Most API endpoints require authentication using an API key. Include your API key in all requests using the Authorization header: 

Authorization: Bearer YOUR_API_KEY

You can manage your API keys in the dashboard or through the API key management endpoints.

Session Authentication

For web applications, you can use session-based authentication. The platform uses HTTP cookies to maintain session state.

Note: For more detailed information on authentication, see the Authentication Guide.

Common Parameters #

All endpoints accept the following common parameters:

Parameter Type Description
user_id string (Required) Identifier for the user. Use a consistent ID to maintain conversation history
conversation_id string (Optional) ID of an existing conversation. If not provided, a new conversation will be created
model string (Optional) AI model to use. Defaults to "gpt-4o"

REST API Endpoints #

Health Check #

GET /api/health
Returns the current status of the API service.
Response
{
  "status": "ok",
  "service": "AI Chat SDK Platform",
  "version": "0.1.0"
}

Chat #

POST /api/chat
Send a text message and receive an AI response.
Request Body
{
  "message": "Hello, how can you help me?",
  "model": "gpt-4o",
  "user_id": "user123",
  "conversation_id": null,
  "system_prompt": "You are a helpful assistant."
}
Response
{
  "message": "Hello! I'm an AI assistant powered by GPT-4o. I can help you with information, answer questions, assist with tasks like writing, creative brainstorming, and much more. Just let me know what you need help with, and I'll do my best to assist you!",
  "conversation_id": "conv_12345",
  "message_id": "msg_67890"
}

Available Models #

GET /api/models
Get a list of available AI models.
Response
{
  "models": [
    {
      "id": "model_1",
      "name": "gpt-4o",
      "display_name": "GPT-4o",
      "provider": "OpenAI",
      "max_tokens": 8192,
      "context_length": 128000
    },
    {
      "id": "model_2",
      "name": "gpt-3.5-turbo",
      "display_name": "GPT-3.5 Turbo",
      "provider": "OpenAI",
      "max_tokens": 4096,
      "context_length": 4096
    },
    {
      "id": "model_3",
      "name": "claude-3-opus",
      "display_name": "Claude 3 Opus",
      "provider": "Anthropic",
      "max_tokens": 4096,
      "context_length": 200000
    }
  ]
}

Available Features #

GET /api/available_features
Get a list of features available to the user based on their subscription tier.
Response
{
  "features": [
    {
      "id": "feature_1",
      "name": "voice_chat",
      "enabled": true
    },
    {
      "id": "feature_2",
      "name": "semantic_search",
      "enabled": true
    },
    {
      "id": "feature_3",
      "name": "multi_agent",
      "enabled": false
    }
  ]
}

Prompt Templates #

GET /api/templates
Get available system prompt templates.
Response
{
  "templates": [
    {
      "id": "template_1",
      "name": "standard_assistant",
      "display_name": "Standard Assistant",
      "description": "A general-purpose AI assistant"
    },
    {
      "id": "template_2",
      "name": "expert_assistant",
      "display_name": "Expert Assistant",
      "description": "An expert-level AI assistant for specialized topics"
    },
    {
      "id": "template_3",
      "name": "customer_support_assistant",
      "display_name": "Customer Support",
      "description": "An assistant specialized in customer support interactions"
    }
  ]
}
GET /api/template/{template_name}
Get details for a specific template.
Path Parameters
  • template_name: Name of the template to retrieve
Response
{
  "id": "template_1",
  "name": "standard_assistant",
  "display_name": "Standard Assistant",
  "description": "A general-purpose AI assistant",
  "system_prompt": "You are a helpful AI assistant named Zeebee. Be concise, accurate, and helpful in your responses.",
  "variables": ["additional_instructions"],
  "example_usage": "You can add additional instructions like {\"additional_instructions\": \"Focus on technical explanations\"}"
}
POST /api/conversation/{conversation_id}/template
Update the system prompt template for an existing conversation.
Path Parameters
  • conversation_id: ID of the conversation to update
Request Body
{
  "template_name": "expert_assistant",
  "variables": {
    "additional_instructions": "Focus on providing technical explanations with code examples."
  }
}
Response
{
  "status": "success",
  "conversation_id": "conv_12345",
  "template": "expert_assistant"
}

Feedback #

POST /api/feedback
Submit feedback for an AI response.
Request Body
{
  "conversation_id": "conv_12345",
  "message_id": "msg_67890",
  "feedback_type": "thumbs_up",
  "feedback_value": 1,
  "comment": "Great response!",
  "user_id": "user123"
}
Response
{
  "status": "success",
  "feedback_id": "feedback_12345"
}
GET /api/feedback/analyze/{conversation_id}
Get an analysis of feedback for a specific conversation.
Path Parameters
  • conversation_id: ID of the conversation to analyze
Response
{
  "conversation_id": "conv_12345",
  "total_messages": 10,
  "messages_with_feedback": 5,
  "positive_feedback": 4,
  "negative_feedback": 1,
  "average_rating": 4.5,
  "feedback_details": [
    {
      "message_id": "msg_67890",
      "feedback_type": "thumbs_up",
      "feedback_value": 1,
      "timestamp": "2025-04-20T10:30:45Z"
    }
  ]
}

Speech Transcription #

GET /api/speech/providers
Get available speech-to-text providers.
Response
{
  "providers": {
    "openai": "OpenAI Whisper",
    "google": "Google Speech-to-Text",
    "azure": "Azure Speech Services"
  }
}
POST /api/transcribe
Transcribe speech to text.
Request Body

Content-Type: multipart/form-data

  • audio: Binary audio data
  • provider: Speech provider (e.g., "openai")
  • language_code: Language code (e.g., "en")
Response
{
  "text": "Hello, how can you help me today?",
  "detected_language": "en",
  "confidence": 0.98
}
GET /api/websocket/config
Get configuration information for connecting to the WebSocket server.
Response
{
  "websocket": {
    "url": "ws://localhost:6789",
    "port": 6789
  },
  "tts": {
    "providers": {
      "openai": "OpenAI TTS",
      "elevenlabs": "ElevenLabs",
      "google": "Google Text-to-Speech",
      "azure": "Azure Speech Services"
    },
    "voices": [
      {
        "provider": "openai",
        "id": "alloy",
        "name": "Alloy",
        "gender": "neutral"
      },
      {
        "provider": "openai",
        "id": "nova",
        "name": "Nova",
        "gender": "female"
      }
    ]
  },
  "stt": {
    "providers": {
      "openai": "OpenAI Whisper",
      "google": "Google Speech-to-Text",
      "azure": "Azure Speech Services"
    }
  },
  "languages": [
    {
      "code": "en",
      "name": "English"
    },
    {
      "code": "es",
      "name": "Spanish"
    }
  ],
  "defaults": {
    "tts_provider": "openai",
    "openai_voice": "alloy",
    "elevenlabs_voice": "kgG7dCoKCfLehAPWkJOE",
    "language": "en"
  }
}

Conversation Management #

GET /api/conversations
Get a list of the user's conversations.
Query Parameters
  • user_id: (Required) ID of the user
  • limit: (Optional) Maximum number of conversations to return (default: 10)
  • offset: (Optional) Offset for pagination (default: 0)
Response
{
  "conversations": [
    {
      "id": "conv_12345",
      "title": "Help with programming",
      "created_at": "2025-04-20T09:15:30Z",
      "updated_at": "2025-04-20T10:30:45Z",
      "message_count": 8
    },
    {
      "id": "conv_67890",
      "title": "Travel recommendations",
      "created_at": "2025-04-19T14:22:10Z",
      "updated_at": "2025-04-19T15:05:22Z",
      "message_count": 12
    }
  ],
  "total": 25,
  "limit": 10,
  "offset": 0
}
GET /api/conversation/{conversation_id}/messages
Get messages for a specific conversation.
Path Parameters
  • conversation_id: ID of the conversation
Query Parameters
  • limit: (Optional) Maximum number of messages to return (default: 50)
  • offset: (Optional) Offset for pagination (default: 0)
Response
{
  "conversation_id": "conv_12345",
  "title": "Help with programming",
  "messages": [
    {
      "id": "msg_12345",
      "role": "user",
      "content": "How do I write a function in Python?",
      "created_at": "2025-04-20T09:15:30Z"
    },
    {
      "id": "msg_67890",
      "role": "assistant",
      "content": "To write a function in Python, you use the `def` keyword followed by the function name and parentheses. Here's a simple example:\n\n```python\ndef greet(name):\n    return f\"Hello, {name}!\"\n\n# Call the function\nresult = greet(\"World\")\nprint(result)  # Outputs: Hello, World!\n```\n\nThis function is called `greet`, takes one parameter `name`, and returns a greeting string. Would you like me to explain more about Python functions?",
      "created_at": "2025-04-20T09:15:35Z"
    }
  ],
  "total": 8,
  "limit": 50,
  "offset": 0
}
DELETE /api/conversation/{conversation_id}
Delete a specific conversation.
Path Parameters
  • conversation_id: ID of the conversation to delete
Response
{
  "status": "success",
  "message": "Conversation deleted successfully"
}
POST /api/search/conversations
Search for conversations using semantic search.
Request Body
{
  "query": "python programming",
  "user_id": "user123",
  "limit": 10
}
Response
{
  "results": [
    {
      "conversation_id": "conv_12345",
      "title": "Help with programming",
      "created_at": "2025-04-20T09:15:30Z",
      "updated_at": "2025-04-20T10:30:45Z",
      "similarity_score": 0.92,
      "snippet": "How do I write a function in Python?"
    },
    {
      "conversation_id": "conv_23456",
      "title": "Python data analysis",
      "created_at": "2025-04-18T11:22:15Z",
      "updated_at": "2025-04-18T12:05:30Z",
      "similarity_score": 0.85,
      "snippet": "I need help with pandas data frames in Python"
    }
  ]
}
POST /api/search/messages
Search for specific messages using semantic search.
Request Body
{
  "query": "python function examples",
  "user_id": "user123",
  "conversation_id": "conv_12345",  // Optional - limit to a specific conversation
  "limit": 10
}
Response
{
  "results": [
    {
      "message_id": "msg_67890",
      "conversation_id": "conv_12345",
      "role": "assistant",
      "content": "To write a function in Python, you use the `def` keyword...",
      "created_at": "2025-04-20T09:15:35Z",
      "similarity_score": 0.94
    },
    {
      "message_id": "msg_34567",
      "conversation_id": "conv_23456",
      "role": "assistant",
      "content": "Here are some examples of Python functions with different parameter types...",
      "created_at": "2025-04-18T11:25:10Z",
      "similarity_score": 0.89
    }
  ]
}

WebSocket API #

The WebSocket API allows for real-time communication, particularly for voice chat functionality. For detailed information, see the WebSocket API Documentation.

Connection

Connect to the WebSocket server using the URL from the WebSocket configuration endpoint:

const socket = new WebSocket('ws://localhost:6789');

Message Types

All WebSocket messages use JSON format with a type field that determines the message's purpose. Key message types include:

Rate Limits #

The platform implements rate limiting to ensure fair usage:

Tier Requests per minute Requests per day
Free 10 100
Basic 60 1,000
Pro 120 5,000
Enterprise 500 50,000

When rate limits are exceeded, the API will return a 429 status code with information about when the rate limit will reset.

Error Codes #

Status Code Meaning Description
200 OK Request succeeded
400 Bad Request Invalid request format or parameters
401 Unauthorized Missing or invalid API key
403 Forbidden Valid API key but insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server encountered an error

SDKs and Client Libraries #

The AI Chat SDK Platform provides client libraries for easy integration:

Example Usage #

Basic Chat Example (JavaScript)

import { ZeebeeAI } from 'zeebee-ai-client';

// Initialize the client
const client = new ZeebeeAI({
  apiKey: 'YOUR_API_KEY',
  userId: 'user123'
});

// Send a message and get a response
async function sendMessage() {
  const response = await client.chat({
    message: 'Hello, how can you help me?',
    model: 'gpt-4o'
  });
  
  console.log(response.message);
  console.log(`Conversation ID: ${response.conversation_id}`);
}

sendMessage();

For more examples and implementation patterns, see the Examples page.