Migrating to the v2 Measurement Stream

The Push API delivers measurement data over WebSocket. Two versions of the measurement message format are available. This guide explains what changes between versions, how to schedule a migration, and how to safely roll back if needed.

For the full REST endpoint reference, see the API Reference.

What Changes in v2?

Queue Subscription

When you subscribe to measurement data, you connect to a queue specific to your username:

Version	WebSocket queue
v1 (current default)	`/queue/{username}/measurements`
v2	`/queue/{username}/measurements-v2`

The v2 queue delivers messages in an updated format. Before scheduling a switch, update your client to connect to the v2 queue and handle the new message structure.

Update your client before scheduling the switch

Your application must be ready to consume from /queue/{username}/measurements-v2 before the switch becomes active. Use the 4-hour transition window (see below) to validate your integration while both queues are live.

Schema Evolution

The v2 message format removes several fields, renames others, and introduces new ones. Review the table below and update your message parsing logic before migrating.

v1 field	v2 field	Change
`uuid`	`uuid`	Unchanged
—	`customer_site`	Added
`device_uuid`	—	Removed
`sensor_uuid`	`sensor_uuid`	Unchanged
`channel_id`	`channel_no`	Renamed — now a channel index rather than a generated identifier
`device_serial_no`	—	Removed
`sensor_serial_no`	`serial_no`	Renamed
`tenant_uuid`	`tenant_uuid`	Unchanged
`timestamp`	`timestamp`	Unchanged
`timestamp_local`	`timestamp_local`	Unchanged
`measurement`	`measurement`	Unchanged
`physical_property_name`	`physical_property_name`	Unchanged
`physical_unit`	`physical_unit`	Unchanged
`physical_extension`	`physical_extension`	Unchanged
—	`model_code`	Added
`processed_at`	`processed_at`	Unchanged

Update your parsing logic before switching

Fields that are removed (device_uuid, device_serial_no) will no longer be present in v2 messages. Fields that are renamed (channel_id → channel_no, sensor_serial_no → serial_no) will arrive under the new name only. Make sure your application does not depend on the old field names before scheduling the switch.

How the Transition Works

When you schedule a version switch, the service moves through three phases automatically:

Phase	When	v1 queue	v2 queue
Before switch	Before your scheduled time	Active	Silent
Transition window	From your scheduled time for 4 hours	Active	Active
After transition	4 hours after your scheduled time	Silent	Active

During the 4-hour transition window, both queues receive messages simultaneously. This gives you time to validate your v2 client against live data before v1 goes silent — without any risk of losing messages.

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'sectionBkgColor': '#fff9c4',
    'altSectionBkgColor': '#37474f'
  },
  'gantt': {
    'barHeight': 40,
    'barPadding': 10,
    'fontSize': 22,
    'sectionFontSize': 18,
    'leftPadding': 220
  }
}}%%
gantt
    title Measurement Queue Transition Timeline
    dateFormat HH:mm
    axisFormat %H:%M
    todayMarker off

    section v1 queue
    Active               : v1, 00:00, 10:00

    section v2 queue
    Active               : active, v2, 06:00, 16:00

    section Key events
    Transition window    : crit, trans, 06:00, 10:00
    start of version switch            : milestone, active, m1, 06:00, 0
    end of version switch (start + 4h) : milestone, crit, m2, 10:00, 0

Configuration refresh

Version settings are picked up within 10 minutes of being saved. Plan your activeFrom time to account for this refresh delay.

Step 1 — Schedule the Switch

Send a POST request to schedule when v2 becomes active. The activeFrom value must be an ISO 8601 UTC timestamp.

POST /api/version-settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "queue": "measurements",
  "version": 2,
  "activeFrom": "2026-07-01T00:00:00Z"
}

A successful response echoes back the scheduled entry:

{
  "queue": "measurements",
  "version": 2,
  "activeFrom": "2026-07-01T00:00:00Z"
}

Possible errors:

Status	Meaning
`400`	Invalid `queue` or `version` value
`422`	Downgrade rejected — you cannot schedule a switch to a version lower than the current active one

Step 2 — Verify Your Settings

You can check all scheduled and historical version entries for a queue at any time:

GET /api/version-settings?queue=measurements
Authorization: Bearer <token>

Example response:

[
  { "queue": "measurements", "version": 1, "activeFrom": "1970-01-01T00:00:00Z" },
  { "queue": "measurements", "version": 2, "activeFrom": "2026-07-01T00:00:00Z" }
]

The entry with activeFrom: 1970-01-01T00:00:00Z is the default baseline and is always present. Any additional entries show scheduled or completed switches.

Step 3 — Validate During the Transition Window

Once your scheduled time arrives, both queues deliver messages for 4 hours. Use this window to:

Connect your updated client to /queue/{username}/measurements-v2.
Confirm messages are received and parsed correctly.
Run any integration tests against live data.

After the 4-hour window closes, only v2 receives messages and v1 goes silent.

Cancelling a Scheduled Switch

If you need to postpone or cancel before the switch becomes active, delete the upcoming entry:

DELETE /api/version-settings/upcoming?queue=measurements
Authorization: Bearer <token>

This removes any future-dated entries. Entries from completed switches are kept for audit purposes.

Cancelling a Switch Already in Transition

If the transition window has already started and you need to abort, pass deleteTransition=true:

DELETE /api/version-settings/upcoming?queue=measurements&deleteTransition=true
Authorization: Bearer <token>

Downgrading is not supported

Once a v2 switch has fully completed (transition window closed), it cannot be undone. Only cancel or abort before the 4-hour window ends.

Both requests return 204 No Content on success.

Summary of What Gets Deleted

Entry type	Default `DELETE`	`DELETE` with `deleteTransition=true`
Default baseline (`1970-01-01`)	Kept	Kept
Completed switches	Kept	Kept
In-progress transition	Kept	Deleted
Future scheduled entry	Deleted	Deleted

Frequently Asked Questions

Will I lose any messages during the migration? No — during the 4-hour transition window both queues deliver messages simultaneously, so no data is lost regardless of when you switch your client.

How much lead time do I need when scheduling activeFrom? Version settings are refreshed every 10 minutes, so set activeFrom at least 10 minutes in the future to ensure the switch takes effect on time.

Can I subscribe to v2 before scheduling the switch to test it? Yes — you can connect to /queue/{username}/measurements-v2 at any time, but it will only start delivering messages once your transition window begins.

What happens if I schedule a switch and then want to change the date? Delete the upcoming entry first (DELETE /api/version-settings/upcoming) and then schedule a new one with your preferred activeFrom date.

What happens if I miss the transition window? If you do not validate during the window, v1 simply goes silent after 4 hours. Messages are not lost — they are delivered on v2 from the moment the transition starts. If your application is not ready at that point, please contact our support team for assistance.

Can I abort a switch that is already in progress? Yes — as long as the 4-hour transition window has not closed yet. Send DELETE /api/version-settings/upcoming?queue=measurements&deleteTransition=true to cancel the in-progress transition. Once the window closes, the switch is permanent and cannot be undone. If you are in that situation, please contact our support team for assistance.

Can I go back to v1 after the switch completes? No. Downgrading to a lower version is not supported. If you need more time, cancel the scheduled switch before it completes and reschedule for a later date. If the switch has already completed and you are facing issues, please contact our support team for assistance.