Lightbug Documentation

Appearance

WebSocket​

GET
/chasm/ws

Establishes a WebSocket connection to manage multiple device subscriptions dynamically

🧪 Alpha

This endpoint is alpha, and may change while being tested.

This documentation page also does not lend itself to a websocket endpoint, this is not a GET. Please see schema descriptions and various response codes for detailed examples of messages.

Supports subscribe/unsubscribe/out message types

Authorizations​

ApiKeyAuth

API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See Authentication for more details.

Type
API Key (header: Authorization)
Example"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Parameters​

Query Parameters

devices

Initial devices to subscribe to (comma-separated)

Type
string
encoding

Message encoding format (json|hex|decimal|base64)

Type
string
Default
"json"

Request Body​

application/json
JSON
{
  
"data": "ff 00 01",
  
"device": "device1",
  
"encoding": "hex",
  
"messageId": "msg-789",
  
"type": "out"
}

Request example

Responses​

Subscription confirmed

application/json
JSON
{
  
"device": "device1",
  
"messageId": "sub-456",
  
"timestamp": "2024-01-10T15:30:45.123Z",
  
"type": "subscribed"
}
Try this endpoint

Playground​

Authorization
Variables
Key
Value
Body

OpenAPI definition ​

References are expanded below, except recursive definitions and references with sibling fields. Documentation overrides are included. Full original OpenAPI spec (JSON).

View endpoint OpenAPI definition
yaml
info:
  title: Lightbug API
  version: '2'
externalDocs:
  description: ''
  url: ''
openapi: 3.1.0
servers:
  - url: https://api.lightbug.cloud/v2
security:
  - ApiKeyAuth: []
tags: []
paths:
  /chasm/ws:
    get:
      description: |-
        Establishes a WebSocket connection to manage multiple device subscriptions dynamically

        <div class="custom-block alpha">
        <p class="custom-block-title">🧪 Alpha</p>
        This endpoint is alpha, and may change while being tested.

        This documentation page also does not lend itself to a websocket endpoint, this is not a GET. Please see schema descriptions and various response codes for detailed examples of messages.
        </div>

        Supports subscribe/unsubscribe/out message types
      parameters:
        - description: Initial devices to subscribe to (comma-separated)
          in: query
          name: devices
          schema:
            type: string
        - description: Message encoding format (json|hex|decimal|base64)
          in: query
          name: encoding
          schema:
            default: json
            type: string
requestBody:
yaml
        content:
          application/json:
            schema:
              properties:
                data:
                  description: Message data in specified encoding
                  example: ff 00 01
                  type: string
                device:
                  description: Target device identifier or ID (required)
                  example: device1
                  type: string
                encoding:
                  description: 'Encoding format: hex, decimal, base64, json'
                  example: hex
                  type: string
                messageId:
                  description: Client-provided message ID for tracking
                  example: msg-789
                  type: string
                type:
                  description: '"out" to send message to device'
                  example: out
                  type: string
              type: object
        description: Send message to device
        required: true
yaml
      responses:
'101':
yaml
          content:
            application/json:
              schema:
                properties:
                  device:
                    description: Device identifier that was subscribed to
                    example: device1
                    type: string
                  messageId:
                    description: Echoes the messageId from subscribe request
                    example: sub-456
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:45.123Z'
                    type: string
                  type:
                    description: '"subscribed" - subscription confirmed'
                    example: subscribed
                    type: string
                type: object
          description: Subscription confirmed
'102':
yaml
          content:
            application/json:
              schema:
                properties:
                  device:
                    description: Device ID that was unsubscribed from
                    example: '2'
                    type: string
                  messageId:
                    description: Echoes the messageId from unsubscribe request
                    example: unsub-101
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:47.345Z'
                    type: string
                  type:
                    description: '"unsubscribed" - unsubscription confirmed'
                    example: unsubscribed
                    type: string
                type: object
          description: Unsubscription confirmed
'103':
yaml
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: Message data in requested encoding
                    example: 7b 22 74 65 6d 70 22 3a 32 35 7d
                  device:
                    description: Device ID that sent the message
                    example: '1'
                    type: string
                  encoding:
                    description: Encoding format
                    example: hex
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:46.234Z'
                    type: string
                  type:
                    description: '"in" - message from device'
                    example: in
                    type: string
                type: object
          description: Incoming message from subscribed device
'104':
yaml
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: Server event data
                  device:
                    description: Device ID that generated the event
                    example: '2'
                    type: string
                  encoding:
                    description: Encoding format
                    example: hex
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:47.345Z'
                    type: string
                  type:
                    description: '"srv" - server event'
                    example: srv
                    type: string
                type: object
          description: Server event from subscribed device
'105':
yaml
          content:
            application/json:
              schema:
                properties:
                  messageId:
                    description: Echoes the messageId from out request
                    example: msg-789
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:46.250Z'
                    type: string
                  type:
                    description: '"ack" - acknowledgment'
                    example: ack
                    type: string
                type: object
          description: Acknowledgment of sent message
'106':
yaml
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: Error description
                    example: 'device not found: invalid-device'
                    type: string
                  messageId:
                    description: MessageId from request if available
                    example: sub-456
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:48.456Z'
                    type: string
                  type:
                    description: '"error" - error response'
                    example: error
                    type: string
                type: object
          description: Error response
yaml
      security:
        - ApiKeyAuth: []
      summary: WebSocket
      tags:
        - chasm
      operationId: get-chasm-ws
components:
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See <a href='/apis/authentication'>Authentication</a> for more details.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...