Work orders

Create, assign, and track maintenance tasks linked to building equipment and insights.

Endpoints

GET    /api/v1/sites/{siteId}/work-orders/
POST   /api/v1/sites/{siteId}/work-orders/
GET    /api/v1/sites/{siteId}/work-orders/{id}/
PATCH  /api/v1/sites/{siteId}/work-orders/{id}/
DELETE /api/v1/sites/{siteId}/work-orders/{id}/

Work orders track maintenance tasks for building equipment. You can create them manually or link them to an insight for automatic context.

All work order endpoints require authentication. See Authentication for details on API keys and JWT tokens.

Path parameters

Parameter	Type	Description
siteId	string	Site slug (e.g., ucl-east-campus)
id	uuid	Work order ID (for detail/update/delete)

Query parameters (list endpoint)

Parameter	Type	Description
status	string	Filter by status: open, in_progress, on_hold, completed, cancelled
priority	string	Filter by priority: none, low, medium, high
type	string	Filter by type: reactive, preventive, inspection, emergency
equipment_uri	string	Filter by equipment Fuseki URI
assigned_to	uuid	Filter by assigned user ID

Request body (create / update)

Field	Type	Required	Description
title	string	Yes	Short description of the task
description	string	No	Detailed instructions or context
status	string	No	Default: open. One of: open, in_progress, on_hold, completed, cancelled
priority	string	No	Default: none. One of: none, low, medium, high
type	string	No	Default: reactive. One of: reactive, preventive, inspection, emergency
category	string	No	Free-text category (e.g., HVAC, Electrical, Plumbing)
equipment_uri	string	No	Fuseki URI of the equipment this task relates to
location_uri	string	No	Fuseki URI of the location (auto-filled from equipment if available)
assigned_to	uuid	No	User ID of the assignee
requester_name	string	No	Name of the person who requested the work
requester_email	string	No	Email of the requester
due_date	string	No	ISO-8601 deadline
insight	uuid	No	Link to an insight. Auto-transitions the insight from open to in_progress
parent	uuid	No	Parent work order ID (for sub-tasks)

For PATCH requests, include only the fields you want to change.

Response

Field	Type	Description
id	uuid	Work order ID
site	string	Site ID
title	string	Task title
description	string	Detailed description
status	string	Current status
priority	string	Priority level
type	string	Work order type
category	string	Category label
equipment_uri	string	Equipment Fuseki URI
location_uri	string	Location Fuseki URI
created_by	uuid	User who created this work order
created_by_detail	object	Creator’s name and email
assigned_to	uuid | null	Assigned user ID
assigned_to_detail	object | null	Assignee’s name and email
requester_name	string	Requester name
requester_email	string	Requester email
insight	uuid | null	Linked insight ID
parent	uuid | null	Parent work order ID
due_date	string | null	Deadline
started_at	string | null	When work began
completed_at	string | null	When work finished
created_at	string	Creation timestamp
updated_at	string	Last update timestamp
comment_count	integer	Number of comments

Insight linking

When you create a work order with an insight field, Tacit automatically transitions that insight from open to in_progress (if it is still open). This connects the detection-to-action pipeline: an FDD system detects a fault, an insight is created, and a work order is assigned to resolve it.

Comments and attachments

Work orders support threaded comments and file attachments:

Endpoint	Method	Description
.../work-orders/{id}/comments/	GET	List comments
.../work-orders/{id}/comments/	POST	Add comment (body field)
.../work-orders/{id}/attachments/	GET	List attachments
.../work-orders/{id}/attachments/	POST	Upload file (file + name fields, multipart)
.../work-orders/{id}/attachments/{attachmentId}/	DELETE	Remove attachment
.../work-orders/{id}/attachments/{attachmentId}/download/	GET	Download file

Status codes

Code	Description
200	Success (list, retrieve, update)
201	Work order created
204	Work order or attachment deleted
400	Validation error
401	Not authenticated
403	No access to this site
404	Work order not found
429	Rate limit exceeded

Examples

Create a work order

curl -X POST https://app.betacit.com/api/v1/sites/ucl-east-campus/work-orders/ \
  -H "Authorization: Bearer tac_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Inspect cooling coil valve actuator on AHU-01",
    "description": "Valve stuck at 87% open. Check actuator for mechanical failure.",
    "priority": "high",
    "type": "reactive",
    "category": "HVAC",
    "equipment_uri": "http://fuseki:3030/buildings/ucl-east#AHU-01",
    "assigned_to": "7a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "due_date": "2026-03-17T17:00:00Z"
  }'

Response (201)

{
  "id": "b2c3d4e5-6789-0abc-def1-234567890abc",
  "site": "ucl-east-campus",
  "title": "Inspect cooling coil valve actuator on AHU-01",
  "description": "Valve stuck at 87% open. Check actuator for mechanical failure.",
  "status": "open",
  "priority": "high",
  "type": "reactive",
  "category": "HVAC",
  "equipment_uri": "http://fuseki:3030/buildings/ucl-east#AHU-01",
  "location_uri": "",
  "created_by": "5d8a6550-b019-4f56-ac6d-bc128af09a9a",
  "created_by_detail": { "id": "5d8a6550-b019-4f56-ac6d-bc128af09a9a", "username": "pamekitti", "email": "[e-mail]" },
  "assigned_to": "7a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "assigned_to_detail": { "id": "7a2b3c4d-5e6f-7890-abcd-ef1234567890", "username": "alex", "email": "[e-mail]" },
  "requester_name": "",
  "requester_email": "",
  "insight": null,
  "parent": null,
  "due_date": "2026-03-17T17:00:00Z",
  "started_at": null,
  "completed_at": null,
  "created_at": "2026-03-15T11:00:00Z",
  "updated_at": "2026-03-15T11:00:00Z",
  "comment_count": 0
}

Create from an insight

Link a work order to an insight to connect detection to action. The insight automatically transitions to in_progress:

Request

{
  "title": "Replace chiller compressor — efficiency below threshold",
  "priority": "high",
  "type": "reactive",
  "equipment_uri": "http://fuseki:3030/buildings/ucl-east#Chiller-01",
  "insight": "d4f7a1b2-8e3c-4f9a-b5d6-1c2e3f4a5b6c"
}

The response is the standard work order object with the insight field populated.

List with filters

curl "https://app.betacit.com/api/v1/sites/ucl-east-campus/work-orders/?status=open&priority=high" \
  -H "Authorization: Bearer tac_your_api_key_here"

Response (200)

[
  {
    "id": "b2c3d4e5-6789-0abc-def1-234567890abc",
    "title": "Inspect cooling coil valve actuator on AHU-01",
    "status": "open",
    "priority": "high",
    "type": "reactive",
    "category": "HVAC",
    "equipment_uri": "http://fuseki:3030/buildings/ucl-east#AHU-01",
    "assigned_to": "7a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "due_date": "2026-03-17T17:00:00Z",
    "created_at": "2026-03-15T11:00:00Z",
    "comment_count": 0
  }
]

Update status to completed

curl -X PATCH https://app.betacit.com/api/v1/sites/ucl-east-campus/work-orders/b2c3d4e5-6789-0abc-def1-234567890abc/ \
  -H "Authorization: Bearer tac_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "completed_at": "2026-03-16T14:30:00Z" }'

Response (200)

{
  "id": "b2c3d4e5-6789-0abc-def1-234567890abc",
  "title": "Inspect cooling coil valve actuator on AHU-01",
  "status": "completed",
  "priority": "high",
  "type": "reactive",
  "completed_at": "2026-03-16T14:30:00Z",
  "updated_at": "2026-03-16T14:30:00Z",
  "comment_count": 0
}