Getting Started with the ChatIQ API

This guide will walk you through integrating ChatIQ into your application, from getting your API key to making your first request.

Step 1: Get Your API Key

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

Important: Store your API key securely. Never commit it to version control or expose it in client-side code.

Step 2: Your First API Call

Let's start with a simple, non-streaming request:

cURL Example

curl -X POST https://chatiq.io/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -d '{
    "message": "Hello, what can you help me with?",
    "bot_slug": "your-bot-slug",
    "stream": false
  }'

JavaScript Example

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: "Hello, what can you help me with?",
    bot_slug: "your-bot-slug",
    stream: false,
  }),
});

const data = await response.json();
console.log(data.response); // Bot's response
console.log(data.conversationId); // Conversation ID for context

Python Example

import requests

url = "https://chatiq.io/api/chat"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk_live_your_api_key_here"
}
data = {
    "message": "Hello, what can you help me with?",
    "bot_slug": "your-bot-slug",
    "stream": False
}

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

Step 3: Add Streaming (Optional)

For real-time responses, enable 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: "Tell me about your services",
    bot_slug: "your-bot-slug",
    stream: true, // Enable streaming
  }),
});

// Handle Server-Sent Events
const reader = response.body.getReader();
const decoder = new TextDecoder();
let fullResponse = "";

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;

      try {
        const parsed = JSON.parse(data);
        if (parsed.choices?.[0]?.delta?.content) {
          fullResponse += parsed.choices[0].delta.content;
          // Update UI with new chunk
          updateUI(fullResponse);
        }
      } catch (e) {
        // Skip invalid JSON
      }
    }
  }
}

See the Streaming Guide for complete streaming examples.

Step 4: Maintain Conversation Context

To keep context across multiple messages, use the conversationId:

let conversationId = null;

async function sendMessage(message) {
  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,
      bot_slug: "your-bot-slug",
      conversation_id: conversationId, // Continue existing conversation
      stream: false,
    }),
  });

  const data = await response.json();

  // Save conversation ID for next message
  if (data.conversationId) {
    conversationId = data.conversationId;
  }

  return data.response;
}

// First message
const response1 = await sendMessage("What are your business hours?");
// Bot remembers this in the next message

// Second message (continues conversation)
const response2 = await sendMessage("What about weekends?");
// Bot knows we're still talking about business hours

Step 5: Handle Errors

Always check for errors:

const response = await fetch("https://chatiq.io/api/chat", {
  // ... request config
});

if (!response.ok) {
  const error = await response.json();
  console.error("API Error:", error.error.message);

  switch (error.error.code) {
    case "UNAUTHORIZED":
      // Invalid API key
      break;
    case "RATE_LIMIT":
      // Rate limit exceeded
      break;
    default:
    // Other error
  }

  return;
}

const data = await response.json();

See Error Handling for all error codes.

Step 6: Upload Documents (Optional)

If you want to add knowledge to your bot via API:

// Create a document
const docResponse = await fetch("https://chatiq.io/api/v1/documents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer sk_live_your_api_key_here",
  },
  body: JSON.stringify({
    title: "Product Information",
    content: "Your product documentation here...",
    tags: ["product", "docs"],
  }),
});

const { document } = await docResponse.json();

// Check embedding status
const statusResponse = await fetch(
  `https://chatiq.io/api/v1/documents/${document.id}/embeddings/status`,
  {
    headers: {
      Authorization: "Bearer sk_live_your_api_key_here",
    },
  }
);

const status = await statusResponse.json();
console.log(`Embedding progress: ${status.percentage}%`);

See Documents API for full documentation.

Integration Patterns

Pattern 1: Server-Side Proxy (Recommended)

Best for: Web applications, hiding API keys

Create a Next.js API route:

// app/api/chatbot/route.ts
export async function POST(request: Request) {
  const { message, conversation_id } = await request.json();

  const response = await fetch("https://chatiq.io/api/chat", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.CHATIQ_API_KEY}`,
    },
    body: JSON.stringify({
      message,
      bot_slug: process.env.CHATIQ_BOT_SLUG,
      stream: true,
      conversation_id,
    }),
  });

  return new Response(response.body, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
    },
  });
}

Then call your own API from the client:

const response = await fetch("/api/chatbot", {
  method: "POST",
  body: JSON.stringify({ message: "Hello" }),
});

Benefits:

• API key stays on server
• No CORS issues
• Can add custom logic

Pattern 2: Server-Side Only

Best for: Backend services, scripts, automation

// Node.js script
const response = await fetch("https://chatiq.io/api/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.CHATIQ_API_KEY}`,
  },
  body: JSON.stringify({
    message: "Hello",
    bot_slug: "my-bot",
    stream: false, // JSON mode for simplicity
  }),
});

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

Next Steps

• Read the Complete API Reference
• Learn about Streaming
• Explore Document Management
• Check Rate Limits

Need Help?

• Documentation: Full API Reference
• Support: support@chatiq.io
• Dashboard: chatiq.io/dashboard