Skip to main content

"listTopics" (JSON Action)

JSON MQ "listTopics" action returns and filters a list of MQTT topics

The "listTopics" action lists the names of MQTT topics that the server is tracking.

Essential information

  • You can return a filtered list by specifying a partial name in the "partialName" property.

  • You can include additional items in the list by searching for words contained in the item’s metadata.

  • Use "describeTopics" to get detailed information about specific MQTT topics.

Request examples

Minimal

{
  "api": "mq",
  "action": "listTopics",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "api": "mq",
  "apiVersion": "1.0",
  "requestId": "2",
  "action": "listTopics",
  "params": {
    "partialName": "test",
    "search": null,
    "dataFormat": "arrays",
    "skipRecords": null,
    "maxRecords": 20,
    "label": {
      "group": "group name",
      "name": "label name"
    }
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal

{
  "result": {
    "data": [
      "test/ReasonCodes",
      "test/SharedSubscriptions",
      "test/topic1",
      "test/topic2"
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "result": {
    "data": [
      "test/ReasonCodes",
      "test/SharedSubscriptions",
      "test/topic1",
      "test/topic2"
    ]
  },
  "requestId": "2",
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The "listTopics" JSON action retrieves and filters MQTT topic names by partial name or metadata words. Requests may specify API, action, and authentication tokens, with optional parameters like partial name, search, and data format. Key parameters include "partialName" for filtering by name and "label" for filtering by label properties.

API actionJSON MQ APIJSON Actionlist topicslistTopicsMQTT topicslist MQTT topicsfilter MQTT topicsMQTT broker topicsfilter MQTT dataJSON MQlistTopics actionMQTT topic metadatafilter by namefilter by metadata

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties. See System limits for a comprehensive look at property requirements and limitations.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

label

(optional) filters the response by the results that match the specified label properties

{}

object

"group"
"name"

partialName

(optional) filters the returned topics by applying partial matches to their names

""

string

0 to 64 bytes



"label"

The "label" property filters the response to include results that match the specified label properties. You can filter by label "group" and label "name".

"partialName"

The "partialName" property is an optional string that causes the server to include items in the result when the beginning of their names match the "partialName" value. It defaults to an empty string.

  • A zero-length string matches all names.

  • The "partialName" property is used to filter results in several actions used to return lists.

"result"

Properties summary

Table 2. "result" properties summary

Property

Description

Type

Limits (inclusive)

data

(optional) specifies an array or object that the server returns, such as records returned by a query. It is always included in a response but contains an empty array when no results are available.

It is an empty array when there are no results available

array

Its contents are determined by the action