Skip to main content

​
Resource model

Canary organizes maintenance around work, equipment context, measurements, inventory, and organization-defined data.

​
Relationship map

​
Work requests and work orders

Work requests use the MaintainX-compatible wire style. Their public status vocabulary is PENDING, REJECTED, APPROVED, and DONE. Internally canceled requests stay outside this compatibility surface. Create a native work order with workRequestId to approve a pending request and link the resulting work order in one operation:
A replay with the same request returns its existing linked work order. A rejected request returns 409 invalid_work_request_state. The compatibility /workorders adapter uses uppercase types and priorities. Priority mappings preserve its narrower vocabulary: NONE creates Canary priority medium, and Canary critical reads as compatibility HIGH. DELETE /work-orders/{id} soft-deletes the record and preserves its maintenance history, costs, procedure results, and audit evidence. Deleted work orders disappear from public reads, and chain fields such as previous_id or next_id become null when their linked record is unavailable. Repeating the same delete returns 204 No Content.

​
Assets and locations

Asset status values are online, offline, and not_monitored. Asset criticality values are critical, important, and normal. asset_type is Canary’s built-in classification (equipment, vehicle, or facility). asset_types is a read-only array of organization-defined type assignments. Asset hierarchy fields are also read-only in public v1:
  • parent_asset_id identifies the direct parent.
  • sub_asset_count counts active descendants.
Locations expose parentId on reads and writes. Location detail includes childrenIds. The current hierarchy supports one parent/sub-location level and rejects invalid moves with 409 invalid_location_hierarchy.

​
Meters and readings

A new meter must reference exactly one asset_id or location_id. Readings are immutable time-series observations ordered by reading_at and ID. DELETE /meters/{id} archives an active meter. Existing readings are preserved. A meter referenced by an automation returns 409 resource_in_use until the dependency is removed. Parts are master records. Link and unlink them through /assets/{id}/parts/{partId}. Both operations require parts:write, and both resources must belong to the key’s organization. The public Part resource describes the part record and minimum-stock setting. Direct inventory adjustment endpoints are outside public v1. Work-order consumption is available through /work-orders/{id}/parts.

​
Work-order parts

GET /work-orders/{id}/parts requires work_orders:read and returns the section object directly, including rows, partStatus, server-computed capabilities, and aggregateVersion. POST /work-orders/{id}/parts requires work_orders:write. Send a new idempotencyKey and the last-read expectedAggregateVersion with each command. Retry an uncertain response with the identical command and key. Refetch after a 409 conflict.
  • operation: "transition" takes targetStatus: assigned, reserved, kitted, staged, or issued. Follow capabilities.allowedTransitions; staging settings may hide statuses.
  • operation: "replace" takes the complete desired items array (id, partId, locationId, positive integer quantity, optional unitCostMinor). Retain row IDs when editing; omit rows to remove them. Cost overrides require the organization setting and an authorized caller.
Assigned parts do not reserve stock. Reserved, Kitted, and Staged contribute to committed quantity. Issued deducts stock immediately; completion also issues pending parts. Editing issued usage adjusts stock by the difference, including on completed work orders. Returning an active work order’s parts from Issued to Assigned returns its effective used quantity. Reopening a work order preserves Issued status. Original stock movements remain in history alongside corrections.

​
Custom fields

Custom-field definition routes use plural compatibility entity names: assets, locations, parts, and workOrders. Entity writes accept extraFields as an object keyed by the visible field label:
Detail responses include extraFields. Asset, part, and native work-order lists omit those values; location lists include them when expand=extra_fields is requested.

​
Identifiers

Identifiers are organization-scoped mappings from exact scanner payloads to assets, locations, or parts. Canary-generated values and customer-owned values share the same resolver. See Identifiers for attach, generate, import, and resolution workflows.