---
title: Reference
slug: solutions/topic-registry/reference
description: Container configuration and REST API endpoints for Topic Registry.
createdAt: 2024-11-05T15:45:11.922Z
---

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:

```bash
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:

```bash
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](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource) 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.