API Documentation

Complete reference for the CircuCity AI REST API. Integrate chatbot, products, conversations, and analytics into your platform.

Endpoints

Chat API

Send messages to your AI chatbot and receive responses. Supports both standard and streaming (SSE) responses.

Authentication

Authorization: Bearer YOUR_API_KEY

All API requests require authentication. Get your API key from Settings → API Keys in the dashboard. Keys are scoped per workspace.

POST/api/chat

Send a message to the AI and get a response.

Parameters

NameTypeRequiredDescription
messagestringYesThe user's message text
session_idstringYesUnique session identifier for conversation continuity
contextobjectNoAdditional context (page_url, user_name, preferences)

Request Example

curl -X POST https://chatbot.circucity.com/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Do you have eco-friendly options?",
    "session_id": "visitor-abc-123",
    "context": {
      "page_url": "https://mystore.com/products",
      "user_name": "Alice"
    }
  }'

Response

{
  "success": true,
  "reply": "Absolutely! Here are our eco-friendly picks...",
  "session_id": "visitor-abc-123",
  "confidence": 0.95,
  "sources": ["https://mystore.com/eco-collection"],
  "product_references": ["prod-001", "prod-002"]
}

Error Codes

200 OK400 Bad Request401 Unauthorized404 Not Found429 Rate Limited500 Server Error
POST/api/chat/stream

Stream a chat response using Server-Sent Events (SSE) for real-time typing effect.

Parameters

NameTypeRequiredDescription
messagestringYesThe user's message text
session_idstringYesUnique session identifier
streambooleanNoEnable SSE streaming (default: true)

Request Example

POST /api/chat/stream
Content-Type: application/json

{
  "message": "Tell me about your shipping policy",
  "session_id": "visitor-abc-123"
}

Response

// Server-Sent Events stream:
data: {"type":"token","content":"Our"}

data: {"type":"token","content":" shipping"}

data: {"type":"token","content":" policy"}

data: {"type":"token","content":"..."}

data: {"type":"done","session_id":"visitor-abc-123"}

Error Codes

200 OK400 Bad Request401 Unauthorized404 Not Found429 Rate Limited500 Server Error
POST/api/chat/reset

Reset a conversation session, clearing all message history.

Parameters

NameTypeRequiredDescription
session_idstringYesSession to reset

Request Example

curl -X POST https://chatbot.circucity.com/api/chat/reset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "visitor-abc-123"}'

Response

{
  "success": true,
  "message": "Session reset successfully",
  "session_id": "visitor-abc-123"
}

Error Codes

200 OK400 Bad Request401 Unauthorized404 Not Found429 Rate Limited500 Server Error

Rate Limits

Starter

100 requests/min

Burst: 200 requests/min

Pro

500 requests/min

Burst: 1000 requests/min

Enterprise

2000 requests/min

Burst: 5000 requests/min