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.
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 |
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 |
| 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 |
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}}
Next Steps
