REST API
AI — REST API
The AI assistant is the v2 multi-agent engine (LangGraph). Its REST surface lives
under /api/v1/ai-v2 and authenticates with the admin JWT
(Authorization: Bearer <jwt>). Routes run AiV2EnabledGuard then AdminAuthGuard
— when AI_V2_ENABLED is off the whole surface returns 404. Conversations are
addressed by slug.
Every endpoint below is a direct link into the interactive API reference — click it to see the full schema and try the call live.
Status
- GET
/ai-v2/status— whether v2 is enabled and which providers are healthy
Conversations
- POST
/ai-v2/conversations— create a conversation → returns itsslug - GET
/ai-v2/conversations— list the caller's conversations - GET
/ai-v2/conversations/{slug}— one conversation - GET
/ai-v2/conversations/{slug}/messages— its message turns - DELETE
/ai-v2/conversations/{slug}— delete a conversation
Run a turn
- POST
/ai-v2/conversations/{slug}/messages— send a message and run the turn (blocking) - POST
/ai-v2/conversations/{slug}/confirm— approve or decline the turn's pending writes
Send body — SendAiV2MessageDto
| Field | When | Notes |
|---|---|---|
message | required | the user's message (bounded by AI_V2_LIMITS.MESSAGE_MAX_CHARS) |
agent | optional | pin a specific agent and skip the supervisor (≤ 64 chars; ignored if unknown) |
object_slug | optional | focus context — the object the user is viewing; a soft default for unqualified requests |
The response carries the assistant's reply, its tool activity, and token usage. If the
turn wants to write, it returns a confirmation with the pending calls instead of
applying them — click the endpoint above to see the exact response schema.
Confirm body — ConfirmAiV2WritesDto
| Field | When | Notes |
|---|---|---|
approved | required | true to run the pending writes, false to decline |
approved_call_ids | optional | echo the exact call ids the confirmation showed — the server runs only those (each is re-checked) |
Why a confirmation step? No agent turn writes to your CRM without an explicit approve. See the write-confirmation law.
Streaming (WebSocket)
REST runs a turn to completion. For live tokens, tool progress, agent hand-offs,
and the interactive confirmation gate, use the WebSocket instead — namespace
/ai-v2/chat. Full event tables and payloads:
Frontend Integration.
Next
- Build the UI → Frontend Integration
- Copy-paste requests → Examples