Departments API
Manage departments and link staff to them. All routes require Authorization: Bearer <access_token> and admin role. Base path: <API_BASE_URL>/departments.
List departments
Returns all departments. Query: active_only (optional; use 1, true, or yes to return only active departments). Response: {"departments": [{"id", "name", "description", "is_active", "created_at", "staff_count"}, ...]}.
Create department
Create a department. Body: name (required), description (optional). Returns full department with staff list (201). 409 if name already exists.
Get, update, disable, delete
Returns one department with id, name, description, is_active, created_at, staff_count, and staff (array of staff in this department). 404 if not found.
Update department. Body: optional name, description, is_active. Returns full department. 409 if name already used by another department.
Sets is_active to false. Returns full department. Disabled departments cannot be assigned to new staff; existing staff keep the link until updated.
Permanently delete a department. Staff previously in this department have department_id set to null (on delete SET NULL). 404 if not found.
Common responses
401 if missing or invalid token. 403 if not admin. 404 if department not found. 409 if department name already exists.