Overview
The C-Bridge API provides programmatic access to all building automation data and controls — devices, lighting states, energy, scenes, alerts, and more. It is designed for integration with third-party platforms, custom dashboards, and automation workflows.
Protocol: REST (HTTP) + WebSocket
Version: v1
Authentication: Bearer JWT
Base Configuration
| Item | Value |
|---|---|
| Base URL | http://<gateway-ip>:5000/api |
| WebSocket | ws://<gateway-ip>:5000 |
| Auth Type | Bearer JWT |
| Content-Type | application/json |
Replace <gateway-ip> with your C-Bridge device's IP address or hostname (e.g., 192.168.1.100 or cbridge.local).
What You Can Do with the API
- Monitor — read real-time and historical device states, sensor values, and energy data
- Control — turn devices on/off, adjust brightness and colour temperature, recall scenes
- Automate — create and manage schedule events and alerts programmatically
- Integrate — connect C-Bridge to custom dashboards, BMS platforms, SCADA systems, and automation tools
- Expose — grant third-party lighting, BMS, and AV/control systems (e.g. Crestron, Control4, custom platforms) scoped, credentialed access to read and control C-Bridge devices, scenes, and energy data
- Stream — subscribe to real-time events via WebSocket for live updates
Two API Surfaces
C-Bridge actually has two separate API surfaces, each with its own authentication:
| API Surface | Purpose | Auth Type |
|---|---|---|
| Gateway REST/WebSocket API | Direct device, scene, energy, and system control on the local gateway | Bearer JWT (/api/auth/generate-token) |
| Expose Integration API | Registering and managing third-party systems that read/control C-Bridge data (e.g. Crestron, other lighting platforms, BMS) | Bearer JWT (/api/auth/login) to manage integrations; a single self-contained vendor API key (Authorization: Bearer <apiKey>) for the third-party system's own calls |
See the Authentication guide for full details on generating and refreshing tokens for both surfaces.
Integrating Other Lighting & Building Systems
Third-party lighting control platforms, AV/control systems, and BMS platforms connect to C-Bridge through the Expose Integration API, not the Gateway API. An admin registers the third-party system as an integration, grants it scoped permissions, and C-Bridge issues it a dedicated credential to call C-Bridge's vendor-facing endpoints directly — reading devices, scenes, and energy data, and sending control commands.
See Third-Party Lighting Integration below for the full tutorial, the exact endpoints a partner system calls, and how device exposure (import/export) is controlled.
API Sections
Each of these pages covers one part of the API:
Generating and refreshing tokens/credentials for both API surfaces.
Gateway REST/WebSocket endpoints (devices, scenes, groups, energy, alerts, schedules, system).
Third-Party Lighting Integration
Expose Integration API: connecting lighting/BMS/AV systems, device import & export, and the vendor credential contract.
Vendor API — Endpoint Reference
The exact endpoints an integration partner calls directly, grouped by task — what a third-party system can read and control:
Vendor API — Devices & Control
Discover devices and control them: on/off, brightness, colour temperature, RGB.
List and activate scenes; list and control groups of devices at once.
Vendor API — Monitoring & Status
Verify a credential, read energy data, and check gateway health.
Rate Limiting
The C-Bridge API applies rate limiting to protect system performance. If you exceed the limit, you will receive a 429 response. Implement exponential backoff in integrations that make frequent requests.
Supported Platforms
The C-Bridge REST API and WebSocket interface work with any HTTP/WebSocket-capable platform, including:
- Building management systems — Tridium Niagara, Siemens Desigo, Johnson Controls Metasys
- Control systems — Crestron, AMX, Control4
- SCADA and IoT platforms — Node-RED, Home Assistant, custom Python/Node.js integrations
- Custom dashboards — React, Vue, Angular, or any web framework
Error Handling
All API errors follow a consistent format:
{
"error": "Unauthorized",
"message": "Token expired",
"statusCode": 401
}
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request — check request body or parameters |
| 401 | Unauthorized — missing or expired token |
| 403 | Forbidden — valid token but insufficient permissions |
| 404 | Not found — resource does not exist |
| 429 | Rate limit exceeded — slow down requests |
| 500 | Server error — contact support |
Related Articles
- Third-Party Lighting Integration — Connecting external lighting, BMS, and AV/control systems via the Expose API (see API Sections above)
- BACnet Integration — Alternative integration for BMS-first environments
- System Overview — Architecture and connectivity model
- Troubleshooting Guide — API connectivity issues