Skip to content
Nucleus

Squads API

Squads

Section titled “Squads”

List squads

Section titled “List squads”
GET /api/squads

Returns squads scoped by access level. Executive/Head see all; Managers see squads they manage; Employees see their own squad.

Response fields: id, name, description, dm_user_id, lead_user_id, colour, kickoff_day, kickoff_time, focus_note, member_count, open_action_count, last_session_date, Slack channel fields.

Get squad detail

Section titled “Get squad detail”
GET /api/squads/:id

Returns full squad detail including members, recent sessions, and DM/lead names.

Update squad

Section titled “Update squad”
PUT /api/squads/:id

Permission: Executive for existing fields, Manager+ for new fields.

Body: description, dm_user_id, lead_user_id, colour, kickoff_day, kickoff_time, focus_note, plus existing Slack channel fields.

Get squad performance

Section titled “Get squad performance”
GET /api/squads/:id/performance

Combined endpoint returning utilisation grid, time entry flags, AI adoption breakdown, and scorecard summary for the squad.

Sessions

Section titled “Sessions”

List sessions

Section titled “List sessions”
GET /api/squads/:id/sessions

Returns sessions newest first. Employee/Lead access returns limited fields (no 4P notes).

Query params: limit, page

Create session

Section titled “Create session”
POST /api/squads/:id/sessions

Creates a new session for the given week. If a session already exists for this week (UNIQUE constraint), returns the existing session.

Body: session_date (ISO date, Monday), week_ending (ISO date, Friday), facilitator_id (optional)

Captures snapshots at creation: utilisation, AI adoption, pending time entries, open actions, employee context.

Get session

Section titled “Get session”
GET /api/squads/:id/sessions/:sessionId

Full session detail. Employee/Lead access omits 4P notes. Includes linked actions.

Update session

Section titled “Update session”
PATCH /api/squads/:id/sessions/:sessionId

Body: progress_notes, plans_notes, problems_notes, promotions_notes, attendees (JSON array), facilitator_id

Complete session

Section titled “Complete session”
POST /api/squads/:id/sessions/:sessionId/complete

Sets status to completed, records completed_at and completed_by.

Generate session brief

Section titled “Generate session brief”
POST /api/squads/:id/sessions/:sessionId/generate

Gathers context (utilisation, time entries, Granola meetings, open actions, client health, per-employee data) and calls Claude to generate a 4P draft.

Response: { progress, plans, problems, promotions } — draft text for each section.

Actions

Section titled “Actions”

List squad actions

Section titled “List squad actions”
GET /api/squads/:id/actions

Query params: completed (boolean), session_id

Create squad action

Section titled “Create squad action”
POST /api/squads/:id/actions

Body: title, assigned_to (user ID), due_date, notes, session_id

Also creates a mirrored action_items record.

Update squad action

Section titled “Update squad action”
PATCH /api/squad-actions/:actionId

Body: title, assigned_to, due_date, notes

Complete squad action

Section titled “Complete squad action”
POST /api/squad-actions/:actionId/complete

Marks the action and its mirrored action_items record as completed.

Admin Endpoints

Section titled “Admin Endpoints”

Squad CRUD is also available via the admin API (/api/admin/squads), which requires Executive access.