Important notice: Changes to the Lytx Surfsight™ API

The following is a list of upcoming changes to the Surfsight API may impact your use of the service.

New Parameter for Get Organization Devices Endpoint (SUR-9249)

We will be adding a new, optional query parameter, telemetryDataSource. This change is being made to improve performance and prevent timeout errors by allowing you to control the source of device location and speed data.

The valid values for this parameter are:

Cache (fallback to the cached values)

Device (a real-time check that uses cellular data)

None (to exclude this data from the response)

This new parameter will affect the latitude, longitude, altitude, and speed properties in the payload. The existing API calls that rely on the previous behavior of the endpoint will have a new default setting after this is implemented. If your application needs real-time data, you must update your integration to explicitly use telemetryDataSource=Device.

Affected Endpoint

get/organizations/{orgId}/devices

Get Organization Devices' Endpoint (SUR-9254)

To improve performance and prevent timeouts, the Get Organization Devices endpoint will soon have a default limit on how many devices it returns.

This means if your organization has more devices than the new limit, your API response will be partial, even if you do not set a limit yourself.

If you need a complete list of devices for a large organization, you will need to implement pagination.

Affected Endpoint

get/organizations/{orgId}/devices

Change to Audit Log API Offset Parameter (VIK-516)

We are updating the "Retrieve organization audit logs" API. Currently, an offset of 'n' mistakenly returns data beginning at position 'n-1'. We are correcting this so that an offset of 'n' will properly return data starting at position 'n'. If no offset is specified, it will default to '0' (all records), aligning with the behavior of our other APIs.

Affected Endpoint

get/audit-logs

Virtual Event cameraId Validation (SUR-9204)

We will be making updates to the API used for creating virtual events, focusing on the cameraId field.

Currently, our "Create Virtual Event" API endpoint lets you include cameraId values that are not actually supported by our system (for example, 42). Even though the API accepts these and returns a 200 success code, these events do not connect to real camera streams. To fix this, we will be implementing strict validation for the cameraId field. If you try to create a virtual event with an unsupported cameraId, the API will reject the request. You will receive a 400 status code and a specific error message explaining the issue. Valid cameraId values are 1, 2, or 51 and higher, corresponding to specific camera types, such as road-facing, in-cabin, or AUX.

Affected Endpoint

post/devices/{imei}/virtual-event

Driver PIN Code Validation (SUR-9198)

We will be updating a V2 API that affects the Driver PIN Code (driverCode) format.

Currently, our V2 APIs allow driverCode updates with unsupported characters (e.g., letters, symbols) or incorrect lengths (not exactly 5 digits), despite system requirements for a 5-digit numeric PIN.

We will be enforcing strict validation for the driverCode field. After this change is implemented, attempts to update a driver with a PIN code that doesn't meet the required 5-digit numeric format will be rejected with a validation error.

Affected Endpoint

This change is relevant for V2 APIs when updating driver entities:

patch/driver

Stricter Validations for Event Settings APIs (SUR-9256)

We will be enforcing stricter validations for our Event settings APIs (Single, Bulk, and Org settings).

After this change, these APIs will not accept unexpected parameters or configurations that are incompatible with specific device types (such as AI-12 vs. AI-14) or firmware versions. Invalid requests will result in an HTTP 400 Bad Request error, and your changes will not be saved.

If your request targets both supported and unsupported devices, the API will still return HTTP 200 OK , but it will only apply changes to the devices that support the configuration.

Please review your API calls to ensure they meet these new rules.

Affected Endpoints

put/devices/{imei}/event-config

put/devices/event-config

post/organizations/{orgId}/event-settings

Device Settings API Validation Changes (SUR-9257)

Our Device Settings APIs (Single, Bulk, and Org settings) will soon enforce new, stricter validations. This breaking change means that attempts to set or update device configurations with unexpected parameters or to apply AI-14 specific settings to AI-12 devices will result in a 400 Bad Request error.

For requests targeting both supported and unsupported devices, the API will still return HTTP 200 OK for the overall request, but it will only apply changes to the devices that support the configuration. Please review your API calls to align with these new validation rules.

Affected Endpoints

put/devices/{imei}/device-config

put/devices/device-config

post/organizations/{orgId}/device-settings

These changes will be implemented in the release scheduled for November 15, 2025. We understand that these changes may cause some disruption to your workflow, and we apologize for any inconvenience. If you have any questions or concerns, please reach out to your Technical Account Manager.

Thank you for your understanding and continued support.

NOTE: Lytx, Inc. owns the LYTX and SURFSIGHT trademarks and other related trademarks and logos. The TM or SM refer to a trademark or service mark, respectively, used by Lytx, Inc. The ® symbol refers to a trademark registered in the USA and elsewhere.