Shifts

Model your production shifts, record what happened on each one, and compare performance across shifts. All endpoints are authenticated with a Bearer JWT (see Authentication).

Endpoints

Method	Path	Description
GET	/api/v1/shifts/definitions	List shift definitions
POST	/api/v1/shifts/definitions	Create a shift definition (Admin)
PUT	/api/v1/shifts/definitions/{definition_id}	Update a shift definition (Admin)
DELETE	/api/v1/shifts/definitions/{definition_id}	Deactivate a shift definition (Admin)
GET	/api/v1/shifts/logs	List shift logs
POST	/api/v1/shifts/logs	Create a shift log
PATCH	/api/v1/shifts/logs/{log_id}	Update a shift log
DELETE	/api/v1/shifts/logs/{log_id}	Delete a shift log (Admin)
GET	/api/v1/shifts/logs/{log_id}/handover	Handover report for a shift log
GET	/api/v1/shifts/comparison	Shift-over-shift OEE comparison
GET	/api/v1/shifts/active	Currently active shifts

Endpoints marked Admin require an account administrator role.

Shift definitions

A shift definition is a reusable template (name, start/end time, duration, display color).

List shift definitions

GET /api/v1/shifts/definitions

Parameter	Type	Default	Description
active_only	boolean	true	Return only active definitions

Create a shift definition

POST /api/v1/shifts/definitions

{
  "name": "Morning",
  "start_time": "06:00:00",
  "end_time": "14:00:00",
  "duration_minutes": 480,
  "color": "#3B82F6",
  "is_active": true,
  "sort_order": 0
}

color must be a 7-character hex code (for example #3B82F6). The response returns the created definition with its id, created_at, and updated_at.

Shift logs

A shift log records an actual worked shift on a machine.

List shift logs

GET /api/v1/shifts/logs

Parameter	Type	Description
machine_id	uuid	Filter by machine
from_date	date	Start of date range
to_date	date	End of date range
status	string	active, completed, or cancelled
page	int	Page number (default 1)
page_size	int	Items per page

{
  "items": [
    {
      "id": "...",
      "machine_id": "...",
      "shift_definition_id": "...",
      "shift_date": "2026-08-05",
      "actual_start": "2026-08-05T06:00:00Z",
      "actual_end": "2026-08-05T14:02:00Z",
      "supervisor": "Jane Doe",
      "operator_count": 3,
      "handover_notes": "Line 2 slow to start.",
      "status": "completed",
      "shift_name": "Morning",
      "shift_color": "#3B82F6",
      "duration_minutes": 482.0,
      "created_at": "2026-08-05T06:00:05Z",
      "updated_at": "2026-08-05T14:02:10Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

Create a shift log

POST /api/v1/shifts/logs

{
  "machine_id": "MACHINE_UUID",
  "shift_definition_id": "DEFINITION_UUID",
  "shift_date": "2026-08-05",
  "actual_start": "2026-08-05T06:00:00Z",
  "actual_end": null,
  "supervisor": "Jane Doe",
  "operator_count": 3,
  "handover_notes": "Started on time.",
  "status": "active"
}

actual_end, when provided, must be after actual_start.

Handover report

GET /api/v1/shifts/logs/{log_id}/handover

Returns the shift log alongside the alerts and downtime events that occurred during the shift window.

{
  "shift_log": { "id": "...", "status": "completed" },
  "alerts_during_shift": [
    { "id": "...", "severity": "warning", "description": "Vibration high", "created_at": "2026-08-05T09:12:00Z" }
  ],
  "downtime_during_shift": [
    { "id": "...", "reason_type": "unplanned", "reason_note": "Jam", "started_at": "2026-08-05T10:00:00Z", "ended_at": "2026-08-05T10:18:00Z", "duration_minutes": 18.0 }
  ],
  "total_downtime_minutes": 18.0,
  "alert_count": 1
}

Shift comparison

GET /api/v1/shifts/comparison

Compares average OEE (and its availability, performance, and quality components) across shift definitions.

Parameter	Type	Description
machine_id	uuid	Filter to one machine (optional)
from_date	date	Start of date range
to_date	date	End of date range

{
  "machine_id": null,
  "from_date": "2026-07-01",
  "to_date": "2026-08-01",
  "shifts": [
    {
      "shift_definition_id": "...",
      "shift_name": "Morning",
      "shift_color": "#3B82F6",
      "record_count": 22,
      "avg_oee_pct": 79.8,
      "avg_availability_pct": 91.2,
      "avg_performance_pct": 88.5,
      "avg_quality_pct": 98.9,
      "total_downtime_minutes": 240,
      "avg_planned_production_minutes": 480.0
    }
  ]
}

See OEE for the underlying metric definitions.

Active shifts

GET /api/v1/shifts/active

Returns the shifts currently in progress, each with elapsed_minutes since actual_start.