REST API Reference

    Complete reference for all AIE REST API endpoints. Each endpoint includes detailed parameters, request/response examples, and implementation notes.

    Chatbots API

    Manage your AI chatbots - create, update, configure, and deploy them.

    GET
    /chatbots

    Retrieve a list of all your chatbots with their current status and configuration.

    Parameters

    NameTypeRequiredDescription
    page
    integer
    Optional
    		Page number for pagination (default: 1)
    limit
    integer
    Optional
    		Number of results per page (default: 20, max: 100)
    status
    string
    Optional
    		Filter by status: active, inactive, draft

    Request Example

    // Using JavaScript SDK
const chatbots = await aie.chatbots.list({
  page: 1,
  limit: 10,
  status: 'active'
});

// Using fetch
const response = await fetch('https://api.aie.ai/v1/chatbots?page=1&limit=10', {
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  }
});

    Response Example

    {
  "success": true,
  "data": [
    {
      "id": "chatbot_123",
      "name": "Customer Support Bot",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "settings": {
        "language": "en",
        "tone": "friendly"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "pages": 3
  }
}
    POST
    /chatbots

    Create a new chatbot with custom configuration and training data.

    Parameters

    NameTypeRequiredDescription
    name
    string
    Required
    		Display name for the chatbot
    description
    string
    Optional
    		Brief description of the chatbot purpose
    settings
    object
    Optional
    		Configuration object with language, tone, etc.

    Request Example

    const newChatbot = await aie.chatbots.create({
  name: "Sales Assistant",
  description: "AI assistant for sales inquiries and product information",
  settings: {
    language: "en",
    tone: "professional",
    max_tokens: 150,
    temperature: 0.7
  }
});

    Response Example

    {
  "success": true,
  "data": {
    "id": "chatbot_456",
    "name": "Sales Assistant",
    "status": "draft",
    "api_key": "cb_456_abc123...",
    "created_at": "2024-01-15T11:00:00Z"
  }
}
    PUT
    /chatbots/{id}

    Update an existing chatbot's configuration, training data, or settings.

    Parameters

    NameTypeRequiredDescription
    id
    string
    Required
    		Unique identifier of the chatbot to update
    name
    string
    Optional
    		New display name for the chatbot
    settings
    object
    Optional
    		Updated configuration settings

    Request Example

    const updatedBot = await aie.chatbots.update('chatbot_456', {
  name: "Sales Assistant Pro",
  settings: {
    tone: "enthusiastic",
    max_tokens: 200
  }
});

    Response Example

    {
  "success": true,
  "data": {
    "id": "chatbot_456",
    "name": "Sales Assistant Pro",
    "status": "active",
    "updated_at": "2024-01-15T11:30:00Z"
  }
}

    Conversations API

    Manage chat conversations, sessions, and interaction history.

    POST
    /conversations

    Start a new conversation session with a specific chatbot.

    Parameters

    NameTypeRequiredDescription
    chatbot_id
    string
    Required
    		ID of the chatbot to use for this conversation
    user_id
    string
    Optional
    		Optional user identifier for tracking
    metadata
    object
    Optional
    		Additional context or session data

    Request Example

    const conversation = await aie.conversations.create({
  chatbot_id: "chatbot_123",
  user_id: "user_789",
  metadata: {
    source: "website",
    page: "/pricing",
    referrer: "google"
  }
});

    Response Example

    {
  "success": true,
  "data": {
    "id": "conv_abc123",
    "chatbot_id": "chatbot_123",
    "status": "active",
    "created_at": "2024-01-15T12:00:00Z",
    "session_token": "sess_xyz789"
  }
}
    GET
    /conversations/{id}

    Retrieve the complete history and details of a specific conversation.

    Parameters

    NameTypeRequiredDescription
    id
    string
    Required
    		Unique identifier of the conversation
    include_messages
    boolean
    Optional
    		Whether to include message history (default: true)

    Request Example

    const conversation = await aie.conversations.get('conv_abc123', {
  include_messages: true
});

    Response Example

    {
  "success": true,
  "data": {
    "id": "conv_abc123",
    "chatbot_id": "chatbot_123",
    "status": "completed",
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Hello, I need help with pricing",
        "timestamp": "2024-01-15T12:00:00Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "I'd be happy to help you with pricing information!",
        "timestamp": "2024-01-15T12:00:05Z"
      }
    ]
  }
}

    Messages API

    Send and receive messages within conversation sessions.

    POST
    /conversations/{id}/messages

    Send a message to a chatbot and receive an AI-generated response.

    Parameters

    NameTypeRequiredDescription
    id
    string
    Required
    		Conversation ID to send the message to
    content
    string
    Required
    		The message content from the user
    stream
    boolean
    Optional
    		Enable streaming response (default: false)

    Request Example

    const response = await aie.conversations.sendMessage('conv_abc123', {
  content: "What are your pricing plans?",
  stream: false
});

    Response Example

    {
  "success": true,
  "data": {
    "message_id": "msg_003",
    "conversation_id": "conv_abc123",
    "response": {
      "id": "msg_004",
      "content": "We offer three pricing plans: Starter ($29/month), Professional ($99/month), and Enterprise (custom pricing). Each plan includes different features and usage limits. Would you like me to explain the differences?",
      "timestamp": "2024-01-15T12:01:00Z"
    }
  }
}

    Analytics API

    Access performance metrics, conversation analytics, and usage statistics.

    GET
    /analytics/overview

    Get high-level analytics overview including key performance metrics.

    Parameters

    NameTypeRequiredDescription
    start_date
    string
    Optional
    		Start date for analytics period (ISO 8601 format)
    end_date
    string
    Optional
    		End date for analytics period (ISO 8601 format)
    chatbot_id
    string
    Optional
    		Filter analytics for specific chatbot

    Request Example

    const analytics = await aie.analytics.getOverview({
  start_date: "2024-01-01T00:00:00Z",
  end_date: "2024-01-31T23:59:59Z",
  chatbot_id: "chatbot_123"
});

    Response Example

    {
  "success": true,
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "metrics": {
      "total_conversations": 1247,
      "total_messages": 8932,
      "unique_users": 892,
      "avg_conversation_length": 7.2,
      "resolution_rate": 0.87,
      "avg_response_time": 1.3
    }
  }
}

    Users API

    Manage user profiles, preferences, and conversation history.

    GET
    /users/{id}/conversations

    Get all conversations for a specific user across all chatbots.

    Parameters

    NameTypeRequiredDescription
    id
    string
    Required
    		User identifier
    limit
    integer
    Optional
    		Number of conversations to return (default: 20)
    status
    string
    Optional
    		Filter by conversation status

    Request Example

    const userConversations = await aie.users.getConversations('user_789', {
  limit: 10,
  status: 'completed'
});

    Response Example

    {
  "success": true,
  "data": [
    {
      "id": "conv_abc123",
      "chatbot_id": "chatbot_123",
      "status": "completed",
      "message_count": 8,
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:15:00Z"
    }
  ],
  "meta": {
    "total": 23,
    "limit": 10
  }
}