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

ChatIQ supports both authenticated and public chat access:

• Authenticated access: supply an API key to use the owning team's plan and quota.
• Public access: omit the API key and the request is handled under stricter anonymous limits.

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

Authorization is optional for /api/chat.

• Include it for authenticated server-to-server usage.
• Omit it for public/anonymous usage with stricter limits.

Request Body

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

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" }
  ],
  "session_updates": {
    "private_mode": false,
    "retention_override": "full"
  }
}

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]

Streaming responses may also include additional SSE events such as:

• attachments
• suggestions
• response_component
• session_updates
• response_source
• structured_step
• booking handoff fields such as booking_handoff_session_id
• payment_handoff
• request_debug
• openai_messages

Example: cURL (JSON Mode)

curl -X POST https://www.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://www.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://www.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://www.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
• Minimal, non-content analytics may still be recorded

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.

Session Opt-In for Saving

If saving is required for a flow (e.g., booking), the server can return:

{
  "session_updates": {
    "private_mode": false,
    "retention_override": "full"
  }
}

Clients should apply these updates for the current session.

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 depend on how you call the chat endpoint:

• API key provided: usage is charged against the owning team's plan.
• Internal app requests: usage follows the bot owner's plan.
• No API key: request is treated as anonymous/public and handled under stricter free-tier limits.

Current plan quotas are managed in the application runtime and may change over time. For product-level plan details, refer to the pricing documentation rather than hard-coding numeric limits from this page.

When you exceed a request rate limit, you'll receive 429 RATE_LIMIT_EXCEEDED. If your team exceeds a broader plan quota, you may receive 402 QUOTA_EXCEEDED.

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.