Make your first request

This path verifies authentication with a read-only request, shows the standard response envelope, and gives you a safe foundation for your first write.

1. Create a scoped key

In Canary, open Settings → API Keys, create a key, and grant assets:read. Copy the value when it appears; Canary shows the full key once. Store it in an environment variable:

export CANARY_API_KEY="sk_live_replace_me"

Test and live keys access the same organization records. Use a dedicated organization or clearly identified fixtures for development writes.

2. List one asset

Choose the example for your runtime. Each version calls the production endpoint, sends the Bearer header, and stops on a non-successful response.

curl --fail-with-body --silent --show-error \
  "https://api.oncanary.com/v1/assets?limit=1" \
  --header "Authorization: Bearer $CANARY_API_KEY"

const apiKey = process.env.CANARY_API_KEY;
if (!apiKey) throw new Error('Set CANARY_API_KEY');

const response = await fetch('https://api.oncanary.com/v1/assets?limit=1', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code ?? response.status}: ${body.detail ?? 'Request failed'}`);
}

console.log(body.data);
console.log('request', response.headers.get('X-Request-ID'));

import os
import requests

response = requests.get(
    'https://api.oncanary.com/v1/assets?limit=1',
    headers={'Authorization': f"Bearer {os.environ['CANARY_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()

body = response.json()
print(body['data'])
print('request', response.headers.get('X-Request-ID'))

A successful Canary-native list uses this shape:

{
  "data": [
    {
      "id": "01JAY7C1NQZ5H2R8M4K6T9V3BP",
      "name": "North compressor",
      "asset_type": "equipment",
      "status": "online",
      "criticality": "critical"
    }
  ],
  "meta": {
    "request_id": "req_01JAY8FVDM6CH4R3X9Q2T7K5NP",
    "api_version": "v1",
    "pagination": {
      "has_more": false
    }
  }
}

An empty data array is also a successful connection.

3. Make the first write

Grant work_orders:write to a key, then create a work order. The resource IDs for asset_id, location_id, and assignees are optional.

curl --fail-with-body --silent --show-error \
  --request POST "https://api.oncanary.com/v1/work-orders" \
  --header "Authorization: Bearer $CANARY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Inspect north compressor",
    "description": "Check vibration and oil level",
    "priority": "high"
  }'

The response has HTTP 201 and places the created work order in data.

4. Build for operations

Before running a recurring synchronization:

Follow the endpoint’s pagination variant.
Retry 429 responses using Retry-After and use backoff for transient 5xx failures.
Log X-Request-ID with every request.
Plan write retries using the idempotency guidance.

Resource model

Choose the right records and relationships.

Endpoint reference

Browse request fields, filters, scopes, and response schemas.

API essentials

Work management

Equipment

Inventory

Organization data

Make your first request

Make your first request

1. Create a scoped key

2. List one asset

3. Make the first write

4. Build for operations

Resource model

Endpoint reference

​Make your first request

​1. Create a scoped key

​2. List one asset

​3. Make the first write

​4. Build for operations

Resource model

Endpoint reference

Make your first request

1. Create a scoped key

2. List one asset

3. Make the first write

4. Build for operations