Reference

8 min

Look up container settings and the Topic Registry REST API.

Configuration

Environment variables configure the Topic Registry container.

Litmus Edge connection

Variable	Required	Default	Meaning
EDGE_API_TOKEN	Yes	None	Litmus Edge API token. No Litmus Edge username or password is used.
EDGE_URL	External mode	Detected Docker gateway in internal mode	HTTP or HTTPS origin for the Litmus Edge API, including its port when required. No path, query, or embedded credentials.
EDGE_VERIFY_TLS	No	true	Verify the Litmus Edge certificate. Set false to accept a self-signed certificate. Applies to API calls and external NATS connections.
EDGE_NATS_TOKEN	External mode	None	Access-account token for the NATS proxy. Internal mode sends no NATS credentials.
EDGE_DOCKER_GATEWAY_IP	When detection fails	Detected Docker gateway	Explicit Docker gateway IP for internal mode when EDGE_URL is unset.
EDGE_CONNECTION_MODE	No	external when EDGE_URL is set; otherwise internal	internal uses the Docker gateway and plain NATS. external uses the supplied URL and authenticated NATS over TLS.

The API uses the scheme and port in EDGE_URL. The NATS connection uses the same hostname on port 4222.

Topic Registry settings

Variable	Required	Default	Meaning
X_LITMUS_KEY	Yes	None	Secret used by the Topic Registry API. External callers send the X_LITMUS_KEY header. The browser receives a cookie automatically.
SHOW_LOGGER	No	false in the production image	Enable verbose diagnostics with true. Connection failures are logged without enabling verbose diagnostics.
SQLITE_URL	No	/app/db_files/sqlite.prod.db in the image	SQLite database file. The installation procedure persists its directory in a named volume.
PORT	No	3000 in the image	HTTP port inside the container.
HOSTNAME	No	0.0.0.0 in the image	Address on which the Topic Registry server listens. This is not the Litmus Edge address.

REST API

Topic Registry exposes the following endpoints on its own HTTP server. They are separate from the Litmus Edge API.

Authentication

Every endpoint below requires the configured Topic Registry secret in the X_LITMUS_KEY request header. Browser requests can use the cookie set by Topic Registry. Invalid or missing credentials return HTTP 401.

Endpoints

Method	Path	Input	Result
POST	/api/status	No body	Application configuration and component retrieval status
GET	/api/value	Required topic query parameter	Cached value for the topic
GET	/api/subscribe	No body	Active simple and wildcard subscriptions
POST	/api/subscribe	Required topic; optional timeout query parameters	Subscribe to the topic and wait for a value
GET	/api/streaming/{topic}	Topic in the path	Server-sent event stream
POST	/api/namespace	JSON object with module and namespace	Add a namespace
DELETE	/api/namespace	JSON object with module and namespace	Remove a namespace

The namespace module is flo for Flows or mp for Marketplace.

Subscription timeout

The subscription timeout is measured in milliseconds. Values from 1 through 60000 are accepted. Missing, invalid, or out-of-range values use 5000.

A new subscription that receives data returns HTTP 200. Waiting without receiving data returns HTTP 201; the subscription remains active. An existing subscription returns HTTP 202.

JSON responses

JSON responses contain success and msg. Successful HTTP handlers can include a data object. Inspect that object's success field when present: a successful handler response does not guarantee that the requested value exists or the namespace operation succeeded.

The streaming endpoint returns text/event-stream rather than a JSON response envelope. Data messages contain timestamp, value, dataType, and rawData. Status and heartbeat events share the stream.

Streaming topic names contain 1–255 characters from letters, digits, dots, underscores, and hyphens. Wildcards are not accepted by the streaming endpoint.

Example requests

Use the Topic Registry server address, not the Litmus Edge API address. Replace the secret and topic with values from your installation.

Retrieve the cached value:

curl --fail-with-body -H 'X_LITMUS_KEY: YOUR_TOPIC_REGISTRY_SECRET' \
  'http://127.0.0.1:3000/api/value?topic=devicehub.alias.sensor1.temperature'

Open a live event stream:

curl -N -H 'X_LITMUS_KEY: YOUR_TOPIC_REGISTRY_SECRET' \
  'http://127.0.0.1:3000/api/streaming/devicehub.alias.sensor1.temperature'

Press Ctrl+C to close the stream. Values arrive only while the source publishes to that topic.

A browser's native EventSource constructor does not accept custom request headers. A page served by Topic Registry can use its same-origin authentication cookie. Use an HTTP client that supports headers when connecting from another application.