Getting started

Everything below runs against https://api.canaro.ca/external/v1. You need a Canaro workspace on a plan that includes API access, and an owner or admin role in it.

Create a workspace API key.

In the Canaro dashboard, open Settings → API and create a key. Grant it only the scopes the integration needs, and set an expiry if you want one.

The full key is shown once, at creation. It begins with cnr_. Store it in your secret manager; the dashboard keeps only a display prefix and a hash, so it cannot show you the key again.

Make your first call.

The account endpoint needs the account:read scope and tells you what your plan allows.

curl https://api.canaro.ca/external/v1/account \
  -H "Authorization: Bearer cnr_your_key_here"

{
  "workspace_id": "9f1c4d6e-2b70-4a55-9a1e-6c3f8b2d5471",
  "name": "Northfield Agriculture",
  "plan": {
    "plan_id": "enterprise_l1",
    "name": "Enterprise Basic",
    "max_api_keys": 5,
    "external_requests_per_minute": 60,
    "external_requests_per_day": 25000,
    "history_max_days": 365,
    "max_devices_per_page": 200
  },
  "usage": { "devices": 48, "open_alerts": 3 }
}

Every response also carries X-RateLimit-Limit and X-RateLimit-Remaining — see Rate limits.

List your devices.
Terminal window
```
curl "https://api.canaro.ca/external/v1/devices?limit=50" \
  -H "Authorization: Bearer cnr_your_key_here"
```
Hubs and add-ons come back in one flat list; an add-on’s parent_device_id names the hub it reports to. When a response includes next_cursor, pass it back as cursor for the next page — see Pagination.

Handle refusals.

Anything that is not a success is a JSON object with a single error member:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not hold devices:read.",
    "required_scope": "devices:read"
  }
}

The full code set, and what each one means, is in Errors.

Where to next

The API reference lists every endpoint, parameter, response and example, generated from the API’s own contract.
Authentication covers key lifecycle and the refusals you can hit before a request reaches an endpoint.