Developer Platform

Build on the
Connection Platform

Two powerful APIs — a RESTful server API for device management and communication orchestration, and a low-level CBBP protocol for direct badge control.

REST API ReferenceCBBP Protocol
OpenAPI 3.0JSON / RESTBluetooth + WiFiWebhook Support
Connection Studio
Explorer
examples
send_command.http
response.json
list_devices.http
webhooks.http
src
docs
send_command.http
response.json
# Send a CBBP command via the server
POST /api/v1/devices/{uuid}/cbbp

{
  "command": "speak",
  "object": {
    "text": "Shift starts in 5 minutes",
    "volume": 85,
    "language": "en-US"
  }
}

# Response
{
  "result": 0,
  "detail": "ok"
}
main
HTTPUTF-8Ln 2, Col 1

REST API

Full device lifecycle management — provisioning, configuration, firmware, communications, and analytics — over standard HTTPS.

Explore REST API →

CBBP Protocol

Com Badge Basic Protocol — a JSON command protocol for direct device control over Bluetooth (app), WiFi (server proxy), or local dispatch.

Explore CBBP →

Webhooks

Subscribe to real-time device events — communications, status changes, location updates — delivered as HTTP POST payloads to your endpoint.

Explore Webhooks →

Early Access: The Connection API is currently available by special request to select partners. Contact us to apply for access.

Pro or Plus plan required: Badges must be on the Pro or Plus plan to be controlled via the API.

Getting Started

Authentication

The Connection API uses Bearer token authentication. All requests must include a valid JWT access token in the Authorization header.

Obtain a token

POST your credentials to the auth endpoint. You'll receive a short-lived access_token and a longer-lived refresh_token.

Use the token

Include the token in every request:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Request
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Response 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Base URL & Versioning

All API endpoints are versioned under /api/v1/. The base URL depends on your deployment.

For cloud-hosted deployments, use the regional endpoint assigned to your organization. For on-premises Server deployments, use your server's hostname.

EnvironmentBase URL
Cloud (US)https://beta.connection.app/api/v1
On-Premiseshttps://<your-server>/api/v1
Content-Type
All request and response bodies use application/json. Include Content-Type: application/json on requests with a body.

Errors & Status Codes

The API uses standard HTTP status codes. Error responses include a machine-readable code and human-readable message.

StatusMeaning
200Success
201Created
400Bad Request — invalid parameters
401Unauthorized — missing or expired token
403Forbidden — insufficient permissions
404Not Found
500Internal Server Error
Error Response
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
REST API

REST API Overview

The Connection Server REST API provides full programmatic access to your device fleet, communications infrastructure, and analytics. It follows RESTful conventions with JSON request/response bodies.

API Authentication
Users
Devices
Channels
Communication
Audio Bridge
Conversations
Content
Locations
Push Notifications
Storage
Bulk Operations
Date & Time

Authentication

Token-based authentication. Login returns a token that must be sent as Authorization: Token <token> on all subsequent requests.

POST/api/v1/loginAuthenticate a user and receive an auth token
POST/api/v1/login-deviceAuthenticate a device by UUID and MAC address
POST/api/v1/logoutInvalidate the current session token

Users

Create and manage user accounts. The GET /users/user endpoint returns the currently authenticated user.

GET/api/v1/users/userRetrieve the currently logged-in user profile
POST/api/v1/users/userCreate a new user account
PATCH/api/v1/users/user/{uuid}Update user profile (e.g. profile image)

Devices

List and inspect devices, manage user–device associations, read and write per-device settings and status, handle firmware and storage images, and receive logs and crash reports.

GET/api/v1/devices/deviceList all devices
GET/api/v1/devices/device/{uuid}Get detailed device info including firmware and settings
PUT/api/v1/devices/association/{uuid}Update the association between a user and a device
DELETE/api/v1/devices/association/{uuid}Remove user–device association and stored settings
GET/api/v1/devices/device/{device_uuid}/settingsList settings stored for a device
POST/api/v1/devices/device/{device_uuid}/settingsSave device-specific settings
GET/api/v1/devices/device/{device_uuid}/statusGet device status (connectivity, battery, sensors, audio state)
POST/api/v1/devices/device/{device_uuid}/statusPost device status from the device
GET/api/v1/devices/device/{device_uuid}/contextList context values stored for a device
POST/api/v1/devices/device/{device_uuid}/ingest-contextReceive GPS + WiFi context from the device
GET/api/v1/devices/firmwareList firmware releases compatible with a given hardware/software version
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchFetch a firmware image in chunks
GET/api/v1/devices/languageList supported device languages and voices
GET/api/v1/devices/storage_imageDownload customized device storage image for a locale
POST/api/v1/devices/logReceive a log file from a device
POST/api/v1/devices/crashReceive a core dump from a device
PATCH/api/v1/devices/crash/{uuid}Update a crash record

CBBP Proxy

Send any CBBP command to a device through the server. The server relays the command over the device's WiFi connection and returns the device response. The outgoing-make response also embeds a CBBPMessage that the device executes immediately.

POST/api/v1/devices/device/{device_uuid}/cbbpSend a CBBP command to a device via the server
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Retrieve the status and response of a previously sent CBBP command

The request body is a CBBP command envelope. The stored CBBPCommand object tracks delivery status: UNSET → SENT → RECEIVED or TIMED_OUT.

Poll GET /cbbp/ to check whether the device received and responded to the command.
Request — outgoingMessage
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Response — CBBPCommand status
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Channels

Channels are the core communication primitives. Types include ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService, and ChannelRecorder.

GET/api/v1/channels/channelList channels, optionally filtered by object_type
POST/api/v1/channels/channelCreate a channel (ChannelGroup, ChannelContact, or ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Update a ChannelGroup or ChannelContact
DELETE/api/v1/channels/channel/{uuid}Delete a channel
DELETE/api/v1/channels/{uuid}Delete a ChannelGroup
DELETE/api/v1/channels/by-type/{channelType}Delete all channels of a given type (currently ChannelContact)
GET/api/v1/channels/associationList channel associations for the current user
POST/api/v1/channels/associationRequest an association with a channel
PATCH/api/v1/channels/association/{uuid}Accept, decline, or update association settings
DELETE/api/v1/channels/association/{uuid}Remove an association with a channel
GET/api/v1/channels/historyGet paginated channel access history for the current user
POST/api/v1/channels/historyCreate a channel history entry
GET/api/v1/channels/searchSearch channels by query string and optional type filter

Communication

Initiate and manage active communication sessions — outgoing calls, VCP, recording, and content streaming. The outgoing-make response includes a CBBPMessage that the device acts on immediately.

POST/api/v1/communicate/outgoing-makeInitiate an outgoing channel to a ChannelPeople, ChannelGroup, ChannelContact, or ChannelContactNumber
POST/api/v1/communicate/incoming-acceptanceAccept or decline an incoming channel join request
POST/api/v1/communicate/closeClose the current active communication channel on a device
POST/api/v1/communicate/vcp-activateInitiate Voice Communication Protocol (VCP) on the server and device
POST/api/v1/communicate/vcp-deactivateDeactivate VCP, returning to any previous channel
POST/api/v1/communicate/recording-activateActivate recording mode on the server and device
POST/api/v1/communicate/content-startOpen a streaming channel to audio content
POST/api/v1/communicate/request-vocalizationGenerate TTS audio for the given text, optionally translating it

Audio Bridge

Access recorded bridge conversations including full transcripts, participant lists, and AI-generated summaries. Supports multiple summary templates (meeting notes, class notes, healthcare, etc.) and TTS audio generation for summaries.

GET/api/v1/bridge/conversationsList all bridge conversations
GET/api/v1/bridge/conversations/{uuid}Get a detailed conversation including transcript, participants, and summary
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGenerate an AI summary for a conversation
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGenerate audio for a conversation summary

Conversations

AI-powered conversation sessions using ChatGPT, Gemini, or the native engine. Supports multiple personas (Doctor, Tutor, Mechanic, etc.) and paginated message history.

GET/api/v1/conversations/conversationList AI generator sessions, filterable by persona and tool
POST/api/v1/conversations/conversationCreate a new AI conversation session
GET/api/v1/conversations/conversation/{uuid}Retrieve a conversation session with optional summary/away update
DELETE/api/v1/conversations/conversation/{uuid}Delete a conversation session
GET/api/v1/conversations/conversation/{uuid}/messagesList messages in a conversation
POST/api/v1/conversations/conversation/{uuid}/messagesAdd a user message and receive an AI reply

Content

Browse and play streaming audio content on devices. Content is organized in a category tree; popular content can be filtered by city, region, or country.

GET/api/v1/content/categoriesGet a tree of content categories
GET/api/v1/content/contentList available content within a category
GET/api/v1/content/popularList popular content for a given city, region, or country

Locations

Resolve geographic coordinates to a structured city, region, and country object. Used by devices when ingesting context.

POST/api/v1/location/determineResolve a latitude/longitude to city, region, and country

Push Notifications

Register a mobile app to receive FCM push notifications. Supports iOS, Android, and web targets.

POST/api/v1/push-notifications/pushRegister a mobile app for FCM push notifications (iOS, Android, web)

Storage

Download files stored on model objects, and run image background removal (returns base64-encoded result).

GET/api/v1/storage/retrieve/{path}Download a stored file by path
POST/api/v1/storage/remove-backgroundRemove the background from an image (returns base64)

Bulk Operations

Execute multiple API operations in a single HTTP request. Pass single_transaction=true to wrap all operations in one atomic transaction — a failure on any item rolls back the entire batch.

POST/api/v1/bulkExecute multiple API operations in a single request, optionally as a single atomic transaction

Date & Time

Returns the current server date and time in GMT+0. Does not require authentication. Used by devices to sync their internal clock.

GET/api/v1/current-datetimeReturn the current date and time in GMT+0
CBBP Protocol

Com Badge Basic Protocol

CBBP is a lightweight JSON command protocol for direct interaction with Connection badges. It gives you full control over every hardware and software function on the device.

Message Format

Every CBBP interaction consists of a command message sent to the device and a result message returned by the device.

The object field in both request and response carries command-specific data and may be omitted when not needed.

Full protocol documentation is available to registered partners. Contact your Connection business representative or reach out to developer@connectionbadge.com to request access to the complete CBBP command reference, including full request/response schemas, error codes, and integration guides.
Command Message
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Result Message
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Transport

CBBP messages can be delivered to a badge through three different transports depending on your integration architecture.

Bluetooth (App)

Send CBBP commands directly from a mobile app over BLE. Requires the device to be paired and within range.

Mobile SDK

WiFi or Bluetooth via Server

Proxy CBBP through the REST API — POST /devices//cbbp. The server automatically routes to the device over WiFi or Bluetooth depending on how the badge is connected. Most common for backend integrations.

REST API

Internal Dispatch

On-device or inter-process CBBP dispatch. Used by the badge firmware to route commands between internal subsystems.

Firmware Only

Power Commands

Control device power state — sleep, wake, reboot, and factory reset.

PowerRebootReboot the device immediately.
PowerDeepsleepEnter deep sleep (low-power) mode.
FactoryResetErase all configuration and reset to factory defaults.

WiFi Commands

Configure wireless networks, scan for APs, check connection status, and manage saved credentials.

WiFiScanScan for available WiFi access points.
WiFiAPTestTest connectivity to a specific WiFi access point.
WiFiAPJoinJoin a WiFi access point with the provided credentials.

Bluetooth Commands

Control BLE advertising, pairing, and badge-to-badge communication.

BTScanBTScan for classic Bluetooth devices.
BTScanBLEScan for BLE devices.
DeviceBLEServiceAvailableMark the BLE service as available.
DeviceBLEServiceUnavailableMark the BLE service as unavailable.
DeviceBLEActiveSet the BLE radio to active state.
DeviceBLEIdleSet the BLE radio to idle state.
DeviceBLEAdvChannelAddAdd a channel to the BLE advertising payload.
DeviceBTScanInitiate a Bluetooth device scan.
DeviceBTA2DStartStart Bluetooth A2DP audio streaming.
DeviceBTA2DEndEnd Bluetooth A2DP audio streaming.
DeviceBTNativeAssistStartStart the native Bluetooth voice assistant.
DeviceBTNativeAssistEndEnd the native Bluetooth voice assistant.

Settings Commands

Read and write device configuration — display name, time zone, language, and feature flags.

SettingsListGetRetrieve all settings as a key-value list.
SettingsListSetWrite multiple settings values at once.
SettingsGetGet the value of a single setting by key.
SettingsSetSet the value of a single setting.
SettingsSendPush current settings to the server.
SettingsClearClear specific setting values.
SettingsEraseErase all stored settings.

Firmware Commands

Trigger OTA firmware updates, check update status, and query the current firmware version on the device.

FirmwareCheckCheck whether a firmware update is available.
FirmwareUpdateBegin an OTA firmware update.
FirmwareValidateValidate the integrity of a downloaded firmware image.

Device Commands

Device lifecycle, authentication, configuration, logging, status, and hardware control.

NoOpNo-operation / keep-alive.
TestBasic connectivity test.
DeviceDateTimeGet or set the device date and time.
DeviceAuthenticateAuthenticate the device with the server.
DeviceConfigureApply a configuration payload to the device.
DevicePostConnectionTasksRun post-connection initialization tasks.
DeviceStorageLoadLoad data from on-device storage.
DeviceLoadCustomAudioLoad custom audio files onto the device.
DeviceCoredumpSendUpload a crash core dump to the server.
DeviceAttachAttach the device to a server session.
DeviceDetachDetach the device from a server session.
DeviceLogSendUpload device logs to the server.
DeviceConnectionTestTest server connectivity.
DeviceStatusSendPush device status to the server.
DeviceStatusGetGet current device status.
DeviceInteractionTrigger a device interaction event.
DeviceSetAPIHostSet the API server host.
DeviceTestMicsRun a microphone self-test.
HardwareI2CCommandSend a raw I2C command to a hardware peripheral.

Communication Commands

Initiate calls, send messages, manage active communication sessions, and control recording.

CommunicateChannelJoinJoin a communication channel.
CommunicateChannelLeaveLeave a communication channel.
CommunicateChannelChangeSwitch to a different channel.
CommunicateChannelCloseClose a communication channel.
CommunicateReceiveIncomingNotify the device of an incoming communication.
CommunicateRequestOutgoingRequest an outgoing communication.
CommunicateVCPActivateActivate the Voice Communication Protocol session.
CommunicateVCPDeactivateDeactivate the VCP session.
CommunicateRecordingActivateStart recording the active communication.
CommunicateIncomingAcceptAccept an incoming call.
CommunicateIncomingRejectReject an incoming call.
CommunicateHFPCallStartStart a Bluetooth HFP phone call.
CommunicateHFPCallEndEnd a Bluetooth HFP phone call.
CommunicateContentStartBegin streaming audio content to the device.
CommunicateContentStopStop streaming audio content.
SocketReceiveStatusReceive a WebSocket status update.

Audio Commands

Control speaker volume, microphone gain, audio profiles, and text-to-speech playback.

AudioPlayStoragePlay an audio file from on-device storage.
AudioPlayContentPlay streamed audio content.
AudioSetVolumeSet the speaker output volume.

LED Commands

Set LED color, brightness, and animation patterns on the badge indicator light.

DeviceIlluminationSetSet the LED color and illumination pattern.

Internal Commands

Internal dispatch commands used for context delivery, channel history, vocalization, and audio decoding.

InternalSendContextSend context data to the internal context handler.
InternalSendChannelHistorySend channel history to the internal handler.
InternalRequestVocalizationRequest text-to-speech vocalization internally.
InternalHandleVocalizationRTPHandle an incoming vocalization RTP stream.
InternalDecodeAudioDecode an incoming audio stream.

Mobile Commands

Commands for coordinating the badge with a paired mobile app — push notifications, app state sync, and deep linking.

MobileServiceStatusReport mobile service status to the device. (Mobile → Device)
MobileSocketOpenInstruct the mobile app to open a WebSocket connection. (Device → Mobile)
MobileSocketCloseInstruct the mobile app to close a WebSocket connection. (Device → Mobile)
MobileSocketStatusReport WebSocket status to the mobile app. (Device → Mobile)
MobileReceiveStatusReport receive status to the mobile app. (Device → Mobile)
MobileSocketUpdateSend a WebSocket data update to the mobile app. (Device → Mobile)
MobilePTTStartNotify the mobile app that PTT transmission has started. (Device → Mobile)
MobilePTTStopNotify the mobile app that PTT transmission has ended. (Device → Mobile)
MobileContextSetSet context data on the mobile app. (Device → Mobile)
MobileEchoEcho command for testing mobile connectivity. (Device → Mobile)

Ready to build?

Join the Connection developer community and get access to sandbox devices, SDKs, and dedicated support.

Contact Us