API Reference

The ChatIQ API allows you to integrate AI chatbots into your applications, websites, and services. This guide covers authentication, endpoints, and usage examples.

Base URL

All API requests should be made to:

https://www.chatiq.io/api

Note: chatiq.io redirects to www.chatiq.io, so always use the www subdomain.

Authentication

API requests are authenticated using API keys. You can generate API keys from your dashboard at /dashboard/api-keys.

Using API Keys

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer sk_live_your_api_key_here

Generating API Keys

1. Navigate to API Keys in your dashboard
2. Click Create New Key
3. Select the bot this key should have access to
4. Give it a descriptive label (e.g., "Production" or "Development")
5. Copy the key immediately — you won't be able to see it again

Important: Keep your API keys secure. Never commit them to version control or expose them in client-side code.

Chat Endpoint

POST /api/chat

Send a message to a chatbot and receive a response.

Request Headers

Content-Type: application/json
Authorization: Bearer sk_live_your_api_key_here

Request Body

{
  "message": "What are your business hours?",
  "bot_slug": "support-bot",
  "stream": false,
  "history": [],
  "conversation_id": null,
  "private_mode": false
}

Response Format

JSON Mode (stream: false):

{
  "response": "Our business hours are Monday through Friday, 9 AM to 5 PM EST.",
  "conversationId": "uuid-here",
  "attachments": [
    {
      "type": "image",
      "url": "https://.../delivery.jpg",
      "assetId": "uuid",
      "alt": null,
      "caption": null
    }
  ],
  "suggestions": [
    { "label": "See Pad Thai photo", "payload": "__item__:docId:itemId" }
  ]
}

Image Attachments

• attachments is optional and may contain 1–3 images.
• alt and caption can be null or empty; do not rely on them for labels.
• If attachments is present, render images even when response is empty.

Suggestions

Some pre-configured responses can return suggestions (quick replies). Render the label and send the payload as the next user message.

Streaming Mode (stream: true or omitted):

The API returns a Server-Sent Events (SSE) stream:

data: {"choices":[{"delta":{"content":"Our"}}]}

data: {"choices":[{"delta":{"content":" business"}}]}

data: {"choices":[{"delta":{"content":" hours"}}]}

...

data: {"conversationId":"uuid-here"}

data: [DONE]

Example: cURL (JSON Mode)

curl -X POST https://chatiq.io/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -d '{
    "message": "What are your business hours?",
    "bot_slug": "support-bot",
    "stream": false
  }'

Example: JavaScript (Fetch API)

const response = await fetch("https://chatiq.io/api/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer sk_live_your_api_key_here",
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    bot_slug: "support-bot",
    stream: false,
  }),
});

const data = await response.json();
console.log(data.response);

Example: JavaScript (Streaming)

const response = await fetch("https://chatiq.io/api/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer sk_live_your_api_key_here",
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    bot_slug: "support-bot",
    stream: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split("\n");

  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = line.slice(6);
      if (data === "[DONE]") break;

      const parsed = JSON.parse(data);
      if (parsed.choices?.[0]?.delta?.content) {
        process.stdout.write(parsed.choices[0].delta.content);
      }
    }
  }
}

Example: Python

import requests

url = "https://chatiq.io/api/chat"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk_live_your_api_key_here"
}
data = {
    "message": "What are your business hours?",
    "bot_slug": "support-bot",
    "stream": False
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result["response"])

Conversation Management

Private Mode

For privacy-sensitive conversations or GDPR compliance, you can enable private mode by setting private_mode: true in your request. When enabled:

• The conversation will work normally (user receives responses)
• No conversation data is saved to the database
• The conversation is completely ephemeral (exists only in the current session)
• No conversation history will be available after the session ends

Example:

{
  "message": "What are your business hours?",
  "bot_slug": "support-bot",
  "private_mode": true
}

Note: When private_mode is enabled, the conversationId in the response will be null or omitted, as no conversation record is created.

Continuing Conversations

To maintain context across multiple messages, include the conversation_id and history in your requests:

{
  "message": "What about weekends?",
  "bot_slug": "support-bot",
  "conversation_id": "uuid-from-previous-response",
  "history": [
    {
      "role": "user",
      "content": "What are your business hours?"
    },
    {
      "role": "assistant",
      "content": "Our business hours are Monday through Friday, 9 AM to 5 PM EST."
    }
  ],
  "stream": false
}

The API will return the same conversationId for all messages in the same conversation thread.

Error Handling

The API uses standard HTTP status codes:

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key",
    "details": {}
  }
}

Rate Limits

Rate limits are based on your subscription plan:

Note: The Evaluation plan also has an overall 100 AI-call cap during the 14-day evaluation window.

Rate limits are tracked per API key and reset daily. When you exceed your limit, you'll receive a 429 Too Many Requests response.

CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser-based integrations. In development, all origins are allowed. In production, CORS is configured to allow requests from your configured domains.

To configure additional allowed origins, set the CORS_ALLOWED_ORIGINS environment variable (comma-separated list of origins).

Best Practices

1. Store API keys securely: Use environment variables or secure key management services
2. Handle errors gracefully: Always check response status codes and handle errors appropriately
3. Respect rate limits: Implement exponential backoff when hitting rate limits
4. Use conversation IDs: Maintain conversation context for better user experience
5. Monitor usage: Track your API usage to stay within plan limits

Additional Resources

• Getting Started Guide - Step-by-step onboarding
• Streaming Guide - Complete SSE streaming documentation
• Documents API - Document management and embedding status
• OpenAPI Specification - Machine-readable API spec

Support

Need help? Contact us at support@chatiq.io or visit your dashboard for more resources.