MQTT

Capture exposes a real-time MQTT broker. Depending on your account type you can use it to receive live data, push data in, or send commands to sources.

Connecting

For the standard Capture Cloud environment, the hostname is mqtt.captureplatform.com. Use TLS enabled with certificate validation on — the broker presents a valid certificate, so no custom CA or insecure mode is needed. For other environments, contact the Capture team to obtain the hostname.

Protocol	Port	Example	Notes
MQTTS (TLS)	8883	mqtts://mqtt.captureplatform.com:8883	Recommended for most clients
WSS (Secure WebSocket)	443	wss://mqtt.captureplatform.com:443/mqtt	Base path: /mqtt
WSS (Secure WebSocket)	8084	wss://mqtt.captureplatform.com:8084/mqtt	Base path: /mqtt

Authentication

Use your Capture credentials to authenticate. Two methods are supported:

Username & Password

Use any active Capture user account username and password. If you are authenticating as a source/device, use the credentials found in the auth config, which can be downloaded from the source details page in the Capture portal.

Username & JWT Token

Use your Capture username as the username field and a JWT token obtained from the Capture Auth API as the password field.

API Token

Use the API token's ID (GUID) as the username field and the API token value as the password field. The GUID is visible in the token details page in the Capture portal under Identity → API Tokens. An API token authenticates as a user account — see Authorization for what it can access.

Authorization

What you can publish and subscribe to depends on the type of account you authenticate with. Authorization is checked on every publish and subscribe, so a topic outside your allowed scope is rejected by the broker.

User accounts (regular Capture users and API tokens) can:

Action	Allowed topics
Subscribe	v1/raw/[your company]/# (including sub-companies)
Subscribe	v1/uns/# for assets your company has access to
Subscribe	v1/sources/[any source in your company]/#
Publish	v1/sources/[Source ID]/cmd/... (commands to your own sources)

User accounts are otherwise read-only — they cannot publish data into the raw, uns, or data/read topics.

Source/device accounts can publish and subscribe, but only within their own v1/sources/[Source ID]/... subtree (logs, status, cmd, data/read, data/write). They cannot access other sources, the raw tree, or the uns tree.

---

Subscribing to live data (raw)

The raw tree exposes every data point collected by Capture, broken down to individual field-level topics. Each message contains a single field value.

Topic format

v1/raw/[Company Name]/[Source ID]/[Connection Tag]/[Measurement]/[Key]

Example

v1/raw/AcmeCorp/fe453df1-b4a0-492d-a12c-505988eea849/System_Monitoring_Requester/Monitoring/CPU_Temp

Payload

{
  "Value": 55,
  "Tags": {
    "Connection_Tag": "System_Monitoring_Requester",
    "MachineName": "MyMachine",
    "SerialNumber": "77777"
  },
  "UtcTimestamp": "2024-11-08T10:22:06.26Z"
}

You can use MQTT wildcards from the Source ID level and below. The company name segment must always be an exact match — wildcarding it will be rejected by the broker.

Receive all data under your company:

v1/raw/AcmeCorp/#

Receive all fields for a specific measurement across all sources:

v1/raw/AcmeCorp/+/+/Monitoring/#

Subscribing to the Unified Namespace (uns)

The uns tree exposes the same live data as raw, but organized by your asset hierarchy (namespace → asset → … → field) instead of by source. A data point appears in the uns tree once it has been mapped to a UNS path in Capture.

Topic format

v1/uns/[Namespace]/[Asset]/.../[Key]

The path can be any depth — every segment except the last identifies an asset in the hierarchy, and the final segment is the field key.

Example

v1/uns/AcmeCorp/Plant1/Line2/Press/CPU_Temp

Payload

{
  "Value": 55,
  "Tags": {
    "MachineName": "MyMachine",
    "SerialNumber": "77777"
  },
  "UtcTimestamp": "2024-11-08T10:22:06.26Z"
}

The payload has the same shape as a raw message. Source-oriented tags that don't apply in an asset context (such as Connection_Tag) are stripped before publishing.

You can use MQTT wildcards to subscribe within the asset hierarchy. You can only subscribe to assets your company has access to, and the asset must exist in Capture — subscriptions to assets you cannot access will be rejected by the broker.

Receive everything under a namespace:

v1/uns/AcmeCorp/#

Sending commands to a source

User accounts can publish commands to any source that belongs to their company.

Topic format

v1/sources/[Source ID]/cmd/writedata

Payload

{
  "Topic": "{connection}/{measurement}/{variable}",
  "Mapping": "{mapping}",
  "Data": "{value}"
}

---

Source/device accounts

Sources registered in Capture have their own dedicated credentials. A source account can only publish and subscribe within its own v1/sources/[Source ID]/... subtree — it cannot access other sources or the raw tree.

Pushing data into Capture

Sources publish data to the data/read subtopic. Two payload formats are accepted.

Field level — one field per message

Topic:

v1/sources/[Source ID]/data/read/[Connection Tag]/[Measurement]/[Key]

Payload:

{
  "Value": 55,
  "Tags": {
    "MachineName": "MyMachine"
  },
  "UtcTimestamp": "2024-11-08T10:22:06.26Z"
}

Measurement level — multiple fields in one message

Topic:

v1/sources/[Source ID]/data/read/[Connection Tag]/[Measurement]

Payload:

{
  "Fields": {
    "CPU_Temp": 55,
    "CPU_Load": 23.4
  },
  "Tags": {
    "MachineName": "MyMachine"
  },
  "UtcTimestamp": "2024-11-08T10:22:06.26Z"
}

Timestamp formats

The UtcTimestamp field accepts:

• ISO 8601 string: "2024-11-08T10:22:06.26Z"
• Unix epoch in milliseconds: 1731060126260
• Omitted — Capture will use the time the message is received

---

tip

If you get disconnected immediately after connecting, it is most likely an authorization issue. Check that the topic you are subscribing or publishing to falls within the allowed scope for your account type.