Work orders

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": "[email protected]" },
  "assigned_to": "7a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "assigned_to_detail": { "id": "7a2b3c4d-5e6f-7890-abcd-ef1234567890", "username": "alex", "email": "[email protected]" },
  "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
}

GraphQL

REST API

REST guides

Endpoints

Path parameters

Query parameters (list endpoint)

Request body (create / update)

Response

Insight linking

Comments and attachments

Status codes

Examples

Create a work order

Create from an insight

List with filters

Update status to completed

​Endpoints

​Path parameters

​Query parameters (list endpoint)

​Request body (create / update)

​Response

​Insight linking

​Comments and attachments

​Status codes

​Examples

​Create a work order

​Create from an insight

​List with filters

​Update status to completed

Endpoints

Path parameters

Query parameters (list endpoint)

Request body (create / update)

Response

Insight linking

Comments and attachments

Status codes

Examples

Create a work order

Create from an insight

List with filters

Update status to completed