> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telluspowergroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time telemetry stream (WebSocket)

> **WebSocket endpoint.** Connect to `wss://<base>/v1/operator/stream?devices=<comma-separated device_ids>`
with the access token in the `Authorization` header during the WebSocket
handshake (or as a `?token=...` query parameter).

The server pushes JSON telemetry frames (see `TelemetryFrame` schema)
for the subscribed device IDs at the platform's configured cadence.

This endpoint cannot be tested via the standard "Try it" console — use
a WebSocket client. The schema below describes one frame the server emits.




## OpenAPI

````yaml /api-reference/openapi.json get /operator/stream
openapi: 3.1.0
info:
  title: Tellus Open Platform API
  version: 1.3.0
  summary: Charger-platform integration API for CPMS, EMS, aggregators, and chargers.
  description: >
    The Tellus Open Platform API enables Charging Point Management Systems
    (CPMS),

    Energy Management Systems (EMS), aggregators and chargers themselves to
    integrate

    with the Tellus charging-platform infrastructure.


    The API is divided into three logical surfaces:


    - **Operator-side API** (`/v1/operator/...`) — used by CPMS, EMS, and
    aggregators
      to query the fleet, retrieve charging records, control chargers, schedule charging,
      issue load-flexibility commands, and subscribe to a real-time telemetry WebSocket.
    - **Charger-side API** (`/v1/device/...`) — used by chargers themselves for
      registration, heartbeat, telemetry, event reporting, charging-record upload,
      command fetching (long-polling), command-status reporting, and firmware-upgrade
      status.
    - **Operator-to-operator interop (legacy)** — an older roaming-style
    interface
      (PascalCase, PUT-based) used for data exchange between operator platforms,
      modelled after China's national charging-interop standard. Most modern partners
      should integrate via the Operator-side API instead.

    All requests use HTTPS (TLS 1.2 or higher). Plain HTTP is not supported.

    All bodies are `application/json`. Timestamps are ISO 8601 UTC.

    Energy is in kWh, power in kW, current in A, voltage in V, temperature in
    °C,

    and SOC is an integer percentage 0–100.


    Optional request signing using HMAC-SHA256 is supported for high-security

    operations (see §2.2.4 of the v1.3 specification).
  contact:
    name: Tellus Power — Platform Team
    url: https://www.telluspowergroup.com
  license:
    name: Proprietary — Tellus Power Group
servers:
  - url: https://api.telluspower.example.com/v1
    description: >
      Production (HOSTNAME PENDING).

      The v1.3 specification uses `api.chargingplatform.com` as a placeholder;
      the

      real production hostname has not yet been confirmed by the developer team.
  - url: https://api-test.telluspower.example.com/v1
    description: |
      Test / Sandbox (HOSTNAME PENDING). To be confirmed by the developer team.
security: []
tags:
  - name: Operator — Authentication
    description: OAuth2 client-credentials grant for CPMS / EMS / Aggregator integrations.
  - name: Operator — Sites & Devices
    description: >-
      Read-only resource queries — sites accessible to the authenticated client,
      and per-device detail with connector states.
  - name: Operator — Remote Control
    description: >-
      Initiate charging, stop charging, V2G discharge, and set charging
      schedules remotely.
  - name: Operator — Charging Records
    description: Historical session data (CDR — Charging Detail Records).
  - name: Operator — Energy & Flexibility
    description: >-
      Aggregated energy time-series and load-flexibility / demand-response
      control.
  - name: Operator — Commands
    description: Track execution of issued commands.
  - name: Operator — Telemetry Stream (WebSocket)
    description: >-
      Real-time telemetry subscription via WebSocket. Documented here for
      reference; the connection is established outside the OpenAPI
      request/response model.
  - name: Charger — Provisioning
    description: First-time device registration and access-token issuance.
  - name: Charger — Reporting
    description: Heartbeat, real-time telemetry, event reporting, charging-record upload.
  - name: Charger — Commands
    description: Long-polling for pending commands and reporting their execution status.
  - name: Charger — Firmware
    description: Firmware upgrade status reporting.
  - name: Operator-to-operator (legacy interop)
    description: |
      Older roaming-style interface (PascalCase fields, PUT methods) used for
      data exchange between operator platforms. Modern partners should normally
      integrate via the Operator-side API instead.
externalDocs:
  description: >-
    Tellus Power developer documentation — guides, diagnostics, runbooks, and
    proposed API extensions
  url: https://developers.telluspowergroup.com
paths:
  /operator/stream:
    get:
      tags:
        - Operator — Telemetry Stream (WebSocket)
      summary: Real-time telemetry stream (WebSocket)
      description: >
        **WebSocket endpoint.** Connect to
        `wss://<base>/v1/operator/stream?devices=<comma-separated device_ids>`

        with the access token in the `Authorization` header during the WebSocket

        handshake (or as a `?token=...` query parameter).


        The server pushes JSON telemetry frames (see `TelemetryFrame` schema)

        for the subscribed device IDs at the platform's configured cadence.


        This endpoint cannot be tested via the standard "Try it" console — use

        a WebSocket client. The schema below describes one frame the server
        emits.
      parameters:
        - name: devices
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated list of device IDs to subscribe to.
      responses:
        '101':
          description: |
            WebSocket handshake successful. Subsequent traffic is JSON-encoded
            `TelemetryFrame` messages, one per device per cadence interval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryFrame'
components:
  schemas:
    TelemetryFrame:
      type: object
      description: >
        A single telemetry frame pushed by the operator-side WebSocket telemetry

        stream (§13.2.7). The server emits one frame per device on a regular
        cadence

        (typically every few seconds) for the device IDs the client subscribed
        to

        when establishing the WebSocket connection.
      required:
        - device_id
        - timestamp
        - connectors
      properties:
        device_id:
          type: string
        timestamp:
          type: string
          format: date-time
        connectors:
          type: array
          items:
            type: object
            properties:
              connector_id:
                type: integer
              state:
                $ref: '#/components/schemas/ConnectorState'
              power:
                type: number
              energy_delivered:
                type: number
              soc:
                type: integer
                minimum: 0
                maximum: 100
      example:
        device_id: dvc_a1b2c3d4e5f6
        timestamp: '2025-03-15T11:05:00Z'
        connectors:
          - connector_id: 1
            state: charging
            power: 6.9
            energy_delivered: 13.1
            soc: 58
    ConnectorState:
      type: string
      enum:
        - idle
        - charging
        - discharging
        - fault
        - unavailable
      description: Current state of the connector.

````