Skip to content
Squad AI

Chat API

The Chat API provides direct access to Squad’s intelligence engine through REST endpoints with real-time SSE streaming.

Endpoints

MethodEndpointDescription
POST/api/v1/chatCreate a new chat session (rate limited: 60/min)
POST/api/v1/chat/{session_id}/messageSend a message (rate limited: 30/min)
GET/api/v1/chat/{session_id}/streamSSE event stream for real-time progress
GET/api/v1/chat/{session_id}/eventsHistorical event trace for a session
GET/api/v1/chat/{session_id}/statusSession status
POST/api/v1/chat/{session_id}/disambiguateSend disambiguation response
POST/api/v1/chat/{session_id}/reviewSubmit review response
GET/api/v1/chat/{session_id}/historyGet session message history
GET/api/v1/chat/historyList all chat sessions

Create Session

Terminal window
curl -X POST https://yourorg.squadai.uk/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "nuclear-safety",
    "metadata": {"source": "api-integration"}
  }'

Both project_id and metadata are optional.

Response 200

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "created",
  "message": "Session created successfully"
}

Send Message

Sends a user message and returns an SSE stream of AIM processing events.

Terminal window
curl -X POST https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the active fault schedules for reactor unit 3?",
    "context": {"priority": "high"}
  }'

context is optional and passed through to the AIM graph as additional metadata.

Response 200 — text/event-stream

{"timestamp": "2026-03-17T10:30:00Z", "event": "step_started", "data": {"node": "classify", "run_id": "abc-123"}}
{"timestamp": "2026-03-17T10:30:01Z", "event": "step_completed", "data": {"node": "classify", "query_type": "FACTUAL"}}
{"timestamp": "2026-03-17T10:30:02Z", "event": "tool_executed", "data": {"tool_name": "retriever", "success": true}}
{"timestamp": "2026-03-17T10:30:04Z", "event": "answer", "data": {"content": "There are 3 active fault schedules for reactor unit 3..."}}

Live Stream

Connect to the SSE stream for real-time progress while AIM processes a query.

Terminal window
curl -N https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Because the browser EventSource API cannot set custom headers, the stream endpoint also accepts a query-string token:

GET /api/v1/chat/{session_id}/stream?token=<your-jwt-token>

The event format is identical to the stream returned by the message endpoint above.

Historical Events

Returns the full normalised event trace for a session after processing completes. Use this to replay or audit a previous interaction.

Terminal window
curl https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/events \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "events": [
    {"timestamp": "2026-03-17T10:30:00Z", "event": "step_started", "data": {"node": "classify", "run_id": "abc-123"}},
    {"timestamp": "2026-03-17T10:30:01Z", "event": "step_completed", "data": {"node": "classify", "query_type": "FACTUAL"}},
    {"timestamp": "2026-03-17T10:30:02Z", "event": "tool_executed", "data": {"tool_name": "retriever", "success": true}},
    {"timestamp": "2026-03-17T10:30:04Z", "event": "answer", "data": {"content": "There are 3 active fault schedules..."}}
  ]
}

Session Status

Terminal window
curl https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/status \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "current_module": "executor",
  "pending_review": false,
  "created_at": "2026-03-17T10:29:58Z",
  "updated_at": "2026-03-17T10:30:04Z"
}

Disambiguate

When AIM detects ambiguity in a query, the stream pauses and requests clarification. Respond with the selected intent to resume processing.

Terminal window
curl -X POST https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/disambiguate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selected_intent": "List active fault schedules only"
  }'

Response 200 — text/event-stream

The SSE stream resumes with the clarified intent.

Submit Review

When AIM flags an output for human-in-the-loop review, submit a decision through the chat session.

Terminal window
curl -X POST https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/review \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "amendments": null
  }'

decision accepts "approve", "reject", or "amend". When amending, include the corrected text in amendments.

Response 200 — text/event-stream

The SSE stream resumes with the review outcome applied.

Session Message History

Terminal window
curl "https://yourorg.squadai.uk/api/v1/chat/a1b2c3d4-5678-90ab-cdef-1234567890ab/history?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "history": [
    {"role": "user", "content": "What are the active fault schedules for reactor unit 3?", "timestamp": "2026-03-17T10:30:00Z"},
    {"role": "assistant", "content": "There are 3 active fault schedules for reactor unit 3...", "timestamp": "2026-03-17T10:30:04Z"}
  ],
  "count": 2
}

List All Sessions

Terminal window
curl "https://yourorg.squadai.uk/api/v1/chat/history?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "sessions": [
    {"session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "created_at": "2026-03-17T10:29:58Z", "message_count": 2},
    {"session_id": "b2c3d4e5-6789-01bc-def0-234567890abc", "created_at": "2026-03-16T14:12:00Z", "message_count": 5}
  ],
  "count": 2
}