Skip to main content

Chat REST API

The Chat REST API provides SSE (Server-Sent Events) streaming endpoints for real-time AI chat interactions.

Base URL​

/api/eai/v3/chat

Send Message (Streaming)​

Send a message and receive streaming AI response via SSE.

POST /api/eai/v3/chat
Content-Type: application/json
Accept: text/event-stream

Request Body​

{
  "message": "What are the active projects?",
  "conversationId": "conv_123",
  "options": {
    "temperature": 0.7,
    "maxTokens": 2048,
    "systemPrompt": "You are a helpful assistant.",
    "context": {
      "resources": [
        { "type": "project", "id": "proj_456" }
      ],
      "documents": ["doc_789"]
    }
  }
}

Request Parameters​

FieldTypeRequiredDescription
messagestringYesUser message
conversationIdstringNoConversation ID for context
options.temperaturenumberNo0-1, default 0.7
options.maxTokensnumberNoMax response length
options.systemPromptstringNoSystem behavior prompt
options.contextobjectNoAdditional context

Example Request (JavaScript)​

const eventSource = new EventSource('/api/eai/v3/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Summarize the project status',
    conversationId: 'conv_123',
    options: {
      temperature: 0.5,
      context: {
        resources: [{ type: 'project', id: 'proj_456' }]
      }
    }
  })
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
};

eventSource.onerror = (error) => {
  console.error('Stream error:', error);
  eventSource.close();
};

Example Request (fetch API)​

const response = await fetch('/api/eai/v3/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({
    message: 'What is the project budget?'
  })
});

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\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log('Event:', data);
    }
  }
}

SSE Event Types​

Message Event​

Incremental message content.

data: {"type":"message","data":{"content":"The project","delta":"The project"}}

data: {"type":"message","data":{"content":"The project is","delta":" is"}}

Citation Event​

Source citation for response.

data: {"type":"citation","data":{"source":"doc_789","sourceType":"document","content":"Project budget is $500k","confidence":0.95}}

Status Event​

Processing status update.

data: {"type":"status","data":{"status":"searching","message":"Searching documents..."}}

Error Event​

Error during processing.

data: {"type":"error","data":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests"}}

Done Event​

Stream complete.

data: {"type":"done","data":{"conversationId":"conv_123","messageId":"msg_456","usage":{"totalTokens":342}}}

curl Example​

curl -X POST "/api/eai/v3/chat" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "What are the active projects?",
    "options": {
      "temperature": 0.5
    }
  }' \
  --no-buffer

Get Conversation History​

Retrieve message history for a conversation.

GET /api/eai/v3/chat/conversations/:conversationId

Example Request​

const response = await fetch('/api/eai/v3/chat/conversations/conv_123');
const { messages } = await response.json();

Response​

{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "content": "What are the active projects?",
      "timestamp": "2026-03-11T14:00:00Z"
    },
    {
      "id": "msg_2",
      "role": "assistant",
      "content": "There are 5 active projects...",
      "citations": [
        {
          "source": "doc_789",
          "confidence": 0.95
        }
      ],
      "timestamp": "2026-03-11T14:00:05Z"
    }
  ]
}

List Conversations​

Get all conversations for current user.

GET /api/eai/v3/chat/conversations

Response​

{
  "data": [
    {
      "id": "conv_123",
      "title": "Project Discussion",
      "messageCount": 12,
      "createdAt": "2026-03-10T10:00:00Z",
      "updatedAt": "2026-03-11T14:00:00Z"
    }
  ]
}

Delete Conversation​

DELETE /api/eai/v3/chat/conversations/:conversationId

Error Responses​

400 Bad Request​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Message is required"
  }
}

429 Rate Limit​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many chat requests",
    "retryAfter": 30
  }
}

Next Steps​