Vendor API: Devices & Control

The endpoints a connected third-party system uses to discover and control individual C-Bridge devices. These are part of the Vendor API — the surface your integration calls with its own API key.

See Authentication for how to authenticate, and Third-Party Lighting Integration for how an integration is registered and its device access is scoped.

Base & Authentication

Item	Value
Base URL	`http://<gateway-ip>:5000/api/vendor`
Auth header	`Authorization: Bearer <apiKey>`
Content-Type	`application/json`

Every request needs one authentication header: Authorization: Bearer <apiKey>. Send the complete <credentialId>.<secret> value. For JSON request bodies, also send Content-Type: application/json.

Each endpoint lists the operation your key must hold (monitor, read, or control). Confirm what your key can do with GET /me (see Monitoring & Status).

List devices

GET /devices — operation: monitor

Returns the devices exposed to your integration (subject to its allow-list).

{
  "success": true,
  "data": [
    {
      "id": "319701d5-e8be-4ac9-b516-9ca2e3969cda",
      "name": "Cafe Window Lights",
      "unitId": 79,
      "status": "online",
      "category": ["light"],
      "space": null
    }
  ]
}

Field	Meaning
`id`	Device identifier — use it in every other call below
`name`	Human-readable device name
`status`	`online` or `offline`
`category`	Device type(s), e.g. `light`, `shade`, `sensor`
`unitId`	Underlying hardware unit number

Get a device

GET /devices/:id — operation: read

The full record for one device, including model and timestamps.

Read device state

GET /devices/:id/state — operation: monitor

Returns the device's reported state object. Poll this (or the device list) to reflect current state in your UI.

Control a device

POST /devices/:id/control — operation: control

Send one or more control fields in the body. Combine fields in a single call (e.g. power + brightness).

Action	Body
Turn on	`{ "power": true }` (or `{ "on": true }`)
Turn off	`{ "power": false }`
Set brightness	`{ "level": 75 }` — 0–100 (`brightness` is also accepted)
Set colour temperature	`{ "level": 80, "colorTemp": 4000 }`
Set RGB colour	`{ "r": 255, "g": 100, "b": 0 }` — each 0–255

Successful response:

{
  "success": true,
  "data": {
    "deviceId": "319701d5-...",
    "deviceName": "Cafe Window Lights",
    "controlData": { "power": true, "dimmer": 75 },
    "message": "Control command sent successfully"
  }
}

Errors

HTTP	`code`	Meaning
400	`CONTROL_DATA_REQUIRED`	The body was empty `{}` — include at least one control field
404	`DEVICE_NOT_FOUND`	The id doesn't exist or isn't exposed to your integration
403	`OPERATION_DENIED`	Your key does not hold the `control` operation

Example

# Turn a light on at 60%
curl -s -X POST http://<gateway-ip>:5000/api/vendor/devices/<id>/control \
  -H "Authorization: Bearer <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{"power": true, "level": 60}'