Review API

The Review API provides endpoints for human-in-the-loop review of Squad’s outputs, accessible through both the review panel and programmatic API calls.

Endpoints

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 with filters
GET	/api/v1/review/{session_id}/memories	Session memories and context

---

Examples

Pending Reviews

Check whether a session has outputs awaiting human review.

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

Response 200

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "has_pending": true,
  "review": {
    "module_name": "executor",
    "review_type": "workflow_output",
    "content": "Generated Cypher query: MATCH (fs:FaultSchedule)...",
    "requested_at": "2026-03-17T10:31:00Z"
  }
}

When no review is pending, has_pending is false and review is null.

Approve

Approve the pending review item. Optionally include amendments to adjust the output before acceptance.

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

Response 200 — text/event-stream

The SSE stream resumes with the approved output applied. Approval may also trigger memory crystallisation.

{"timestamp": "2026-03-17T10:32:00Z", "event": "review_completed", "data": {"decision": "approve", "session_id": "a1b2c3d4-..."}}
{"timestamp": "2026-03-17T10:32:01Z", "event": "step_started", "data": {"node": "crystallise", "run_id": "abc-124"}}

Reject

Reject the pending review with an optional reason.

curl -X POST https://yourorg.squadai.uk/api/v1/review/a1b2c3d4-5678-90ab-cdef-1234567890ab/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Cypher query returns unfiltered results — too broad"}'

Response 200 — text/event-stream

{"timestamp": "2026-03-17T10:33:00Z", "event": "review_completed", "data": {"decision": "reject", "reason": "Cypher query returns unfiltered results — too broad"}}

Review History

Query the full audit trail of review decisions with optional filters.

curl "https://yourorg.squadai.uk/api/v1/review/history?module_name=executor&decision=approve&limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"

All query parameters are optional. limit accepts 1–500 (default 50).

Response 200

{
  "items": [
    {
      "id": 1,
      "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "module_name": "executor",
      "review_type": "workflow_output",
      "decision": "approve",
      "amendments": null,
      "user_id": "user-001",
      "memory_ids": ["mem-abc", "mem-def"],
      "requested_at": "2026-03-17T10:31:00Z",
      "decided_at": "2026-03-17T10:32:00Z"
    }
  ],
  "total": 128,
  "limit": 50,
  "offset": 0
}

Session Memories

Retrieve memories captured during a session’s review interactions.

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

Response 200

{
  "session_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "memories": [
    {"id": "mem-abc", "content": "User prefers fault schedules filtered by active status", "created_at": "2026-03-17T10:32:01Z"},
    {"id": "mem-def", "content": "Reactor unit 3 is the primary focus area", "created_at": "2026-03-17T10:32:01Z"}
  ],
  "count": 2
}