Maintenance

Maintenance events schedule planned work on a machine over a start and end time. All endpoints require a bearer JWT.

Endpoints

Method	Path	Description
POST	/api/v1/maintenance	Schedule a maintenance event
GET	/api/v1/maintenance	List maintenance events
GET	/api/v1/maintenance/{event_id}	Get a maintenance event
PUT	/api/v1/maintenance/{event_id}	Update a maintenance event
DELETE	/api/v1/maintenance/{event_id}	Delete a maintenance event

Schedule an event

POST /api/v1/maintenance

Requires an operator or administrator role.

Field	Type	Required	Description
machine_id	uuid	Yes	Machine the event applies to
title	string	Yes	Event title (1–300 chars)
description	string	No	Details (up to 4,000 chars)
scheduled_start	datetime	Yes	Start time (ISO 8601 UTC)
scheduled_end	datetime	Yes	End time (ISO 8601 UTC)
linked_alert_id	uuid	No	Alert that prompted this event
assigned_to	uuid	No	User the event is assigned to
recurrence_rule	string	No	One of daily, weekly, monthly, quarterly

When recurrence_rule is set, a series of child events is generated automatically from the parent.

{
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Quarterly bearing inspection",
  "description": "Check and replace main spindle bearings if needed.",
  "scheduled_start": "2026-08-10T08:00:00Z",
  "scheduled_end": "2026-08-10T12:00:00Z",
  "recurrence_rule": "quarterly"
}

Response — 201 Created

{
  "id": "dd44...",
  "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Quarterly bearing inspection",
  "description": "Check and replace main spindle bearings if needed.",
  "scheduled_start": "2026-08-10T08:00:00Z",
  "scheduled_end": "2026-08-10T12:00:00Z",
  "status": "scheduled",
  "linked_alert_id": null,
  "assigned_to": null,
  "created_by": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "created_at": "2026-08-07T10:00:00Z",
  "recurrence_rule": "quarterly",
  "parent_event_id": null
}

List events

GET /api/v1/maintenance

Parameter	Type	Description
machine_id	uuid	Filter by machine
status	string	One of scheduled, in_progress, completed, cancelled
start_after	datetime	Events starting on or after this time
end_before	datetime	Events ending on or before this time

Returns an array of maintenance events.

Get an event

GET /api/v1/maintenance/{event_id}

Returns one event, or 404 if it is not found.

Update an event

PUT /api/v1/maintenance/{event_id}

Requires an operator or administrator role. Include only the fields you want to change.

Field	Type	Description
title	string	New title (1–300 chars)
description	string	New description
scheduled_start	datetime	New start time
scheduled_end	datetime	New end time
status	string	One of scheduled, in_progress, completed, cancelled
assigned_to	uuid	New assignee

Delete an event

DELETE /api/v1/maintenance/{event_id}

Requires an operator or administrator role. Returns 204 No Content.

Statuses

Status	Description
scheduled	Planned, not yet started
in_progress	Work underway
completed	Work finished
cancelled	Event cancelled