AI Chat SDK Platform API Reference

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 #

REST API: https://api.zeebee.ai/v1
WebSocket: wss://api.zeebee.ai/v1/ws

Authentication #

API Key Authentication

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

X-API-Key: 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"

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/completions

Send a text message and receive an AI response.

Request Body

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."}, // Optional
    {"role": "user", "content": "Hello, how can you help me?"}
  ],
  "model": "gpt-4o", // AI model to use
  "conversation_id": "conv_12345", // Optional ID of existing conversation
  "stream": false, // Whether to stream the response
  "temperature": 0.7, // Controls randomness (0-1)
  "max_tokens": 2048, // Maximum tokens in the response
  "user_id": "user123" // User identifier
}

Response

{
  "message": "Hello! I'm an AI assistant powered by GPT-4o...",
  "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": "claude-3-5-sonnet",
      "display_name": "Claude 3.5 Sonnet",
      "provider": "Anthropic",
      "max_tokens": 4096,
      "context_length": 200000
    },
    {
      "id": "model_3",
      "name": "grok-2-1212",
      "display_name": "Grok 2",
      "provider": "xAI",
      "max_tokens": 4096,
      "context_length": 131072
    },
    {
      "id": "model_4",
      "name": "qwen-max",
      "display_name": "Qwen Max",
      "provider": "Alibaba Cloud",
      "max_tokens": 6144,
      "context_length": 32768
    },
    {
      "id": "model_5",
      "name": "gpt-3.5-turbo",
      "display_name": "GPT-3.5 Turbo",
      "provider": "OpenAI",
      "max_tokens": 4096,
      "context_length": 16385
    },
    {
      "id": "model_6",
      "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": "agent_orchestration",
      "enabled": true
    },
    {
      "id": "feature_4",
      "name": "autonomous_routing",
      "enabled": true
    },
    {
      "id": "feature_5",
      "name": "dynamic_layout_engine",
      "enabled": true
    },
    {
      "id": "feature_6",
      "name": "policy_engine",
      "enabled": true
    },
    {
      "id": "feature_7",
      "name": "multi_model_access",
      "enabled": true
    }
  ]
}

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/voice/stt/providers

Get available speech-to-text providers.

Response

{
  "providers": {
    "openai": "OpenAI Whisper",
    "google": "Google Speech-to-Text",
    "azure": "Azure Speech Services"
  }
}

POST /api/voice/stt

Transcribe speech to text.

Request Body

{
  "audio": "base64_encoded_audio_data",
  "config": {
    "encoding": "LINEAR16",
    "sample_rate": 16000,
    "channels": 1,
    "language_code": "en-US"
  },
  "model": "whisper",
  "provider": "openai" // Optional, defaults to "openai"
}

Response

{
  "text": "Hello, how can you help me today?",
  "detected_language": "en",
  "confidence": 0.98
}

Speech Transcription #

GET /api/voice/stt/providers

Get available speech-to-text providers.

Response

{
  "providers": {
    "openai": "OpenAI Whisper",
    "google": "Google Speech-to-Text",
    "azure": "Azure Speech Services"
  }
}

POST /api/voice/stt

Transcribe speech to text.

Request Body

{
  "audio": "base64_encoded_audio_data",
  "config": {
    "encoding": "LINEAR16",
    "sample_rate": 16000,
    "channels": 1,
    "language_code": "en-US"
  },
  "model": "whisper",
  "provider": "openai" // Optional, defaults to "openai"
}

Response

{
  "text": "Hello, how can you help me today?",
  "detected_language": "en",
  "confidence": 0.98
}

POST /api/voice/tts

Convert text to speech.

Request Body

{
  "text": "Hello, I'm your AI assistant. How can I help you today?",
  "voice_id": "default",
  "language_code": "en-US",
  "model": "openai_tts"
}

Response

{
  "audio": "base64_encoded_audio_data",
  "format": "mp3",
  "sample_rate": 24000,
  "duration_seconds": 3.5
}

POST /api/voice/stream

Create a voice streaming session.

Request Body

{
  "user_id": "user123",
  "model": "gpt-4o",
  "conversation_id": "conv_12345", // Optional
  "stt_model": "whisper",
  "tts_model": "openai_tts",
  "voice_id": "default",
  "language_code": "en-US"
}

Response

{
  "session_id": "session_12345",
  "token": "session_token_for_websocket_auth",
  "websocket_url": "wss://api.zeebee.ai/voice/stream/session_12345"
}

Conversation Management #

GET /api/conversations

Get a list of the user's conversations.

Query Parameters

limit: (Optional) Maximum number of conversations to return (default: 20)
offset: (Optional) Offset for pagination (default: 0)
status: (Optional) Filter by status (active/archived/all, default: active)
order: (Optional) Sort order (desc/asc, default: desc)

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,
      "status": "active"
    },
    {
      "id": "conv_67890",
      "title": "Travel recommendations",
      "created_at": "2025-04-19T14:22:10Z",
      "updated_at": "2025-04-19T15:05:22Z",
      "message_count": 12,
      "status": "active"
    }
  ],
  "total": 25,
  "limit": 20,
  "offset": 0
}

POST /api/conversations

Create a new conversation.

Request Body

{
  "title": "New Conversation", // Optional
  "description": "Conversation about programming", // Optional
  "model": "gpt-4o", // Optional
  "system_prompt": "You are a helpful assistant specialized in programming.", // Optional
  "metadata": {} // Optional additional metadata
}

Response

{
  "id": "conv_12345",
  "title": "New Conversation",
  "description": "Conversation about programming",
  "created_at": "2025-04-20T11:30:00Z",
  "updated_at": "2025-04-20T11:30:00Z",
  "system_prompt": "You are a helpful assistant specialized in programming.",
  "model": "gpt-4o"
}

GET /api/conversations/{conversation_id}

Get details for a specific conversation.

Path Parameters

conversation_id: ID of the conversation

Response

{
  "id": "conv_12345",
  "title": "Help with programming",
  "description": "Conversation about Python programming",
  "created_at": "2025-04-20T09:15:30Z",
  "updated_at": "2025-04-20T10:30:45Z",
  "message_count": 8,
  "system_prompt": "You are a helpful assistant specialized in programming.",
  "model": "gpt-4o",
  "status": "active",
  "metadata": {}
}

Agent API #

GET /api/agent/types

Get all available agent types with their capabilities.

Response

{
  "agent_types": [
    {
      "id": "RetrievalAgent",
      "name": "Retrieval Agent",
      "description": "Agent for retrieving information from knowledge bases",
      "capabilities": ["document_retrieval", "knowledge_base_search"]
    },
    {
      "id": "SummarizationAgent",
      "name": "Summarization Agent",
      "description": "Agent for summarizing long-form content",
      "capabilities": ["text_summarization", "key_point_extraction"]
    },
    {
      "id": "ReasoningAgent",
      "name": "Reasoning Agent",
      "description": "Agent for performing logical reasoning and analysis",
      "capabilities": ["logical_reasoning", "problem_solving"]
    },
    {
      "id": "GenerationAgent",
      "name": "Generation Agent",
      "description": "Agent for generating creative content",
      "capabilities": ["text_generation", "creative_writing"]
    },
    {
      "id": "WebAgent",
      "name": "Web Agent",
      "description": "Agent for interacting with web resources",
      "capabilities": ["web_search", "content_extraction"]
    },
    {
      "id": "StructureAgent",
      "name": "Structure Agent",
      "description": "Agent for processing and transforming structured data",
      "capabilities": ["data_processing", "table_generation"]
    }
  ]
}

GET /api/agent/agents

Get all agents available to the current user.

Response

{
  "agents": [
    {
      "id": "agent_1",
      "name": "Research Assistant",
      "description": "Retrieves and analyzes research information",
      "agent_type": "RetrievalAgent",
      "created_at": "2025-05-01T12:00:00Z",
      "updated_at": "2025-05-02T14:30:00Z",
      "is_public": false,
      "model_id": "gpt-4o"
    },
    {
      "id": "agent_2",
      "name": "Code Reviewer",
      "description": "Reviews code and suggests improvements",
      "agent_type": "ReasoningAgent",
      "created_at": "2025-05-01T12:30:00Z",
      "updated_at": "2025-05-01T12:30:00Z",
      "is_public": true,
      "model_id": "claude-3-5-sonnet"
    }
  ]
}

POST /api/agent/agents

Create a new agent.

Request Body

{
  "name": "Data Analysis Agent",
  "agent_type": "StructureAgent",
  "configuration": {
    "processing_steps": ["clean", "analyze", "visualize"],
    "output_format": "json"
  },
  "description": "Analyzes data and provides insights", // Optional
  "model_id": "claude-3-5-sonnet", // Optional
  "is_public": false // Optional, defaults to false
}

Response

{
  "id": "agent_3",
  "name": "Data Analysis Agent",
  "description": "Analyzes data and provides insights",
  "agent_type": "StructureAgent",
  "model_id": "claude-3-5-sonnet",
  "created_at": "2025-05-04T15:30:00Z",
  "updated_at": "2025-05-04T15:30:00Z",
  "is_public": false,
  "configuration": {
    "processing_steps": ["clean", "analyze", "visualize"],
    "output_format": "json"
  }
}

GET /api/agent/agents/{agent_id}

Get details about a specific agent.

Path Parameters

agent_id: ID of the agent to retrieve

Response

{
  "id": "agent_1",
  "name": "Research Assistant",
  "description": "Retrieves and analyzes research information",
  "agent_type": "RetrievalAgent",
  "created_at": "2025-05-01T12:00:00Z",
  "updated_at": "2025-05-02T14:30:00Z",
  "is_public": false,
  "model_id": "gpt-4o",
  "configuration": {
    "search_providers": ["google_scholar", "pubmed"],
    "result_count": 5
  }
}

PUT /api/agent/agents/{agent_id}

Update an existing agent.

Path Parameters

agent_id: ID of the agent to update

Request Body

{
  "name": "Improved Research Assistant", // Optional
  "description": "Enhanced agent for research tasks", // Optional
  "configuration": { // Optional
    "search_providers": ["google_scholar", "pubmed", "arxiv"],
    "result_count": 10
  },
  "model_id": "claude-3-opus", // Optional
  "is_public": true // Optional
}

Response

{
  "id": "agent_1",
  "name": "Improved Research Assistant",
  "description": "Enhanced agent for research tasks",
  "agent_type": "RetrievalAgent",
  "created_at": "2025-05-01T12:00:00Z",
  "updated_at": "2025-05-04T16:45:00Z",
  "is_public": true,
  "model_id": "claude-3-opus",
  "configuration": {
    "search_providers": ["google_scholar", "pubmed", "arxiv"],
    "result_count": 10
  }
}

DELETE /api/agent/agents/{agent_id}

Delete an agent.

Path Parameters

agent_id: ID of the agent to delete

Response

{
  "success": true,
  "message": "Agent deleted successfully",
  "id": "agent_1"
}

POST /api/agent/agents/{agent_id}/execute

Execute an agent with the provided input data.

Path Parameters

agent_id: ID of the agent to execute

Request Body

{
  // Input data depends on the agent type
  "query": "Analyze the latest trends in renewable energy adoption.",
  "parameters": {
    "max_results": 5,
    "include_charts": true
  }
}

Response

{
  "success": true,
  "execution_id": "exec_12345",
  "result": {
    "analysis": "Based on recent data, renewable energy adoption is accelerating globally...",
    "key_findings": [
      "Solar PV installations increased by 25% in 2024",
      "Wind power capacity expanded by 19% year-over-year",
      "Green hydrogen projects have tripled since 2023"
    ],
    "chart_data": {
      "labels": ["2020", "2021", "2022", "2023", "2024"],
      "datasets": [...]
    }
  },
  "metrics": {
    "execution_time_ms": 2400,
    "tokens_used": 1256
  }
}

Pipeline API #

POST /api/agent/pipelines

Create a new pipeline.

Request Body

{
  "name": "Search and Summarize",
  "stages": [ // Optional
    {
      "agent_id": "agent_1",
      "name": "Web Search",
      "input_mapping": {"query": "$.input.search_query"},
      "output_mapping": {"search_results": "$.output.results"}
    },
    {
      "agent_id": "agent_2",
      "name": "Summarize",
      "input_mapping": {"text": "$.stages.Web Search.search_results"},
      "output_mapping": {"summary": "$.output.summary"}
    }
  ],
  "description": "Pipeline that searches the web and summarizes the results", // Optional
  "visual_layout": { // Optional
    "nodes": [...],
    "edges": [...]
  }
}

Response

{
  "pipeline_id": "pipeline_12345",
  "name": "Search and Summarize",
  "description": "Pipeline that searches the web and summarizes the results",
  "created_at": "2025-05-04T17:30:00Z",
  "updated_at": "2025-05-04T17:30:00Z",
  "stages": [
    {
      "id": "stage_1",
      "agent_id": "agent_1",
      "name": "Web Search",
      "input_mapping": {"query": "$.input.search_query"},
      "output_mapping": {"search_results": "$.output.results"}
    },
    {
      "id": "stage_2",
      "agent_id": "agent_2",
      "name": "Summarize",
      "input_mapping": {"text": "$.stages.Web Search.search_results"},
      "output_mapping": {"summary": "$.output.summary"}
    }
  ]
}

GET /api/agent/pipelines/{pipeline_id}

Get details about a specific pipeline.

Path Parameters

pipeline_id: ID of the pipeline to retrieve

Response

{
  "pipeline": {
    "id": "pipeline_12345",
    "name": "Search and Summarize",
    "description": "Pipeline that searches the web and summarizes the results",
    "created_at": "2025-05-04T17:30:00Z",
    "updated_at": "2025-05-04T17:30:00Z",
    "configuration": {
      "stages": [
        {
          "id": "stage_1",
          "agent_id": "agent_1",
          "name": "Web Search",
          "input_mapping": {"query": "$.input.search_query"},
          "output_mapping": {"search_results": "$.output.results"}
        },
        {
          "id": "stage_2",
          "agent_id": "agent_2",
          "name": "Summarize",
          "input_mapping": {"text": "$.stages.Web Search.search_results"},
          "output_mapping": {"summary": "$.output.summary"}
        }
      ]
    },
    "visual_layout": {
      "nodes": [...],
      "edges": [...]
    }
  }
}

PUT /api/agent/pipelines/{pipeline_id}

Update an existing pipeline.

Path Parameters

pipeline_id: ID of the pipeline to update

Request Body

{
  "name": "Improved Search and Summarize", // Optional
  "description": "Enhanced pipeline for search and summarization", // Optional
  "stages": [ // Optional
    {
      "agent_id": "agent_1",
      "name": "Web Search",
      "input_mapping": {"query": "$.input.search_query"},
      "output_mapping": {"search_results": "$.output.results"}
    },
    {
      "agent_id": "agent_3",
      "name": "Analysis",
      "input_mapping": {"data": "$.stages.Web Search.search_results"},
      "output_mapping": {"analysis": "$.output.analysis"}
    },
    {
      "agent_id": "agent_2",
      "name": "Summarize",
      "input_mapping": {"text": "$.stages.Analysis.analysis"},
      "output_mapping": {"summary": "$.output.summary"}
    }
  ],
  "visual_layout": { // Optional
    "nodes": [...],
    "edges": [...]
  }
}

Response

{
  "id": "pipeline_12345",
  "name": "Improved Search and Summarize",
  "description": "Enhanced pipeline for search and summarization",
  "created_at": "2025-05-04T17:30:00Z",
  "updated_at": "2025-05-05T09:15:00Z",
  "stages": [
    {
      "id": "stage_1",
      "agent_id": "agent_1",
      "name": "Web Search",
      "input_mapping": {"query": "$.input.search_query"},
      "output_mapping": {"search_results": "$.output.results"}
    },
    {
      "id": "stage_3",
      "agent_id": "agent_3",
      "name": "Analysis",
      "input_mapping": {"data": "$.stages.Web Search.search_results"},
      "output_mapping": {"analysis": "$.output.analysis"}
    },
    {
      "id": "stage_2",
      "agent_id": "agent_2",
      "name": "Summarize",
      "input_mapping": {"text": "$.stages.Analysis.analysis"},
      "output_mapping": {"summary": "$.output.summary"}
    }
  ]
}

DELETE /api/agent/pipelines/{pipeline_id}

Delete a pipeline.

Path Parameters

pipeline_id: ID of the pipeline to delete

Response

{
  "success": true,
  "message": "Pipeline deleted successfully",
  "id": "pipeline_12345"
}

POST /api/agent/pipelines/{pipeline_id}/execute

Execute a pipeline with the provided input data.

Path Parameters

pipeline_id: ID of the pipeline to execute

Request Body

{
  // Input data depends on the pipeline's input_mapping
  "search_query": "What are the health benefits of meditation?",
  "max_results": 5,
  "conversation_id": "conv_12345" // Optional
}

Response

{
  "execution_id": "exec_67890",
  "status": "completed",
  "pipeline_id": "pipeline_12345",
  "output": {
    "summary": "Meditation has been found to have numerous health benefits, including reduced stress and anxiety...",
    "key_points": [
      "Reduces stress and anxiety",
      "Lowers blood pressure",
      "Improves sleep quality",
      "Enhances focus and concentration",
      "May reduce age-related memory loss"
    ]
  },
  "metrics": {
    "execution_time_ms": 4320,
    "stages_completed": 3
  }
}

GET /api/agent/pipelines/{pipeline_id}/executions

Get all executions of a pipeline.

Path Parameters

pipeline_id: ID of the pipeline

Response

{
  "executions": [
    {
      "id": "exec_67890",
      "pipeline_id": "pipeline_12345",
      "status": "completed",
      "created_at": "2025-05-05T10:30:00Z",
      "completed_at": "2025-05-05T10:30:04Z",
      "execution_time_ms": 4320
    },
    {
      "id": "exec_67891",
      "pipeline_id": "pipeline_12345",
      "status": "failed",
      "created_at": "2025-05-05T09:15:00Z",
      "completed_at": "2025-05-05T09:15:02Z",
      "execution_time_ms": 2100,
      "error": "Error in Web Search stage: Failed to connect to search API"
    }
  ],
  "total": 2
}

GET /api/agent/executions/{execution_id}

Get detailed information about a specific pipeline execution.

Path Parameters

execution_id: ID of the execution to retrieve

Response

{
  "execution": {
    "id": "exec_67890",
    "pipeline_id": "pipeline_12345",
    "status": "completed",
    "created_at": "2025-05-05T10:30:00Z",
    "completed_at": "2025-05-05T10:30:04Z",
    "execution_time_ms": 4320,
    "input": {
      "search_query": "What are the health benefits of meditation?",
      "max_results": 5
    },
    "output": {
      "summary": "Meditation has been found to have numerous health benefits...",
      "key_points": [...]
    },
    "stages": [
      {
        "id": "stage_1",
        "name": "Web Search",
        "agent_id": "agent_1",
        "status": "completed",
        "started_at": "2025-05-05T10:30:00Z",
        "completed_at": "2025-05-05T10:30:02Z",
        "execution_time_ms": 2000,
        "input": {
          "query": "What are the health benefits of meditation?"
        },
        "output": {
          "search_results": [...]
        }
      },
      {
        "id": "stage_3",
        "name": "Analysis",
        "agent_id": "agent_3",
        "status": "completed",
        "started_at": "2025-05-05T10:30:02Z",
        "completed_at": "2025-05-05T10:30:03Z",
        "execution_time_ms": 1000,
        "input": {
          "data": [...]
        },
        "output": {
          "analysis": [...]
        }
      },
      {
        "id": "stage_2",
        "name": "Summarize",
        "agent_id": "agent_2",
        "status": "completed",
        "started_at": "2025-05-05T10:30:03Z",
        "completed_at": "2025-05-05T10:30:04Z",
        "execution_time_ms": 1320,
        "input": {
          "text": [...]
        },
        "output": {
          "summary": "Meditation has been found to have numerous health benefits...",
          "key_points": [...]
        }
      }
    ]
  }
}

Routing API #

POST /api/routing/detect-intent

Detect the intent from a user message.

Request Body

{
  "message": "Can you analyze this dataset and create a visualization?",
  "conversation_id": "conv_12345"  // Optional
}

Response

{
  "success": true,
  "intent": {
    "id": "intent_12345",
    "text": "Can you analyze this dataset and create a visualization?",
    "category": "DATA_ANALYSIS",
    "confidence": 0.95,
    "timestamp": "2025-05-04T15:50:00Z",
    "metadata": {
      "detected_entities": ["dataset", "visualization"],
      "complexity": "medium"
    }
  }
}

POST /api/routing/route

Route a user message to the appropriate agent, pipeline, or model.

Request Body

{
  "message": "Can you analyze this dataset and create a visualization?",
  "conversation_id": "conv_12345",  // Optional
  "context": {  // Optional
    "history": [
      {"role": "user", "content": "I have a CSV file with sales data."},
      {"role": "assistant", "content": "Great! What would you like to do with this sales data?"}
    ],
    "preferences": {
      "preferred_models": ["gpt-4o"],
      "routing_strategy": "performance"
    }
  }
}

Response

{
  "success": true,
  "route_to": "DataAnalysisAgent",
  "route_type": "agent",
  "confidence": 0.85,
  "intent": {
    "id": "intent_12345",
    "category": "DATA_ANALYSIS",
    "confidence": 0.95
  },
  "rationale": "The user is requesting data analysis and visualization, which aligns with the capabilities of the DataAnalysisAgent.",
  "alternative_routes": [
    {
      "route_to": "VisualizationPipeline",
      "route_type": "pipeline",
      "confidence": 0.70
    },
    {
      "route_to": "gpt-4o",
      "route_type": "model",
      "confidence": 0.65
    }
  ]
}

POST /api/routing/feedback

Provide feedback on a routing decision to improve future routing.

Request Body

{
  "message": "Can you analyze this dataset and create a visualization?",
  "selected_route": "CodeAssistantAgent",
  "conversation_id": "conv_12345"  // Optional
}

Response

{
  "success": true,
  "message": "Feedback recorded successfully",
  "feedback_id": "feedback_12345"
}

Dynamic Layout API #

POST /api/routing/test/layout

Generate a dynamic layout based on message complexity and routing.

Request Body

{
  "message": "Can you create a table comparing different programming languages?",
  "routing_result": {  // Optional
    "route_to": "StructureAgent",
    "route_type": "agent",
    "suggested_template": "table-layout",
    "content_analysis": {
      "contentTypes": ["table", "comparison"],
      "complexity": "medium"
    }
  }
}

Response

{
  "success": true,
  "layout": {
    "template": "table-layout",
    "components": [
      {
        "type": "table",
        "id": "comparison-table",
        "config": {
          "headers": true,
          "striped": true,
          "sortable": true
        }
      },
      {
        "type": "text",
        "id": "explanation",
        "config": {
          "format": "markdown"
        }
      }
    ],
    "styling": {
      "color_scheme": "technical",
      "fonts": {
        "headings": "Roboto",
        "body": "Open Sans"
      }
    },
    "content_analysis": {
      "contentTypes": ["table", "comparison"],
      "complexity": "medium"
    }
  }
}

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:

init - Initialization message
text - Text message
audio - Audio message
text_response - Text response from the AI
audio_response - Audio response from the AI
transcript - Transcription result
error - Error message

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 ZeebeeClient({
  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.

Getting Started

API References

SDK

AI Chat SDK Platform API Reference

Table of Contents

Introduction #

Base URLs #

Authentication #

API Key Authentication

Session Authentication

Common Parameters #

REST API Endpoints #

Health Check #

Chat #

Available Models #

Available Features #

Prompt Templates #

Feedback #

Speech Transcription #

Speech Transcription #

Conversation Management #

Agent API #

Pipeline API #

Routing API #

Dynamic Layout API #

WebSocket API #

Connection

Message Types

Rate Limits #

Error Codes #

SDKs and Client Libraries #

Example Usage #

Basic Chat Example (JavaScript)