> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncanary.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, response conventions, headers, and the generated Canary API reference

# API overview

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

```text theme={"theme":"github-light"}
https://api.oncanary.com/v1
```

[Download the OpenAPI 3.1 document](/openapi.yaml) 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.

```json theme={"theme":"github-light"}
{
  "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.

```json theme={"theme":"github-light"}
{
  "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](/guides/errors).

## 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.

<CardGroup cols={2}>
  <Card title="Resource model" icon="boxes" href="/api-reference/resource-model">
    Understand relationships and lifecycle behavior.
  </Card>

  <Card title="Integration patterns" icon="waypoints" href="/guides/integration-patterns">
    Build pagination, retries, request approval, and file handling into production clients.
  </Card>
</CardGroup>