Litmus Unify (UNS) API Documentation

Litmus Unify is the MQTT-based Unified Namespace: a central data fabric where every edge, application, and consumer in a plant shares one organized topic tree. The API is GraphQL only (46 endpoints) and covers everything an integrator needs: provisioning broker accounts with access rules, shaping the namespace, configuring Kafka and connector data egress, and managing node backup and upgrades.

Product versions

This documentation covers Litmus Unify 2.0.x (current). The prior product was named Litmus UNS (versions <v2.0.0) and has a different shape: account operations sat in a separate "Security" folder, server config lived under "Tools", several operations were renamed, and the connectors and node-configuration (backup/upgrade) operations did not exist yet. Each component page carries a version map noting which of its operations also exist in <v2.0.0 and how they differ. Full <v2.0.0 request bodies remain in the collection.

Authentication

Litmus Unify uses the OAuth2 password grant via Keycloak (unlike Litmus Edge, which uses client credentials):

POST {{uns_url}}/auth/v3/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id={{uns_oauth_client_id}}
client_secret=
username={{uns_oauth_username}}
password={{uns_oauth_password}}

The client_id defaults to ide-ui (use that unless told otherwise), and client_secret is empty (send it blank or omit it). Only username and password are specific to your account. Use the returned access_token as Authorization: Bearer <token>; a missing or expired token returns HTTP 401 with the body bad token. Every endpoint is a GraphQL operation posted to a single URL: POST {{uns_url}}/mqtt/gql. The operation is selected by the query body, not the URL path, and GraphQL calls return 200 OK even on logical errors, so inspect the errors array in the response.

API components

Litmus Unify 2.0.x (current). Each page carries a version map flagging differences versus <v2.0.0.

Dashboard

Server version, broker statistics, connected clients, and the live topic list.

4 endpoints View in API collection

UNS

The namespace itself: topic tree hierarchy, namespace create/delete, and class-config rules.

4 endpoints View in API collection

MQTT

Broker info, MQTT accounts with publish/subscribe ACL rules, connected clients, interfaces, and activation tokens.

16 endpoints View in API collection

Integrations

Data egress from the namespace: Kafka integrations and the typed connectors framework.

14 endpoints View in API collection

Configuration

Node backup and the update-file / upgrade lifecycle. New in 2.0.x.

8 endpoints View in API collection

The whole product in one place: Litmus Unify in the API collection.

Litmus UNS (<v2.0.0) only

These folders existed in the older Litmus UNS product (<v2.0.0) and no longer exist in Unify 2.0.x; their capabilities moved into the pages above. They remain documented for teams still on <v2.0.0.

Security

MQTT broker accounts and ACLs in Litmus UNS (<v2.0.0). In 2.0.x these live under MQTT / Accounts.

<v2.0.0

Tools

Server config in Litmus UNS (<v2.0.0). In 2.0.x this is the MQTT Server query plus MQTT Update And Restart.

<v2.0.0

Common multi-step tasks

The most frequent integration task is provisioning a broker account for a new machine or application. The provision a UNS MQTT account guide walks the full chain: create the account, set credentials, attach access rules, and verify connectivity.

Getting data into the namespace

Publishing edge data into Unify is configured on the Litmus Edge side, not here: create an integration instance using the Litmus UNS provider in the Litmus Edge Integration API. The Unify API then governs who may consume that data and how the topic tree is organized.

Reference material