Skip to content

API — Rosters & allocation runs

Purpose

Running the allocation engine (allocation runs), inspecting their candidates and ineligibility, managing shift assignments, the employee's own roster, and the equalization view.

Auth & roles

Area Base Gates
Allocation runs /api/allocation-runs allocation_run.read / .write / .execute / .lock / .debug / .archive
Shift assignments /api/... roster.view / roster.create / roster.edit
My roster /api/me/roster [Authorize]
Equalization /api/admin/equalization reconciliation.view

allocation_run.execute/.lock are SYS_ADMIN + PLANNER; allocation_run.debug is SYS_ADMIN only (see RBAC matrix).

Endpoints

Allocation runs — /api/allocation-runs

Method Path Purpose Gate
GET / POST /api/allocation-runs List / create a run read / write
GET / DELETE /api/allocation-runs/{id} Detail / archive a run read / archive
POST /api/allocation-runs/{id}/execute Run the engine allocation_run.execute
POST /api/allocation-runs/{id}/rerun Re-run allocation_run.execute
POST /api/allocation-runs/{id}/review Human review step allocation_run.write
POST /api/allocation-runs/{id}/lock Lock the run allocation_run.lock
GET /api/allocation-runs/{id}/candidates All candidates read
GET /api/allocation-runs/{id}/candidates/{demandLineId} Candidates for a line read
GET /api/allocation-runs/{id}/candidates/{demandLineId}/ineligible Per-rule ineligibility reasons allocation_run.debug

Shift assignments — base /api

Method Path Purpose Gate
GET /api/shift-assignments List assignments roster.view
GET /api/employees/{id}/shift-assignments · /shift-schedule An employee's assignments / schedule roster.view
POST /api/employees/{id}/shift-assignments Create an assignment roster.create
DELETE /api/shift-assignments/{id} Remove an assignment roster.edit

My roster / Equalization

Method Path Purpose Gate
GET /api/me/roster Caller's own roster [Authorize]
GET /api/admin/equalization Equalization scores view reconciliation.view

Shapes & errors

A run uses snapshot pre-materialization and a human-gated state machine (sheet 09). Equalization scores three cohort rules on the snapshot, returning a neutral score on DB-fallback (sheet 14). Standard ProblemDetails.

Gotchas — the F-findings

  • F6 — ineligibility reasons are gated to allocation_run.debug (SYS_ADMIN only). The per-rule reasons a candidate was excluded (which rule blocked them, and why) are computed and available at …/candidates/{demandLineId}/ineligible, but only SYS_ADMIN can call it. A PLANNER troubleshooting an unfilled run cannot see the reasons through the normal UI — the data exists server-side; the gate hides it. Build/diagnose accordingly.
  • F8 — equalization tiers and cross-pool lending-reasons are computed server-side but not surfaced in the UI. The equalization Below/At/Above tier classification (and the cross-pool block reasons, see Pools) are produced by the engine but the frontend does not display them. A developer consuming /api/admin/equalization gets the scores; the tier/reason richness is in the server computation, not the rendered screen.
  • Web "Execute" button is PARTIAL; the ShiftMix cohort populator is PARTIAL (sheet 09).