API overview

Canary v1 is an HTTPS JSON API authenticated by scoped organization keys.

https://api.oncanary.com/v1

Download the OpenAPI 3.1 document for code generation, contract testing, or local reference. Endpoint pages in this documentation are generated from docs/openapi.yaml.

Request conventions

Header	When to send	Value
`Authorization`	Every request	`Bearer {api_key}`
`Content-Type`	JSON writes	`application/json`
`Content-Type`	Work-request file upload	The file media type or `application/octet-stream`

Query parameter and JSON field names are case-sensitive. Use the casing shown on each operation.

Response conventions

The public API contains two stable wire styles. Choose the response parser from the endpoint family.

Canary-native

Assets, locations, parts, meters, meter readings, native work orders, and identifiers use snake_case fields inside a standard envelope.

{
  "data": {
    "id": "01JAY7C1NQZ5H2R8M4K6T9V3BP",
    "name": "North compressor",
    "status": "online"
  },
  "meta": {
    "request_id": "req_01JAY8FVDM6CH4R3X9Q2T7K5NP",
    "api_version": "v1"
  }
}

Native lists place an array in data and pagination state in meta.pagination. Some native resources retain specific camelCase fields, such as location parentId and custom-field extraFields. The work-order parts subresource returns its section object directly, with aggregateVersion and server-computed capabilities, rather than a data envelope. Always use the operation’s schema when generating clients.

MaintainX-compatible

Work requests, request portals, custom-field definitions, and compatibility POST /workorders preserve their external camelCase shapes.

{
  "workRequests": [],
  "nextCursor": null,
  "nextPageUrl": null
}

Custom-field lists return a JSON array. Compatibility writes can return { "id": "..." }, a resource wrapper, or 204 No Content. Follow the generated response schema for each operation. Compatibility applies to the documented operations and fields. Canary v1 does not expose every feature available in the Canary application or every MaintainX endpoint. Vendors, purchase orders, maintenance plans, procedures, teams, users, conversations, and webhook subscriptions currently have no public v1 route family. Parts inventory adjustments and asset hierarchy mutations also remain outside this API.

Errors

Both wire styles use application/problem+json errors with status, detail, request_id, and a machine-readable code. See Error handling.

Response headers

Header	Availability	Use
`X-Request-ID`	Every response, including `204` and errors	Correlate logs and support requests
`X-RateLimit-Limit`	Successful authenticated responses	Requests available in the current one-minute window
`X-RateLimit-Remaining`	Successful authenticated responses	Requests left in the window
`X-RateLimit-Reset`	Successful authenticated responses	Unix timestamp for the window reset
`Retry-After`	`429` responses	Seconds to wait before retrying

Status codes

Status	Meaning
200	Read, update, or compatibility write succeeded
201	Resource or upload created
204	Mutation succeeded with no response body
400	Query, JSON, filename, or field validation failed
401	API key is missing or invalid
403	Scope is missing or the required organization module is disabled
404	The resource or related record is unavailable to the organization
409	Current resource state or uniqueness constraint blocks the operation
413	Work-request upload exceeds 1 MiB
415	Thumbnail or image media cannot be accepted
429	The API key exhausted its one-minute request budget
500	An unexpected server failure occurred

Endpoint reference

Use the generated endpoint groups in the sidebar for the complete current operation inventory. Each operation describes its required scope, parameters, body, success shape, and known error responses.

Resource model

Understand relationships and lifecycle behavior.

Integration patterns

Build pagination, retries, request approval, and file handling into production clients.

API essentials

Work management

Equipment

Inventory

Organization data

API overview

API overview

Request conventions

Response conventions

Canary-native

MaintainX-compatible

Errors

Response headers

Status codes

Endpoint reference

Resource model

Integration patterns

​API overview

​Request conventions

​Response conventions

​Canary-native

​MaintainX-compatible

​Errors

​Response headers

​Status codes

​Endpoint reference

Resource model

Integration patterns

API overview

Request conventions

Response conventions

Canary-native

MaintainX-compatible

Errors

Response headers

Status codes

Endpoint reference