Changelog: Litmus Edge Manager 2.31.x to 3.0.x

You are at https://api.litmus.io/reference/changelog-lem.md. Parent: https://api.litmus.io/agents.md (product router: /lem/agents.md) What changed in the LEM API between 2.31.x and 3.0.x. This tree documents 3.0.x only; 2.31.x endpoints live only in the full collection JSON.

This document describes the API differences between LitmusEdge Manager 2.31.x and 3.0.x, for installations and integrations upgrading from 2.31.x. Every entry was checked against the OpenAPI specifications of both releases and, where it changes behaviour, against live 2.31.x and 3.0.x instances. Changes are grouped by the folders of this collection; anything not listed is unchanged.

Authentication is unchanged. Requests still carry the LEM API token in the X-AuthToken header; the main API is served from /api/v1/ and the Admin Console API from /admin/v1/ on port 8446. Marketplace Catalog endpoints under /mpcs/ take the token in the Authorization header and on 3.0.x also accept X-AuthToken. The LEM web UI now signs in through Keycloak (/auth on the LEM host, realm standalone); this changes how people log in to the UI, not how API clients authenticate.

Breaking changes at a glance

Summary

Deprecations

These still respond in 3.0.x but should not be used in new integrations.

Companies

New

GET /api/v1/company/list/paged returns the companies available to the caller page by page, and GET /api/v1/project/paged the projects of a company. The unpaged lists are unchanged.

Edge Lifecycle Management

Breaking: Sites removed

Every Sites endpoint (GET /site/list/{projectId}, GET /site/{id}, POST /site, DELETE /site/{id}, POST /site/image/{siteId}, DELETE /site/image/{siteId}) answers 410 Gone with {"code":"E","message":"LEM Sites feature has been removed"}. There is no replacement.

Breaking: template friendlyName is required

Every template create, upload and update now requires a friendlyName:

Without it, upload answers 409 (Required request parameter 'friendlyName' ... is not present) and update answers 400 (Friendly name is required). In CreateTemplateRequest, templateDescription is no longer required. Upload also accepts an optional userEncryptionKey.

Breaking: POST /api/v1/template/apply removed

The operation is gone in 3.0.x (it was not part of the 2.31.x documentation). The async-task API lists TEMPLATE_APPLY as a task type, and POST /api/v1/template/preview reports what an apply would change.

Breaking: template objects lost stat

Template objects no longer carry stat. They gain friendlyName, version, createdBy, updatedAt and updatedBy.

Changed (non-breaking)

• GET /api/v1/template/list accepts optional scope, version, templateName (repeatable), parameterized, order, createdFrom, createdTo, updatedFrom and updatedTo.
• GET /api/v1/logs/company/{companyName} (Get System Events) accepts optional action, module and origin filters; action-log records gain action, category, categoryLabel, module, origin, sourceIp, details, errorCode and subtaskId.
• GET /api/v1/device-certificates accepts an optional caCertSynced filter; GET /api/v1/project/incident/{projectId} accepts sortBy; POST /api/v1/backup/get accepts kind, and POST /api/v1/backup/init-restore now starts an EDGE_BACKUP_RESTORE async task and returns its ID.
• Async-task type filters accept new values, including DIGITAL_TWINS_HIERARCHY_UPDATE, DIGITAL_TWINS_INSTANCE_CREATE, EDGE_BACKUP_RESTORE, EXPORT_DEVICE_TEMPLATE and TEMPLATE_SOLUTION_APPLY; GET /api/v1/async-task/task-types lists them.
• Alerts and incidents gain scope GLOBAL and severity CRITICAL; incidents carry devicePrettyName and triggerDescription.
• Devices carry haEnabled, haRole, haPairDeviceId and labels; GET /api/v1/device accepts labels in its tag filter (key:value).
• Projects carry exportTemplateWithBackup and incidentResolutionSettings.

New

Digital Twins/Asset Management

New

Asset Hierarchy. Templates with ordered levels (create, update, duplicate, activate, delete drafts, add / move / remove levels, bulk-update levels), nodes (create, read with depth, list roots, full tree, update, move, delete with force), CSV import and export, all under /api/v1/assets/hierarchy/{companyName}/....

Hierarchy permissions. Grant a user edit access to a branch (POST .../node/{id}/permissions), read a node's access and the caller's capability, revoke grants, and list hierarchy operators.

Asset Hub. Connect to Litmus Asset Hub, browse the catalog and an asset's versions, import, update and delete imported assets, and trigger a sync, under /api/v1/asset-hub/....

Digital Twins. Dynamic attributes accept optional NestedModelID, NestedModelName, NestedInstanceID, NestedInstanceName, TopicExpressionConverted and Transformation in POST /api/v1/dt2/dynamic-attribute and POST /api/v1/dt2/model/complete/{companyName}. POST /api/v1/dt2/{companyName}/instances/parse-csv parses an instances CSV.

Admin Console APIs

Breaking: Docker Pull takes a JSON body

POST /admin/v1/registry/image/upload-remote no longer reads externalUrl, externalName, externalTag, internalName, internalTag, user and password from the query string. Send them in a JSON body; externalName is required. A 2.31.x-style request is rejected with 400 (Required request body is missing).

Breaking: template friendlyName is required

POST /admin/v1/template (update, UpdateTemplateRequest), POST /admin/v1/template/upload and PUT /admin/v1/template/upload-zip require friendlyName. Admin template upload also accepts deviceId and userEncryptionKey, and companyName / projectId became optional. Template objects no longer carry stat.

Deprecated

GET /admin/v1/logs and GET /admin/v1/logs/contexts; use GET /admin/v1/logs/v2 and GET /admin/v1/logs/v2/categories.

Changed (non-breaking)

GET /admin/v1/template/list gains the same filters as the main API; the instance alert trigger scopeType filter accepts GLOBAL; GET /admin/v1/licenses2/type returns licenseCoreName.

New

Upgrade checklist

1. Remove Sites calls; every Sites endpoint answers 410 Gone.
2. Send friendlyName on every template create, upload and update, in the main API and the Admin Console.
3. Move Docker Pull parameters from the query string into a JSON body.
4. Stop calling POST /api/v1/template/apply and stop reading stat on template objects.
5. Move from GET /admin/v1/logs and /logs/contexts to /logs/v2 and /logs/v2/categories.
6. Handle the new enum values: alert scope GLOBAL, severity CRITICAL, and the new async-task types.