Examples

Copy-paste, working requests for the v2 assistant. BASE = https://<workspace>.corteksa.com/api/v1, WS_HOST = wss://<workspace>.corteksa.com, JWT = your admin login token. v2 is gated by AI_V2_ENABLED.

Create a conversation (REST)

curl -X POST "$BASE/ai-v2/conversations" \
  -H "Authorization: Bearer $JWT"
# → { "message": "...", "data": { "slug": "conv-8f3c…", ... } }

Send a message and get the answer (REST, blocking)

curl -X POST "$BASE/ai-v2/conversations/$SLUG/messages" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "message": "how many open deals do I have?" }'

const res = await fetch(`${BASE}/ai-v2/conversations/${slug}/messages`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'how many open deals do I have?', object_slug: 'deals' }),
});
const { data } = await res.json();
// data carries the reply, tool activity, usage — and a `confirmation` if it wants to write

Open the chat WebSocket, send a prompt, stream the answer

import { io } from 'socket.io-client';

const socket = io(`${WS_HOST}/ai-v2/chat`, {
  auth: { token: jwt },
  transports: ['websocket'],
});

let convId = existingConversationId; // or undefined to start fresh

socket.on('assistant:ready', () => {
  socket.emit('assistant:send', { conversationId: convId, message: 'show my open deals' });
});

socket.on('assistant:thinking', (e) => { convId = e.conversationId; showSpinner(); });
socket.on('assistant:agent', (e) => setActiveAgent(e));           // which specialist is handling
socket.on('assistant:token', (e) => appendDelta(e.delta));        // stream tokens
socket.on('assistant:tool_start', (e) => showToolChip(e));
socket.on('assistant:tool_result', (e) => resolveToolChip(e));
socket.on('assistant:complete', (e) => finalize(e));
socket.on('assistant:handoff', (e) => openHandoffTarget(e));      // e.g. open the builder
socket.on('assistant:error', (e) => console.warn(e.code, e.message));

Handle a write with the confirmation gate

A write batch pauses and emits assistant:confirmation_required. Show a card, then echo back the exact call ids to approve — or assistant:reject to decline.

socket.on('assistant:confirmation_required', (c) => {
  const ok = window.confirm('Apply these changes?');
  if (ok) {
    socket.emit('assistant:confirm', { conversationId: c.conversationId, approvedCallIds: c.callIds });
  } else {
    socket.emit('assistant:reject', { conversationId: c.conversationId });
  }
});

The same gate over REST: the send response returns a confirmation; approve it with POST /ai-v2/conversations/{slug}/confirm { "approved": true, "approved_call_ids": [...] }.

Stop an in-flight turn

socket.emit('assistant:cancel_generation'); // aborts the current stream

The protocol in full → Frontend Integration
Every endpoint → REST API