HiveMQ REST API (4.4.0)

Download OpenAPI specification:Download

Introduction

HiveMQ's REST API provides endpoints for the following use cases:

  • Listing all MQTT Clients
  • Getting detailed information about a specific MQTT client
  • Listing all subscriptions for a specific MQTT client
  • Getting the connection status for a specific MQTT client
  • Creating and restoring a backup
  • Starting and stopping a trace recording
  • Downloading backups and trace recordings

API style

HiveMQ's API is organized in a RESTful fashion.

The API has predictable resource-oriented URLs that consume and return JSON with the content-type application/json. It uses standard HTTP response codes and verbs. Some endpoints do return files, those are using the content type application/octet-stream or application/zip.

The base URL is the Host and configured port of your HiveMQ instances. In most cases it makes sense to configure a reverse-proxy or load balancer to access HiveMQ's REST API.

Pagination

Some endpoints support returning the results in a paginated fashion. In those cases a cursor can be returned that contains the relative URL for the next page. The desired page size can be specified by using the limit query parameter.

Example URL: http://my-broker-host:8888/api/v1/mqtt/clients?limit=100

Example Response:

{
  "items": [
    {
      "id": "client-id-1"
    },

    ...

    {
      "id": "client-id-99"
    }
  ],
  "_links": {
    "next": "/api/v1/mqtt/clients?cursor=a-MvelExpd5y0SrXBxDhBvnGmohbpzwGDQFdUyOYWBACqs1TgI4-cUo-A=&limit=100"
  }
}

To fetch the next page with more results, the URL http://my-broker-host:8888/api/v1/mqtt/clients?cursor=a-MvelExpd5y0SrXBxDhBvnGmohbpzwGDQFdUyOYWBACqs1TgI4-cUo-A=&limit=100 is called. If the value for _links.next is not present, then this is the last page and no further pages are available.

Note: If a generated REST API client is used the cursor value must be extracted from the next URL and then passed as the cursor in the API call for fetching the next page.

Steps to use pagination in a REST API client:

  1. Returned next URL:

    http://my-broker-host:8888/api/v1/mqtt/clients?cursor=a-MvelExpd5y0SrXBxDhBvnGmohbpzwGDQFdUyOYWBACqs1TgI4-cUo-A=&limit=100
  2. Extract the cursor from the next URL:

    a-MvelExpd5y0SrXBxDhBvnGmohbpzwGDQFdUyOYWBACqs1TgI4-cUo-A=
  3. Use the cursor in the REST API client to fetch the next page:

    restClient.mqttClientsGet(pageLimitForRequest, "a-MvelExpd5y0SrXBxDhBvnGmohbpzwGDQFdUyOYWBACqs1TgI4-cUo-A=");

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request. Codes in the 2xx range generally indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error on the server side.

For all errors a JSON response with additional details is returned in the format Problem JSON.

OpenAPI

HiveMQ's REST API provides an OpenAPI 3.0 schema definition that can imported into popular API tooling (e.g. Postman) or can be used to generate client-code for multiple programming languages.

Backup & Restore

These endpoints can be used to create, download, inspect and restore backups created by HiveMQ.

More information about the backup and restore capabilities of HiveMQ can be found in the HiveMQ documentation.

Backup Requirements

Some prerequisites are necessary to create a backup or restore from a backup:

  • All HiveMQ nodes have at least version 4.4.0
  • Only one backup/restore can be executed at the same time

Export Requirements

The following requirements are necessary to successfully create a backup:

  • All HiveMQ nodes have at least 1GB of free disk space
  • No cluster topology changes occur during the export. The backup is aborted when the topology changes to avoid inconsistent data in the backup.

Restore Requirements

The requirements to successfully restore data from a backup are:

  • A clean HiveMQ deployment. This means that no clients must be connected and no persistent data exists on every HiveMQ node. The import will not start if there is data available in your cluster.
  • Message data used by Extensions are only restored if the corresponding extension is already started before the restore is started.

Download a backup file

Download a specific backup file.

This endpoint returns the content of the backup file with the content-type application/octet-stream.

Only backups in the states COMPLETED, RESTORE_IN_PROGRESS, RESTORE_FAILED or RESTORE_COMPLETED can be downloaded.

This endpoint requires at least HiveMQ version 4.4.0. on all cluster nodes.

path Parameters
backupId
required
string

The id of the backup.

Responses

200

Success

Response Schema: application/octet-stream
string <binary>
400

Bad request

404

Resource not found

503

Cluster node not reachable during download

get/api/v1/management/files/backups/{backupId}
/api/v1/management/files/backups/{backupId}

Response samples

Content type
application/octet-stream

File download

Copy
<raw data>

List all available backups

Lists all available backups with their current state.

This endpoint can be used to get an overview over all backups that are in progress or can be restored.

Canceled or failed backups are included in the results for up to 1 hour after they have been requested.

This endpoint requires at least HiveMQ version 4.4.0. on all cluster nodes.

Responses

200

Success

Response Schema: application/json
items
Array of objects (Backup)

List of result items that are returned by this endpoint

Array
id
string

The id of this backup

createdAt
string <date-time>

Time the backup was created at

state
string
Enum: "COMPLETED" "RESTORE_COMPLETED" "IN_PROGRESS" "RESTORE_IN_PROGRESS" "FAILED" "RESTORE_FAILED"

The current state of the backup

failReason
string Nullable

The reason why this backup failed, only present for failed backups.

bytes
integer <int64> Nullable

The size of this backup file in bytes.

503

Not all cluster nodes at minimum version

get/api/v1/management/backups
/api/v1/management/backups

Response samples

Content type
application/json
Example

Example response with one stored backup and one backup that is currently in progress.

Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      },
    • {
      },
    • {
      }
    ]
}

Create a new backup

Triggers the creation of a new backup.

This endpoint requires at least HiveMQ version 4.4.0. on all cluster nodes.

Responses

200

Success

Response Schema: application/json
backup
object (Backup)
id
string

The id of this backup

createdAt
string <date-time>

Time the backup was created at

state
string
Enum: "COMPLETED" "RESTORE_COMPLETED" "IN_PROGRESS" "RESTORE_IN_PROGRESS" "FAILED" "RESTORE_FAILED"

The current state of the backup

failReason
string Nullable

The reason why this backup failed, only present for failed backups.

bytes
integer <int64> Nullable

The size of this backup file in bytes.

503

Not all cluster nodes at minimum version

post/api/v1/management/backups
/api/v1/management/backups

Response samples

Content type
application/json

Example response with in-progress backup.

Copy
Expand all Collapse all
{
  • "backup":
    {
    • "id": "20201006-1902318",
    • "createdAt": "2020-05-06T08:13:17.000Z",
    • "state": "IN_PROGRESS"
    }
}

Get backup information

Returns the information for a specific backup with its current state.

This endpoint can be used to check the progress of a specific backup when it is being created or being restored.

Canceled or failed backups are returned for up to 1 hour after the have been requested.

This endpoint requires at least HiveMQ version 4.4.0. on all cluster nodes.

path Parameters
backupId
required
string

The id of the backup.

Responses

200

Success

Response Schema: application/json
backup
object (Backup)
id
string

The id of this backup

createdAt
string <date-time>

Time the backup was created at

state
string
Enum: "COMPLETED" "RESTORE_COMPLETED" "IN_PROGRESS" "RESTORE_IN_PROGRESS" "FAILED" "RESTORE_FAILED"

The current state of the backup

failReason
string Nullable

The reason why this backup failed, only present for failed backups.

bytes
integer <int64> Nullable

The size of this backup file in bytes.

400

Bad request

404

Resource not found

503

Not all cluster nodes at minimum version

get/api/v1/management/backups/{backupId}
/api/v1/management/backups/{backupId}

Response samples

Content type
application/json

Example response.

Copy
Expand all Collapse all
{
  • "backup":
    {
    • "id": "20200506-081317",
    • "createdAt": "2020-05-06T08:13:17.000Z",
    • "bytes": 85550653,
    • "state": "COMPLETED"
    }
}

Restore a new backup

Triggers the restore of a stored backup.

This endpoint requires at least HiveMQ version 4.4.0. on all cluster nodes.

path Parameters
backupId
required
string

The id of the backup.

Responses

200

Success

Response Schema: application/json
backup
object (Backup)
id
string

The id of this backup

createdAt
string <date-time>

Time the backup was created at

state
string
Enum: "COMPLETED" "RESTORE_COMPLETED" "IN_PROGRESS" "RESTORE_IN_PROGRESS" "FAILED" "RESTORE_FAILED"

The current state of the backup

failReason
string Nullable

The reason why this backup failed, only present for failed backups.

bytes
integer <int64> Nullable

The size of this backup file in bytes.

400

Bad request

404

Resource not found

503

Not all cluster nodes at minimum version

post/api/v1/management/backups/{backupId}
/api/v1/management/backups/{backupId}

Response samples

Content type
application/json

Example response.

Copy
Expand all Collapse all
{
  • "backup":
    {
    • "id": "20201006-1902318",
    • "createdAt": "2020-05-06T08:13:17.000Z",
    • "state": "IN_PROGRESS"
    }
}

Trace Recordings

A Trace Recording is a combination of filters which allows you to select messages of specific clients or topics, which are logged to a file in a human readable format. Each trace recording creates cluster-wide trace files that can be downloaded as a collective zip file.

You can log any MQTT message sent or received by the broker with a filter you apply. A Filter can either be a client identifier or a topic. Many filter combinations are possible. All filters are regular expressions.

These endpoints can be used to create, download, inspect, stop and delete trace recordings.

More information about the trace recording capabilities of HiveMQ can be found in the HiveMQ documentation.

Download a trace recording

Download a specific trace recording.

This endpoint returns the content of the trace recording with the content-type application/zip.

Only trace recordings in the states IN_PROGRESS, STOPPED and ABORTED can be downloaded.

path Parameters
traceRecordingId
required
string

The id of the trace recording.

Responses

200

Success

Response Schema: application/zip
string <binary>
400

Bad request

404

Resource not found

get/api/v1/management/files/trace-recordings/{traceRecordingId}
/api/v1/management/files/trace-recordings/{traceRecordingId}

Response samples

Content type
application/zip

File download

Copy
<raw data>

Get all trace recordings

Lists all known trace recordings.

Trace recordings can be in different states. These states are:

  • SCHEDULED if the start date for a trace recording is in the future
  • STOPPED if a trace recording has reached its end date or was stopped manually
  • IN_PROGRESS when the trace recording is currently ongoing
  • ABORTED if the trace recording was aborted by the server

Responses

200

Success

Response Schema: application/json
items
Array of objects (TraceRecording)

List of result items that are returned by this endpoint

Array
name
string

Name of the trace recording. Must be unique, contain at least three characters and only combinations of numbers, letters, dashes and underscores are allowed

startAt
string <date-time>

Time the trace recording is scheduled to start at

endAt
string <date-time>

Time the trace recording is scheduled to stop at. Must be at a later time from the start time

clientIdFilters
Array of objects (TraceFilter)

Client ID filters to trace

topicFilters
Array of objects (TraceFilter)

Topic filters to trace

events
Array of strings
Items Enum: "MQTT_MESSAGE_CONNECT" "MQTT_MESSAGE_CONNACK" "MQTT_MESSAGE_SUBSCRIBE" "MQTT_MESSAGE_SUBACK" "MQTT_MESSAGE_PUBLISH" "MQTT_MESSAGE_PUBACK" "MQTT_MESSAGE_PUBREC" "MQTT_MESSAGE_PUBREL" "MQTT_MESSAGE_PUBCOMP" "MQTT_MESSAGE_UNSUBSCRIBE" "MQTT_MESSAGE_UNSUBACK" "MQTT_MESSAGE_PINGREQ" "MQTT_MESSAGE_PINGRESP" "MQTT_MESSAGE_DISCONNECT" "MQTT_MESSAGE_AUTH"

MQTT events to trace

state
string
Enum: "SCHEDULED" "IN_PROGRESS" "ABORTED" "STOPPED"

Current state of the recording. Only sent by the API, ignored if specified on POST

get/api/v1/management/trace-recordings
/api/v1/management/trace-recordings

Response samples

Content type
application/json

Example response with one recording that is in progress.

Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      }
    ]
}

Create a trace recording

Creates a new trace recording.

To create a trace recording you must specify a name, start date, end date, a set of filters and the desired packets that should be traced.

At least one client or topic filter and at least one packet is required to create a trace recording.

The client and topic filters can be regular expressions.

Request Body schema: application/json

The trace recording to create

traceRecording
required
object (TraceRecording)

Trace recording item describing the desired (and optionally, when receiving from the server: current) state of a trace recording

name
string

Name of the trace recording. Must be unique, contain at least three characters and only combinations of numbers, letters, dashes and underscores are allowed

startAt
string <date-time>

Time the trace recording is