Work Orders

Work orders track repair and maintenance jobs on a machine. Each work order can carry ordered instructions, a comment thread, and file attachments. All endpoints require a bearer JWT.

Endpoints

Method	Path	Description
POST	/api/v1/work-orders	Create a work order
GET	/api/v1/work-orders	List work orders
GET	/api/v1/work-orders/{work_order_id}	Get a work order
PATCH	/api/v1/work-orders/{work_order_id}	Update a work order
DELETE	/api/v1/work-orders/{work_order_id}	Delete a work order
GET	/api/v1/work-orders/{work_order_id}/comments	List comments
POST	/api/v1/work-orders/{work_order_id}/comments	Add a comment
GET	/api/v1/work-orders/{work_order_id}/instructions	List instructions
POST	/api/v1/work-orders/{work_order_id}/instructions	Add an instruction
GET	/api/v1/work-orders/{work_order_id}/instructions/{instruction_id}	Get an instruction
PATCH	/api/v1/work-orders/{work_order_id}/instructions/{instruction_id}	Update an instruction
DELETE	/api/v1/work-orders/{work_order_id}/instructions/{instruction_id}	Delete an instruction
POST	/api/v1/attachments	Upload an attachment
GET	/api/v1/attachments/work-order/{work_order_id}	List a work order's attachments
GET	/api/v1/attachments/{attachment_id}	Get attachment metadata
GET	/api/v1/attachments/{attachment_id}/download	Download an attachment
DELETE	/api/v1/attachments/{attachment_id}	Delete an attachment

Create a work order

POST /api/v1/work-orders

Requires an operator or administrator role.

Field	Type	Required	Description
machine_id	uuid	Yes	Machine the work order applies to
alert_id	uuid	No	Alert that prompted the work order
title	string	Yes	Title (1–255 chars)
description	string	No	Details
priority	string	No	One of low, medium, high, critical (default medium)
assigned_to	uuid	No	Primary assignee
assignee_ids	array of uuid	No	Additional assignees
due_date	datetime	No	Due date (ISO 8601 UTC)

{
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Replace spindle bearings",
  "description": "Main spindle bearings showing excessive vibration.",
  "priority": "high",
  "assigned_to": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}

Response — 201 Created

{
  "id": "ee55...",
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "alert_id": null,
  "title": "Replace spindle bearings",
  "description": "Main spindle bearings showing excessive vibration.",
  "status": "open",
  "priority": "high",
  "assigned_to": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "assignee_ids": [],
  "due_date": null,
  "completed_at": null,
  "completion_notes": null,
  "created_by": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "created_at": "2026-08-07T10:00:00Z",
  "updated_at": "2026-08-07T10:00:00Z"
}

List work orders

GET /api/v1/work-orders

Parameter	Type	Description
machine_id	uuid	Filter by machine
status	string	One of open, in_progress, completed, cancelled
page	integer	Page number (default 1)
page_size	integer	Items per page (default 20, max 100)

Returns an items array with a total count.

Get, update, and delete

GET /api/v1/work-orders/{work_order_id} returns one work order. PATCH /api/v1/work-orders/{work_order_id} updates it and DELETE /api/v1/work-orders/{work_order_id} removes it (204 No Content). Update and delete require an operator or administrator role.

Updatable fields include title, description, status, priority, assigned_to, assignee_ids, due_date, and completion_notes.

{
  "status": "in_progress"
}

Comments

GET /api/v1/work-orders/{work_order_id}/comments lists the comment thread. POST /api/v1/work-orders/{work_order_id}/comments adds a comment (body up to 2,000 characters).

{
  "body": "Bearings ordered. Expected delivery next week."
}

Instructions

Instructions are ordered steps attached to a work order.

Add an instruction

POST /api/v1/work-orders/{work_order_id}/instructions

Requires an operator or administrator role.

Field	Type	Required	Description
step_order	integer	Yes	Step position (≥ 1)
title	string	Yes	Step title (1–255 chars)
body	string	No	Step detail (up to 5,000 chars)
attachment_id	uuid	No	Attachment to show with the step

{
  "step_order": 1,
  "title": "Lock out and tag out the machine",
  "body": "Follow the site LOTO procedure before opening the spindle housing."
}

Response — 201 Created

{
  "id": "ff66...",
  "work_order_id": "ee55...",
  "step_order": 1,
  "title": "Lock out and tag out the machine",
  "body": "Follow the site LOTO procedure before opening the spindle housing.",
  "attachment_id": null,
  "created_by": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "created_at": "2026-08-07T10:05:00Z",
  "updated_at": "2026-08-07T10:05:00Z"
}

List, get, update, and delete

GET /api/v1/work-orders/{work_order_id}/instructions returns the steps as an items array with a total. GET, PATCH, and DELETE on /api/v1/work-orders/{work_order_id}/instructions/{instruction_id} operate on a single step. Update and delete require an operator or administrator role.

Attachments

Attachments are files linked to a work order (or a maintenance event — see Maintenance).

Upload an attachment

POST /api/v1/attachments

Requires an operator or administrator role. Send the file as multipart/form-data under the file field and provide the target as a query parameter — either work_order_id or maintenance_event_id.

curl -X POST "https://api.haltless.io/api/v1/attachments?work_order_id=ee55..." \
  -H "Authorization: Bearer <jwt>" \
  -F "file=@inspection-photo.jpg"

Response — 201 Created

{
  "id": "aa77...",
  "work_order_id": "ee55...",
  "maintenance_event_id": null,
  "uploaded_by": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "filename": "inspection-photo.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 245678,
  "created_at": "2026-08-07T10:10:00Z",
  "updated_at": "2026-08-07T10:10:00Z"
}

List, download, and delete

GET /api/v1/attachments/work-order/{work_order_id} lists a work order's attachments. GET /api/v1/attachments/{attachment_id} returns metadata, and GET /api/v1/attachments/{attachment_id}/download returns the file bytes with a Content-Disposition header. DELETE /api/v1/attachments/{attachment_id} removes an attachment (204 No Content) and requires an operator or administrator role.

Status flow

Status	Description
open	Created, not yet started
in_progress	Work underway
completed	Work finished
cancelled	Work order cancelled