Core Modules

Chat API

The Chat API sends messages to a configured AI assistant and returns responses — either as a complete JSON object or as a real-time Server-Sent Events (SSE) stream. RAG retrieval from the knowledge base happens automatically.

Authentication paths

The Chat API exposes two base paths depending on your authentication method:

/chat-apiKeyAuth/...

Use the x-api-key header. Ideal for server-side integrations.

/chat-tokenAuth/...

Use Authorization: Bearer with a Firebase ID Token. Ideal for frontend apps.

Request body

Request Body

JSON

{
  "message": "What are your business hours?",
  "assistantId": "asst_abc123",
  "threadId": "thread_xyz789",     // optional — omit to create new thread
  "metadata": {                     // optional custom metadata
    "userId": "user_123",
    "channel": "web"
  }
}

Complete response

Response (non-streaming)

JSON

{
  "reply": "Our business hours are Monday to Friday, 9am–6pm EST.",
  "threadId": "thread_xyz789",
  "messageId": "msg_def456",
  "usage": {
    "prompt_tokens": 245,
    "completion_tokens": 18,
    "total_tokens": 263
  },
  "model": "gpt-4o",
  "finishReason": "stop"
}

Streaming (SSE)

Use the /stream endpoint to receive tokens as they are generated. The connection uses Server-Sent Events:

stream-chat.js

JavaScript

const response = await fetch(
  'https://api.cognitiondesk.com/chat-apiKeyAuth/stream',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.COGNITIONDESK_API_KEY,
    },
    body: JSON.stringify({
      message: 'Summarize our return policy.',
      assistantId: 'asst_abc123',
    }),
  }
);

// Parse Server-Sent Events
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

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

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop(); // keep incomplete line

  for (const line of lines) {
    if (!line.startsWith('data: ')) continue;
    const data = JSON.parse(line.slice(6));

    if (data.type === 'delta') {
      process.stdout.write(data.content);
    } else if (data.type === 'done') {
      console.log('\nUsage:', data.usage);
    } else if (data.type === 'tool_call') {
      // Handle tool execution request
      console.log('Tool requested:', data.tool);
    }
  }
}

SSE event types

SSE Event Format

Shell

// delta — content chunk
data: {"type":"delta","content":"Our return "}

// delta — next chunk
data: {"type":"delta","content":"policy allows..."}

// tool_call — assistant requests a tool
data: {"type":"tool_call","tool":"searchInventory","args":{"query":"returns"},"callId":"tc_123"}

// tool_result — send the result back via POST /tools/result
// done — stream complete
data: {"type":"done","threadId":"thread_xyz","usage":{"prompt_tokens":180,"completion_tokens":52}}

Tool calls in streams

When the assistant triggers a tool (e.g. a REST API connection), a tool_call event is emitted. Your client must execute the tool and submit the result via POST /tools/result before the stream continues.

Endpoints

Method	Endpoint	Auth	Description
POST	`/chat-apiKeyAuth/chat`	API Key	Complete chat response (JSON)
POST	`/chat-apiKeyAuth/stream`	API Key	Streaming SSE chat response
POST	`/chat-tokenAuth/chat`	Firebase Token	Complete chat response with Firebase Token
POST	`/chat-tokenAuth/stream`	Firebase Token	Streaming chat with Firebase Token