API Reference Overview

Squad exposes a REST API with automatic OpenAPI documentation. All responses are JSON. Real-time updates are delivered via Server-Sent Events (SSE).

Base URL

Your API base URL is provided during onboarding (e.g., https://yourorg.squadai.uk).

Interactive API documentation is available at:

• Swagger UI: {base_url}/docs
• ReDoc: {base_url}/redoc
• OpenAPI JSON: {base_url}/openapi.json

Authentication

All endpoints require JWT authentication unless explicitly whitelisted. Squad integrates with your identity provider via OAuth2/OIDC.

Public Routes (No Auth Required)

Endpoint	Purpose
GET /health	Liveness check
GET /health/ready	Readiness check
GET /auth/config	OAuth bootstrap configuration
GET /docs	Swagger UI
GET /redoc	ReDoc documentation
GET /openapi.json	OpenAPI specification

Authenticated Requests

Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Tokens are obtained through your identity provider’s OAuth2 flow. The Squad frontend handles this automatically.

Quick Start

Create a session, send a question, and retrieve the event trace — three requests to go from zero to a complete answer.

1. Create a session

curl -X POST https://yourorg.squadai.uk/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

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

2. Send a message

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?"}'

The response is an SSE stream — events arrive as newline-delimited JSON until the final answer event.

3. Retrieve the event trace

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

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "events": [
    {"timestamp": "2026-03-17T10:30:00Z", "event": "step_started", "data": {"node": "classify"}},
    {"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..."}}
  ]
}

See the Chat API for the full endpoint reference.

Endpoint Groups

Health

Method	Endpoint	Description
GET	/health	Liveness probe
GET	/health/ready	Readiness probe with component checks

Chat

Method	Endpoint	Description
POST	/api/v1/chat	Create a new chat session (rate limited: 60/min)
POST	/api/v1/chat/{session_id}/message	Send a message (rate limited: 30/min)
GET	/api/v1/chat/{session_id}/stream	SSE event stream for real-time progress
GET	/api/v1/chat/{session_id}/events	Historical event trace
GET	/api/v1/chat/{session_id}/status	Session status
POST	/api/v1/chat/{session_id}/disambiguate	Send disambiguation response
POST	/api/v1/chat/{session_id}/review	Submit review response
GET	/api/v1/chat/{session_id}/history	Get session message history
GET	/api/v1/chat/history	List all chat sessions

Query Curation

Method	Endpoint	Description
GET	/api/v1/aim/queries/stats	Query count breakdown by status
GET	/api/v1/aim/queries/pending	List pending approval queries
GET	/api/v1/aim/queries/approved	List approved templates
POST	/api/v1/aim/queries/test-cypher	Execute read-only query for testing
POST	/api/v1/aim/queries/{id}/approve	Approve a pending query
POST	/api/v1/aim/queries/{id}/reject	Reject a pending query
POST	/api/v1/aim/queries/{id}/amend	Amend and approve a query
DELETE	/api/v1/aim/queries/{id}	Delete a query

Review

Method	Endpoint	Description
GET	/api/v1/review/{session_id}/pending	Get pending reviews for a session
POST	/api/v1/review/{session_id}/approve	Approve a review item
POST	/api/v1/review/{session_id}/reject	Reject a review item
GET	/api/v1/review/history	Full review history
GET	/api/v1/review/{session_id}/memories	Session memories

Workflows

Method	Endpoint	Description
GET	/api/v1/aim/workflows	List available workflows
POST	/api/v1/aim/workflows/execute	Execute a workflow
GET	/api/v1/aim/workflows/{id}/steps	Get workflow steps and tools
GET	/api/v1/aim/workflows/{id}/queries	Related queries for a workflow
DELETE	/api/v1/aim/workflows/{id}	Revoke a workflow

Documents

Method	Endpoint	Description
POST	/api/v1/documents/upload	Upload files for ingestion
GET	/api/v1/documents/	List all documents
GET	/api/v1/documents/ingestion-status	Ingestion status
GET	/api/v1/documents/graph	Knowledge graph entries
GET	/api/v1/documents/{doc_id}/preview	Preview a document
GET	/api/v1/documents/{doc_id}/download	Download original file
PATCH	/api/v1/documents/{doc_id}/status	Update document status
POST	/api/v1/documents/{doc_id}/approve	Approve for ingestion
POST	/api/v1/documents/{doc_id}/ingest	Trigger ingestion
DELETE	/api/v1/documents/{doc_id}	Delete a document
POST	/api/v1/documents/{doc_id}/link	Create a relationship link
DELETE	/api/v1/documents/{doc_id}/link/{rel_id}	Remove a relationship link
POST	/api/v1/documents/queue/enqueue	Add documents to the ingestion queue
POST	/api/v1/documents/queue/pause	Pause the ingestion queue
POST	/api/v1/documents/queue/resume	Resume the ingestion queue
GET	/api/v1/documents/queue/status	Queue status and progress
GET	/api/v1/documents/queue/stream	SSE stream for queue updates
DELETE	/api/v1/documents/queue/{doc_id}	Remove from the queue

Tools

Method	Endpoint	Description
GET	/api/v1/aim/tools	List registered tools
GET	/api/v1/aim/tools/{tool_name}/workflows	Workflows using a tool

Runs & Files

Method	Endpoint	Description
GET	/api/v1/runs/{run_id}/files	List files for a run
GET	/api/v1/runs/{run_id}/preview/{path}	Preview a run artifact
GET	/api/v1/runs/{run_id}/download/{path}	Download a run artifact

Error Codes

Code	Meaning
400	Invalid input: check request body
401	Unauthorized: missing or invalid JWT
403	Forbidden: insufficient role or permissions
404	Resource not found
429	Rate limited (session creation: 60/min, messages: 30/min)
500	Server error
503	Service unavailable

Error responses return a JSON body with a detail field:

{"detail": "Rate limit exceeded. Try again in 42 seconds."}

SSE Event Format

The chat stream endpoint delivers events as newline-delimited JSON:

{"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}}