< EMQX v5.8 Docs Submit API issue
redocly logoAPI docs by Redocly

EMQX API (5.8.6)

Download OpenAPI specification:Download

Plugins

Get installed plugin's AVRO schema

Get plugin's config AVRO schema.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Responses

Response samples

Content type
application/json
"string"

Get a plugin description

Describe a plugin according to its release.json and README.md.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Responses

Response samples

Content type
application/json
{
  • "name": "emqx_plugin_template-5.0-rc.1",
  • "author": [
    ],
  • "builder": {
    },
  • "built_on_otp_release": "24",
  • "compatibility": {
    },
  • "git_commit_or_build_date": "2021-12-25",
  • "functionality": [
    ],
  • "git_ref": "ddab50fafeed6b1faea70fc9ffd8c700d7e26ec1",
  • "metadata_vsn": "0.1.0",
  • "rel_vsn": "5.0-rc.1",
  • "rel_apps": [
    ],
  • "repo": "https://github.com/emqx/emqx-plugin-template",
  • "description": "This is an demo plugin description",
  • "running_status": [
    ],
  • "readme": "This is an demo plugin."
}

Delete a plugin

Uninstalls a previously uploaded plugin package.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Responses

Response samples

Content type
application/json
{
  • "code": "PARAM_ERROR",
  • "message": "string"
}

Get plugin config

Get plugin config. Config schema is defined by user's schema.avsc file.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Responses

Response samples

Content type
application/json
"string"

Update plugin config

Update plugin config. Config schema defined by user's schema.avsc file.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": "BAD_CONFIG",
  • "message": "string"
}

Trigger action on an installed plugin

start/stop a installed plugin.
- start: start the plugin.
- stop: stop the plugin.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

action
required
string
Enum: "start" "stop"

Action

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List all installed plugins

Plugins are launched in top-down order.
Use POST /plugins/{name}/move to change the boot order.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Move plugin within plugin hierarchy

Setting the boot order of plugins.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: emqx_plugin_template-5.0-rc.1

^[A-Za-z]+[A-Za-z0-9-_.]*$

Request Body schema: application/json
string or string or string


Enable auto-boot at position in the boot list, where Position could be
'front', 'rear', or 'before:other-vsn', 'after:other-vsn'
to specify a relative position.

Responses

Request samples

Content type
application/json
Example
{
  • "position": "after:emqx_plugin_demo-5.1-rc.2"
}

Response samples

Content type
application/json
{
  • "code": "MOVE_FAILED",
  • "message": "string"
}

Install a new plugin

Upload a plugin tarball (plugin-vsn.tar.gz).Follow emqx-plugin-template to develop plugin.

Authorizations:
basicAuthbearerAuth
Request Body schema: multipart/form-data
plugin
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "UNEXPECTED_ERROR",
  • "message": "string"
}

Authentication

Move authenticator in global authentication chain.

Move authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

position
required
string
Example: before:password_based:built_in_database

Position of authenticator in chain. Possible values are 'front', 'rear', 'before:{other_authenticator}', 'after:{other_authenticator}'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get user from authenticator in global authenticati

Get user from authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

user_id
required
string

User ID.

Responses

Response samples

Content type
application/json
Example
{
  • "user_id": "user1"
}

Update user in authenticator in global authenticat

Update user in authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

user_id
required
string

User ID.

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Delete user in authenticator in global authenticat

Delete user in authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

user_id
required
string

User ID.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Import users into authenticator in global authenti

Import users into authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

query Parameters
type
required
string
Enum: "plain" "hash"
Example: type=hash

The import file template type, enum with plain,hash

Request Body schema:

Import body

filename
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "total": 0,
  • "success": 0,
  • "override": 0,
  • "skipped": 0,
  • "failed": 0
}

List users in authenticator in global authenticati

List users in authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_user_id
string

Fuzzy search user_id (username or clientid).

is_superuser
boolean

Is superuser

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create users for authenticator in global authentic

Create users for authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
Example
{
  • "user_id": "user1"
}

Get authenticator status from global authenticatio

Get authenticator status from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

Content type
application/json
{
  • "status": "connected",
  • "node_status": [
    ],
  • "metrics": {
    },
  • "resource_metrics": {
    },
  • "node_error": [ ],
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ]
}

Get authenticator from global authentication chain

Get authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Update authenticator from global authentication ch

Update authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Request Body schema: application/json
One of
mechanism
required
string
Value: "password_based"

Authentication mechanism.

backend
required
string
Value: "ldap"

Backend type.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

Indicates which attribute is used to represent the user's password.

is_superuser_attribute
string
Default: "isSuperuser"

Indicates which attribute is used to represent whether the user is a superuser.

Responses

Request samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete authenticator from global authentication ch

Delete authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

List authenticators for global authentication.

List authenticators for global authentication.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create authenticator for global authentication.

Create authenticator for global authentication.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
mechanism
required
string
Value: "password_based"

Authentication mechanism.

backend
required
string
Value: "ldap"

Backend type.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

Indicates which attribute is used to represent the user's password.

is_superuser_attribute
string
Default: "isSuperuser"

Indicates which attribute is used to represent whether the user is a superuser.

Responses

Request samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Reorder all authenticators in global authenticatio

Reorder all authenticators in global authentication chain.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
id
required
string

Authenticator ID.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Actions

Reset action metrics

Reset a bridge metrics by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Manually start a bridge

Start bridge on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Enable or disable bridge

Enable or Disable bridge on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

enable
required
boolean
Example: true

Whether to enable this bridge.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List bridges

List all created bridges.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create bridge

Create a new bridge by type and name.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"
name
required
string
local_topic
string

MQTT topic or topic filter as data source (action input). If rule action is used as data source, this config should be left empty, otherwise messages will be duplicated in the remote system.

required
object (bridge_mqtt_publisher.action_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (bridge_mqtt_publisher.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Test creating bridge

Test creating a new bridge.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"
name
required
string
local_topic
string

MQTT topic or topic filter as data source (action input). If rule action is used as data source, this config should be left empty, otherwise messages will be duplicated in the remote system.

required
object (bridge_mqtt_publisher.action_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (bridge_mqtt_publisher.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

List available action types

Lists the available action types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "http",
  • "mqtt"
]

Summarize actions

Summarize actions.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get bridge

Get a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Update bridge

Update a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Request Body schema: application/json
One of
local_topic
string

MQTT topic or topic filter as data source (action input). If rule action is used as data source, this config should be left empty, otherwise messages will be duplicated in the remote system.

required
object (bridge_mqtt_publisher.action_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (bridge_mqtt_publisher.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Delete bridge

Delete a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

query Parameters
also_delete_dep_actions
boolean
Default: false

Whether to cascade delete dependent actions.

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get action metrics

Get bridge metrics by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

Manually start a bridge on a given node

Start bridge on a specific node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

The node name, e.g. 'emqx@127.0.0.1'.

id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Metrics

EMQX metrics

EMQX metrics

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Whether to aggregate all nodes Metrics. Default value is 'true'.

node
string

Specify which specific node to fetch data from. If not provided, return values for all nodes. This parameter only works when 'aggregate' is 'false'.

Responses

Response samples

Content type
application/json
Example
[ ]

EMQX stats

EMQX stats

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Calculation aggregate for all nodes

Responses

Response samples

Content type
application/json
Example
{
  • "channels.count": 0,
  • "channels.max": 0,
  • "connections.count": 0,
  • "connections.max": 0,
  • "delayed.count": 0,
  • "delayed.max": 0,
  • "live_connections.count": 0,
  • "live_connections.max": 0,
  • "cluster_sessions.count": 0,
  • "cluster_sessions.max": 0,
  • "retained.count": 0,
  • "retained.max": 0,
  • "sessions.count": 0,
  • "sessions.max": 0,
  • "suboptions.count": 0,
  • "suboptions.max": 0,
  • "subscribers.count": 0,
  • "subscribers.max": 0,
  • "subscriptions.count": 0,
  • "subscriptions.max": 0,
  • "subscriptions.shared.count": 0,
  • "subscriptions.shared.max": 0,
  • "topics.count": 0,
  • "topics.max": 0
}

Current monitor (statistics) data, e.g. number of

Current monitor (statistics) data, e.g. number of connections and connection rate in the whole cluster.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "persisted_rate": 0,
  • "received_msg_rate": 0,
  • "transformation_failed_rate": 0,
  • "validation_failed_rate": 0,
  • "transformation_succeeded_rate": 0,
  • "validation_succeeded_rate": 0,
  • "disconnected_durable_sessions": 0,
  • "subscriptions_durable": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0,
  • "retained_msg_count": 0,
  • "shared_subscriptions": 0
}

Node monitor (statistics) data, e.g. number of con

Node monitor (statistics) data, e.g. number of connections and connection rate on the specified node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

EMQX node name.

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "persisted_rate": 0,
  • "received_msg_rate": 0,
  • "transformation_failed_rate": 0,
  • "validation_failed_rate": 0,
  • "transformation_succeeded_rate": 0,
  • "validation_succeeded_rate": 0,
  • "disconnected_durable_sessions": 0,
  • "subscriptions_durable": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0,
  • "node_uptime": 0,
  • "retained_msg_count": 0,
  • "shared_subscriptions": 0
}

List the monitor (statistics) data on the specifie

List the monitor (statistics) data on the specified node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

EMQX node name.

query Parameters
latest
integer >= 1
Example: latest=300

The latest N seconds data. Like 300 for 5 min.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List monitor (statistics) data for the whole clust

List monitor (statistics) data for the whole cluster.

Authorizations:
basicAuthbearerAuth
query Parameters
latest
integer >= 1
Example: latest=300

The latest N seconds data. Like 300 for 5 min.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear monitor (statistics) data for the whole clus

Clear monitor (statistics) data for the whole cluster.

Authorizations:
basicAuthbearerAuth

Responses

MQTT

Get delayed status

Get delayed status

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "max_delayed_messages": 0
}

Enable or disable delayed, set max delayed message

Enable or disable delayed, set max delayed messages

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: true

Enable this feature

max_delayed_messages
integer
Default: 0

Maximum number of delayed messages (0 is no limit).

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "max_delayed_messages": 0
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "max_delayed_messages": 0
}

View delayed message

View delayed message

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

The node where message from

msgid
required
string

Delayed Message ID

Responses

Response samples

Content type
application/json
{
  • "msgid": 0,
  • "node": "string",
  • "publish_at": "string",
  • "delayed_interval": 1,
  • "delayed_remaining": 0,
  • "expected_at": "string",
  • "topic": "/sys/#",
  • "qos": 0,
  • "from_clientid": "string",
  • "from_username": "string"
}

Delete delayed message

Delete delayed message

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

The node where message from

msgid
required
string

Delayed Message ID

Responses

Response samples

Content type
application/json
{
  • "code": "MESSAGE_ID_SCHEMA_ERROR",
  • "message": "string"
}

List all rewrite rules

List all rewrite rules

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update all rewrite rules

Update all rewrite rules

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
action
required
string
Enum: "subscribe" "publish" "all"

Topic rewriting takes effect on the type of operation:
- subscribe: Rewrite topic when client do subscribe.
- publish: Rewrite topic when client do publish.
- all: Both

source_topic
required
string

Source topic, specified by the client.

dest_topic
required
string

Destination topic.

re
required
string

Regular expressions

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Get topic metrics

Get topic metrics

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string
Example: testtopic/1

Topic string. Notice: Topic string in url path must be encoded

Responses

Response samples

Content type
application/json
{
  • "topic": "testtopic/1",
  • "create_time": "2022-01-14T21:48:47+08:00",
  • "reset_time": "2022-01-14T21:48:47+08:00",
  • "metrics": {
    }
}

Delete topic metrics

Delete topic metrics

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string
Example: testtopic/1

Topic string. Notice: Topic string in url path must be encoded

Responses

Response samples

Content type
application/json
{
  • "code": "TOPIC_NOT_FOUND",
  • "message": "string"
}

Delete delayed message

Delete delayed message

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic

Responses

Response samples

Content type
application/json
{
  • "code": "INVALID_TOPIC_NAME",
  • "message": "string"
}

List topic metrics

List topic metrics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reset telemetry status

Reset telemetry status

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
topic
string

Topic Name. If this parameter is not present,all created topic metrics will be reset.

action
required
string

Action. Only support reset

Responses

Request samples

Content type
application/json
Example
{
  • "action": "reset"
}

Response samples

Content type
application/json
{
  • "code": "TOPIC_NOT_FOUND",
  • "message": "string"
}

Create topic metrics

Create topic metrics

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
topic
required
string

Raw topic string

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List delayed messages

List delayed messages

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

LwM2M Gateways

Observe a Resource

Observe or Cancel observe a resource

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7
enable
required
boolean
Example: enable=true

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_NOT_FOUND",
  • "message": "string"
}

List Client's Resources

Look up a resource

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7
action
required
string
Example: action=discover

Responses

Response samples

Content type
application/json
{
  • "clientid": "urn:oma:lwm2m:oma:2",
  • "path": "/3/0/7",
  • "action": "discover",
  • "codeMsg": "reply_not_received",
  • "content": [
    ]
}

Read Value from a Resource Path

Send a read command to a resource

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_NOT_FOUND",
  • "message": "string"
}

Write a Value to Resource Path

Send a write command to a resource

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: urn:oma:lwm2m:oma:2
query Parameters
path
required
string
Example: path=/3/0/7
type
required
string
Enum: "Integer" "Float" "Time" "String" "Boolean" "Opaque" "Objlnk"
Example: type=Integer
value
required
string
Example: value=123

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENT_NOT_FOUND",
  • "message": "string"
}

Bridges

Reset bridge metrics

Reset a bridge metrics by Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Stop/restart bridge

Stop/Restart bridges on a specific node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

The node name, e.g. emqx@127.0.0.1

id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

operation
required
string
Enum: "start" "stop" "restart"
Example: start

Operations can be one of: stop, restart

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Test creating bridge

Test creating a new bridge by given ID

The ID must be of format '{type}:{name}'

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Enum: "webhook" "http"

The action type.

name
required
string

Action name, used as a human-readable identifier.

enable
boolean
Default: true

Enable or disable this action.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

connect_timeout
string
Default: "15s"

The timeout when connecting to the HTTP server.

retry_interval
string
Deprecated
pool_type
string
Default: "random"
Enum: "random" "hash"

The type of the pool. Can be one of random, hash.

pool_size
integer >= 1
Default: 8

The pool size.

enable_pipelining
integer >= 1
Default: 100

The maximum number of HTTP requests that can be sent before an HTTP response is received.

Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.

request
object
Deprecated

This field is never used, so we deprecated it since 5.3.2.

object (emqx.ssl_client_opts)
url
required
string

The URL of the HTTP action.

Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.

For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.

direction
string
Deprecated
Value: "egress"
local_topic
string

The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.

NOTE: If this action is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.

method
string
Default: "post"
Enum: "post" "put" "get" "delete"

The method of the HTTP request. All the available methods are: post, put, get, delete.

Template with variables is allowed.

headers
object
Default: {"accept":"application/json","cache-control":"no-cache","connection":"keep-alive","content-type":"application/json","keep-alive":"timeout=5"}

The headers of the HTTP request.

Template with variables is allowed.

body
string

The body of the HTTP request.

If not provided, the body will be a JSON object of all the available fields.

There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the local_topic is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).

Template with variables is allowed.

max_retries
integer >= 0
Default: 2

HTTP request max retry times if failed.

request_timeout
string
Deprecated
Default: "15s"

HTTP request timeout.

object (bridge_http.v1_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

Enable or disable bridge

Enable or Disable bridges on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

enable
required
boolean
Example: true

Whether to enable this bridge

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get bridge metrics

Get bridge metrics by Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

Get bridge

Get a bridge by Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

Responses

Response samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Update bridge

Update a bridge by Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

Request Body schema: application/json
One of
enable
boolean
Default: true

Enable or disable this action.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

connect_timeout
string
Default: "15s"

The timeout when connecting to the HTTP server.

retry_interval
string
Deprecated
pool_type
string
Default: "random"
Enum: "random" "hash"

The type of the pool. Can be one of random, hash.

pool_size
integer >= 1
Default: 8

The pool size.

enable_pipelining
integer >= 1
Default: 100

The maximum number of HTTP requests that can be sent before an HTTP response is received.

Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.

request
object
Deprecated

This field is never used, so we deprecated it since 5.3.2.

object (emqx.ssl_client_opts)
url
required
string

The URL of the HTTP action.

Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.

For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.

direction
string
Deprecated
Value: "egress"
local_topic
string

The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.

NOTE: If this action is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.

method
string
Default: "post"
Enum: "post" "put" "get" "delete"

The method of the HTTP request. All the available methods are: post, put, get, delete.

Template with variables is allowed.

headers
object
Default: {"accept":"application/json","cache-control":"no-cache","connection":"keep-alive","content-type":"application/json","keep-alive":"timeout=5"}

The headers of the HTTP request.

Template with variables is allowed.

body
string

The body of the HTTP request.

If not provided, the body will be a JSON object of all the available fields.

There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the local_topic is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).

Template with variables is allowed.

max_retries
integer >= 0
Default: 2

HTTP request max retry times if failed.

request_timeout
string
Deprecated
Default: "15s"

HTTP request timeout.

object (bridge_http.v1_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Response samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Delete bridge

Delete a bridge by Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Stop or restart bridge

Stop/Restart bridges on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:http_example

The bridge Id. Must be of format {type}:{name}

operation
required
string
Enum: "start" "stop" "restart"
Example: start

Operations can be one of: stop, restart

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List bridges

List all created bridges

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create bridge

Create a new bridge by type and name

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Enum: "webhook" "http"

The action type.

name
required
string

Action name, used as a human-readable identifier.

enable
boolean
Default: true

Enable or disable this action.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

connect_timeout
string
Default: "15s"

The timeout when connecting to the HTTP server.

retry_interval
string
Deprecated
pool_type
string
Default: "random"
Enum: "random" "hash"

The type of the pool. Can be one of random, hash.

pool_size
integer >= 1
Default: 8

The pool size.

enable_pipelining
integer >= 1
Default: 100

The maximum number of HTTP requests that can be sent before an HTTP response is received.

Setting this to 1 is equivalent to turning off HTTP pipelining, and the EMQX must receive a response to the previous HTTP request before sending the next HTTP request.

request
object
Deprecated

This field is never used, so we deprecated it since 5.3.2.

object (emqx.ssl_client_opts)
url
required
string

The URL of the HTTP action.

Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.

For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.

direction
string
Deprecated
Value: "egress"
local_topic
string

The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.

NOTE: If this action is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.

method
string
Default: "post"
Enum: "post" "put" "get" "delete"

The method of the HTTP request. All the available methods are: post, put, get, delete.

Template with variables is allowed.

headers
object
Default: {"accept":"application/json","cache-control":"no-cache","connection":"keep-alive","content-type":"application/json","keep-alive":"timeout=5"}

The headers of the HTTP request.

Template with variables is allowed.

body
string

The body of the HTTP request.

If not provided, the body will be a JSON object of all the available fields.

There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the local_topic is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).

Template with variables is allowed.

max_retries
integer >= 0
Default: 2

HTTP request max retry times if failed.

request_timeout
string
Deprecated
Default: "15s"

HTTP request timeout.

object (bridge_http.v1_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Response samples

Content type
application/json
Example
{
  • "name": "http_example",
  • "type": "http",
  • "ssl": {
    },
  • "connect_timeout": "15s",
  • "pool_size": 4,
  • "enable": true,
  • "body": "${payload}",
  • "method": "post",
  • "url": "http://localhost:9901/messages/${topic}",
  • "max_retries": 3,
  • "request_timeout": "15s",
  • "pool_type": "random",
  • "resource_opts": {
    },
  • "enable_pipelining": 100,
  • "local_topic": "emqx_http/#"
}

Status

Serves as a health check for the node.<br/>Returns

Serves as a health check for the node.
Returns response to describe the status of the node and the application.

This endpoint requires no authentication.

Returns status code 200 if the EMQX application is up and running, 503 otherwise.
This API was introduced in v5.0.10.
The GET /status endpoint (without the /api/... prefix) is also an alias to this endpoint and works in the same way.
This alias has been available since v5.0.0.

Starting from v5.0.25 or e5.0.4, you can also use 'format' parameter to get JSON format information.

query Parameters
format
string
Default: "text"

Specify the response format, 'text' (default) to return the HTTP body in free text,
or 'json' to return the HTTP body with a JSON object.

Responses

Topics

Lookup topic info by name

Lookup topic info by name

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic Name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Topics list

Topics list

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

Topic Name

node
string
Example: node=emqx@127.0.0.1

Node Name

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Authorization

Show the list of rules for users

Show the list of rules for users

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_username
string

Fuzzy search username as substring

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add new rule for 'username'

Add new rule for 'username'

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
Array of objects (emqx_authz_api_mnesia.rule_item)
username
required
string

Username

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Show the list of rules for clients

Show the list of rules for clients

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_clientid
string

Fuzzy search clientid as substring

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add new rule for 'clientid'

Add new rule for 'clientid'

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
Array of objects (emqx_authz_api_mnesia.rule_item)
clientid
required
string

ClientID

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get rule for 'clientid'

Get rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "clientid": "client1"
}

Set rule for 'clientid'

Set rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)
clientid
required
string

ClientID

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ],
  • "clientid": "client1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete rule for 'clientid'

Delete rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get a authorization source

Get a authorization source

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

Authorization type

Responses

Response samples

Content type
application/json
{
  • "status": "connected",
  • "node_status": [
    ],
  • "metrics": {
    },
  • "resource_metrics": {
    },
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ]
}

List all authorization sources

List all authorization sources

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ]
}

Add a new source

Add a new source

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "ldap"

Backend type.

enable
boolean
Default: true

Set to true or false to disable this ACL provider

publish_attribute
string
Default: "mqttPublishTopic"

Indicates which attribute is used to represent the allowed topics list of the publish.

subscribe_attribute
string
Default: "mqttSubscriptionTopic"

Indicates which attribute is used to represent the allowed topics list of the subscribe.

all_attribute
string
Default: "mqttPubSubTopic"

Indicates which attribute is used to represent the both allowed topics list of publish and subscribe.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "ldap",
  • "enable": true,
  • "publish_attribute": "mqttPublishTopic",
  • "subscribe_attribute": "mqttSubscriptionTopic",
  • "all_attribute": "mqttPubSubTopic",
  • "query_timeout": "32s",
  • "server": "string",
  • "pool_size": 8,
  • "username": "string",
  • "password": "R4ND0M/S∃CЯ∃T",
  • "base_dn": "uid=${username},ou=testdevice,dc=emqx,dc=io",
  • "filter": "(& (objectClass=mqttUser) (uid=${username}))",
  • "request_timeout": "32s",
  • "ssl": {
    }
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get rule for 'username'

Get rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "username": "user1"
}

Set rule for 'username'

Set rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)
username
required
string

Username

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ],
  • "username": "user1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete rule for 'username'

Delete rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete all rules for all 'users', 'clients' and 'a

Delete all rules for all 'users', 'clients' and 'all'

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Change the exection order of sources

Change the exection order of sources

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

Authorization type

Request Body schema: application/json
position
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "position": "rear"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get a authorization source

Get a authorization source

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

Authorization type

Responses

Response samples

Content type
application/json
Example
{
  • "type": "ldap",
  • "enable": true,
  • "publish_attribute": "mqttPublishTopic",
  • "subscribe_attribute": "mqttSubscriptionTopic",
  • "all_attribute": "mqttPubSubTopic",
  • "query_timeout": "32s",
  • "server": "string",
  • "pool_size": 8,
  • "username": "string",
  • "password": "R4ND0M/S∃CЯ∃T",
  • "base_dn": "uid=${username},ou=testdevice,dc=emqx,dc=io",
  • "filter": "(& (objectClass=mqttUser) (uid=${username}))",
  • "request_timeout": "32s",
  • "ssl": {
    }
}

Update source

Update source

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

Authorization type

Request Body schema: application/json
One of
type
required
string
Value: "ldap"

Backend type.

enable
boolean
Default: true

Set to true or false to disable this ACL provider

publish_attribute
string
Default: "mqttPublishTopic"

Indicates which attribute is used to represent the allowed topics list of the publish.

subscribe_attribute
string
Default: "mqttSubscriptionTopic"

Indicates which attribute is used to represent the allowed topics list of the subscribe.

all_attribute
string
Default: "mqttPubSubTopic"

Indicates which attribute is used to represent the both allowed topics list of publish and subscribe.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "ldap",
  • "enable": true,
  • "publish_attribute": "mqttPublishTopic",
  • "subscribe_attribute": "mqttSubscriptionTopic",
  • "all_attribute": "mqttPubSubTopic",
  • "query_timeout": "32s",
  • "server": "string",
  • "pool_size": 8,
  • "username": "string",
  • "password": "R4ND0M/S∃CЯ∃T",
  • "base_dn": "uid=${username},ou=testdevice,dc=emqx,dc=io",
  • "filter": "(& (objectClass=mqttUser) (uid=${username}))",
  • "request_timeout": "32s",
  • "ssl": {
    }
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete source

Delete source

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

Authorization type

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Reorder all authorization sources.

Reorder all authorization sources.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
type
required
string
Enum: "file" "built_in_database" "http" "redis" "mysql" "postgresql" "mongodb" "ldap"

Authorization type

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Clean all authorization cache in the cluster.

Clean all authorization cache in the cluster.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get authorization settings

Get authorization settings

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "no_match": "allow",
  • "deny_action": "ignore",
  • "cache": {
    }
}

Update authorization settings

Update authorization settings

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
no_match
required
string
Default: "allow"
Enum: "allow" "deny"

Default access control action if the user or client matches no ACL rules,
or if no such user or client is found by the configurable authorization
sources such as built_in_database, an HTTP API, or a query against PostgreSQL.
Find more details in 'authorization.sources' config.

deny_action
required
string
Default: "ignore"
Enum: "ignore" "disconnect"

The action when the authorization check rejects an operation.

object (emqx.authz_cache)

Responses

Request samples

Content type
application/json
{
  • "no_match": "allow",
  • "deny_action": "ignore",
  • "cache": {
    }
}

Response samples

Content type
application/json
{
  • "no_match": "allow",
  • "deny_action": "ignore",
  • "cache": {
    }
}

Show the list of rules for 'all'

Show the list of rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Delete rules for 'all'

Delete rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Create/Update the list of rules for 'all'.

Create/Update the list of rules for 'all'.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Nodes

Get node run-time stats. Such as the number of top

Get node run-time stats. Such as the number of topics, connections, etc.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "channels.count": 0,
  • "channels.max": 0,
  • "connections.count": 0,
  • "connections.max": 0,
  • "delayed.count": 0,
  • "delayed.max": 0,
  • "live_connections.count": 0,
  • "live_connections.max": 0,
  • "cluster_sessions.count": 0,
  • "cluster_sessions.max": 0,
  • "retained.count": 0,
  • "retained.max": 0,
  • "sessions.count": 0,
  • "sessions.max": 0,
  • "suboptions.count": 0,
  • "suboptions.max": 0,
  • "subscribers.count": 0,
  • "subscribers.max": 0,
  • "subscriptions.count": 0,
  • "subscriptions.max": 0,
  • "subscriptions.shared.count": 0,
  • "subscriptions.shared.max": 0,
  • "topics.count": 0,
  • "topics.max": 0
}

Get node run-time counter metrics. Such as receive

Get node run-time counter metrics. Such as received or sent bytes or messages, the number of succeeded or failed authentications or authorizations, etc.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "node": "string",
  • "bytes.received": 0,
  • "bytes.sent": 0,
  • "packets.received": 0,
  • "packets.sent": 0,
  • "packets.connect.received": 0,
  • "packets.connack.sent": 0,
  • "packets.connack.error": 0,
  • "packets.connack.auth_error": 0,
  • "packets.publish.received": 0,
  • "packets.publish.sent": 0,
  • "packets.publish.inuse": 0,
  • "packets.publish.error": 0,
  • "packets.publish.auth_error": 0,
  • "packets.publish.dropped": 0,
  • "packets.puback.received": 0,
  • "packets.puback.sent": 0,
  • "packets.puback.inuse": 0,
  • "packets.puback.missed": 0,
  • "packets.pubrec.received": 0,
  • "packets.pubrec.sent": 0,
  • "packets.pubrec.inuse": 0,
  • "packets.pubrec.missed": 0,
  • "packets.pubrel.received": 0,
  • "packets.pubrel.sent": 0,
  • "packets.pubrel.missed": 0,
  • "packets.pubcomp.received": 0,
  • "packets.pubcomp.sent": 0,
  • "packets.pubcomp.inuse": 0,
  • "packets.pubcomp.missed": 0,
  • "packets.subscribe.received": 0,
  • "packets.subscribe.error": 0,
  • "packets.subscribe.auth_error": 0,
  • "packets.suback.sent": 0,
  • "packets.unsubscribe.received": 0,
  • "packets.unsubscribe.error": 0,
  • "packets.unsuback.sent": 0,
  • "packets.pingreq.received": 0,
  • "packets.pingresp.sent": 0,
  • "packets.disconnect.received": 0,
  • "packets.disconnect.sent": 0,
  • "packets.auth.received": 0,
  • "packets.auth.sent": 0,
  • "messages.received": 0,
  • "messages.sent": 0,
  • "messages.qos0.received": 0,
  • "messages.qos0.sent": 0,
  • "messages.qos1.received": 0,
  • "messages.qos1.sent": 0,
  • "messages.qos2.received": 0,
  • "messages.qos2.sent": 0,
  • "messages.publish": 0,
  • "messages.dropped": 0,
  • "messages.validation_failed": 0,
  • "messages.validation_succeeded": 0,
  • "messages.transformation_failed": 0,
  • "messages.transformation_succeeded": 0,
  • "messages.dropped.await_pubrel_timeout": 0,
  • "messages.dropped.no_subscribers": 0,
  • "messages.forward": 0,
  • "messages.delayed": 0,
  • "messages.delivered": 0,
  • "messages.acked": 0,
  • "messages.persisted": 0,
  • "delivery.dropped": 0,
  • "delivery.dropped.no_local": 0,
  • "delivery.dropped.too_large": 0,
  • "delivery.dropped.qos0_msg": 0,
  • "delivery.dropped.queue_full": 0,
  • "delivery.dropped.expired": 0,
  • "client.connect": 0,
  • "client.connack": 0,
  • "client.connected": 0,
  • "client.authenticate": 0,
  • "client.auth.anonymous": 0,
  • "client.authorize": 0,
  • "client.subscribe": 0,
  • "client.unsubscribe": 0,
  • "client.disconnected": 0,
  • "session.created": 0,
  • "session.resumed": 0,
  • "session.takenover": 0,
  • "session.discarded": 0,
  • "session.terminated": 0,
  • "authorization.allow": 0,
  • "authorization.deny": 0,
  • "authorization.cache_hit": 0,
  • "authorization.cache_miss": 0,
  • "authentication.success": 0,
  • "authentication.success.anonymous": 0,
  • "authentication.failure": 0,
  • "overload_protection.delay.ok": 0,
  • "overload_protection.delay.timeout": 0,
  • "overload_protection.hibernation": 0,
  • "overload_protection.gc": 0,
  • "overload_protection.new_conn": 0
}

Get node info

Get node info

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "connections": 0,
  • "live_connections": 0,
  • "cluster_sessions": 0,
  • "load1": 2.66,
  • "load5": 2.66,
  • "load15": 2.66,
  • "max_fds": 1024,
  • "memory_total": "512.00M",
  • "memory_used": "256.00M",
  • "node_status": "running",
  • "otp_release": "24.2/12.2",
  • "process_available": 2097152,
  • "process_used": 1024,
  • "uptime": 5120000,
  • "version": "5.0.0",
  • "edition": "Opensource",
  • "sys_path": "path/to/emqx",
  • "log_path": "path/to/log | The log path is not yet set",
  • "role": "core"
}

List EMQX nodes

List EMQX nodes

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ExHook

Get the detail information of Exhook server

Get the detail information of Exhook server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "hooks": [
    ],
  • "name": "default",
  • "enable": true,
  • "url": "http://127.0.0.1:9000",
  • "request_timeout": "12m",
  • "failed_action": "deny",
  • "ssl": {
    },
  • "socket_options": {
    },
  • "auto_reconnect": "60s",
  • "pool_size": 8
}

Update the server

Update the server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Request Body schema: application/json
name
required
string

Name of the exhook server

enable
boolean
Default: true

Enable this Exhook server

url
required
string

URL of the gRPC server

request_timeout
string
Default: "5s"

The timeout of request gRPC server

failed_action
string
Default: "deny"
Enum: "deny" "ignore"

The value that is returned when the request to the gRPC server fails for any reason

object (exhook.ssl_conf)
object (exhook.socket_options)
string or string
Default: "60s"

Whether to automatically reconnect (initialize) the gRPC server.
When gRPC is not available, Exhook tries to request the gRPC service at that interval and reinitialize the list of mounted hooks.

pool_size
integer >= 1
Default: 8

The process pool size for gRPC client

Responses

Request samples

Content type
application/json
{
  • "name": "default",
  • "ssl": {
    },
  • "pool_size": 8,
  • "enable": true,
  • "url": "http://127.0.0.1:8081",
  • "request_timeout": "5s",
  • "auto_reconnect": "60s",
  • "failed_action": "deny"
}

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "hooks": [
    ],
  • "name": "default",
  • "enable": true,
  • "url": "http://127.0.0.1:9000",
  • "request_timeout": "12m",
  • "failed_action": "deny",
  • "ssl": {
    },
  • "socket_options": {
    },
  • "auto_reconnect": "60s",
  • "pool_size": 8
}

Delete the server

Delete the server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Move the server.<br/>NOTE: The position should be

Move the server.
NOTE: The position should be "front | rear | before:{name} | after:{name}

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Request Body schema: application/json
position
required
string

The target position to be moved

Responses

Request samples

Content type
application/json
Example
{
  • "position": "rear"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List all servers

List all servers

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a server

Add a server

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
required
string

Name of the exhook server

enable
boolean
Default: true

Enable this Exhook server

url
required
string

URL of the gRPC server

request_timeout
string
Default: "5s"

The timeout of request gRPC server

failed_action
string
Default: "deny"
Enum: "deny" "ignore"

The value that is returned when the request to the gRPC server fails for any reason

object (exhook.ssl_conf)
object (exhook.socket_options)
string or string
Default: "60s"

Whether to automatically reconnect (initialize) the gRPC server.
When gRPC is not available, Exhook tries to request the gRPC service at that interval and reinitialize the list of mounted hooks.

pool_size
integer >= 1
Default: 8

The process pool size for gRPC client

Responses

Request samples

Content type
application/json
{
  • "name": "default",
  • "ssl": {
    },
  • "pool_size": 8,
  • "enable": true,
  • "url": "http://127.0.0.1:8081",
  • "request_timeout": "5s",
  • "auto_reconnect": "60s",
  • "failed_action": "deny"
}

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "hooks": [
    ],
  • "name": "default",
  • "enable": true,
  • "url": "http://127.0.0.1:9000",
  • "request_timeout": "12m",
  • "failed_action": "deny",
  • "ssl": {
    },
  • "socket_options": {
    },
  • "auto_reconnect": "60s",
  • "pool_size": 8
}

Get the hooks information of server

Get the hooks information of server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Monitor

Get Prometheus config info

Get Prometheus config info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "collectors": {
    },
  • "enable_basic_auth": false,
  • "push_gateway": {
    }
}

Update Prometheus config

Update Prometheus config

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
push_gateway_server
required
string
Default: "http://127.0.0.1:9091"

Deprecated since 5.4.0, use prometheus.push_gateway.url instead

interval
required
string
Default: "15s"

Deprecated since 5.4.0, use prometheus.push_gateway.interval instead

headers
object
Default: {}

Deprecated since 5.4.0, use prometheus.push_gateway.headers instead

job_name
required
string
Default: "${name}/instance/${name}~${host}"

Deprecated since 5.4.0, use prometheus.push_gateway.job_name instead

enable
required
boolean
Default: false

Deprecated since 5.4.0, use prometheus.push_gateway.url instead

vm_dist_collector
required
string
Default: "disabled"
Enum: "disabled" "enabled"

Deprecated since 5.4.0, use prometheus.collectors.vm_dist instead

mnesia_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

Deprecated since 5.4.0, use prometheus.collectors.mnesia instead

vm_statistics_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

Deprecated since 5.4.0, use prometheus.collectors.vm_statistics instead

vm_system_info_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

Deprecated, use prometheus.collectors.vm_system_info instead

vm_memory_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

Deprecated since 5.4.0, use prometheus.collectors.vm_memory instead

vm_msacc_collector
required
string
Default: "disabled"
Enum: "enabled" "disabled"

Deprecated since 5.4.0, use prometheus.collectors.vm_msacc instead

Responses

Request samples

Content type
application/json
Example
{
  • "collectors": {
    },
  • "enable_basic_auth": false,
  • "push_gateway": {
    }
}

Response samples

Content type
application/json
{
  • "collectors": {
    },
  • "enable_basic_auth": false,
  • "push_gateway": {
    }
}

Get Prometheus Metrics for Data Integration

Get Prometheus Metrics for Data Integration

query Parameters
mode
string
Default: "node"
Enum: "node" "all_nodes_aggregated" "all_nodes_unaggregated"
Example: mode=node


Metrics format mode.

node:
Return metrics from local node. And it is the default behaviour if mode not specified.

all_nodes_aggregated:
Return metrics for all nodes.
And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.

all_nodes_unaggregated:
Return metrics from all nodes, and the metrics are not aggregated.
The node name will be included in the returned results to
indicate that certain metrics were returned on a certain node.

Responses

Response samples

Content type
No sample

Get Prometheus Metrics

Get Prometheus Metrics

query Parameters
mode
string
Default: "node"
Enum: "node" "all_nodes_aggregated" "all_nodes_unaggregated"
Example: mode=node


Metrics format mode.

node:
Return metrics from local node. And it is the default behaviour if mode not specified.

all_nodes_aggregated:
Return metrics for all nodes.
And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.

all_nodes_unaggregated:
Return metrics from all nodes, and the metrics are not aggregated.
The node name will be included in the returned results to
indicate that certain metrics were returned on a certain node.

Responses

Response samples

Content type
No sample

Get Prometheus Metrics for AuthN, AuthZ and Banned

Get Prometheus Metrics for AuthN, AuthZ and Banned

query Parameters
mode
string
Default: "node"
Enum: "node" "all_nodes_aggregated" "all_nodes_unaggregated"
Example: mode=node


Metrics format mode.

node:
Return metrics from local node. And it is the default behaviour if mode not specified.

all_nodes_aggregated:
Return metrics for all nodes.
And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.

all_nodes_unaggregated:
Return metrics from all nodes, and the metrics are not aggregated.
The node name will be included in the returned results to
indicate that certain metrics were returned on a certain node.

Responses

Response samples

Content type
No sample

Auto Subscribe

Get auto subscribe topic list

Get auto subscribe topic list

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update auto subscribe topic list

Update auto subscribe topic list

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
topic
required
string

Topic name, placeholders are supported. For example: client/${clientid}/username/${username}/host/${host}/port/${port}
Required field, and cannot be empty string

qos
integer [ 0 .. 2 ]
Default: 0

Default value 0. Quality of service.
At most once (0)
At least once (1)
Exactly once (2)

rh
integer [ 0 .. 2 ]
Default: 0

Default value 0. This option is used to specify whether the server forwards the retained message to the client when establishing a subscription.
Retain Handling is equal to 0, as long as the client successfully subscribes, the server will send the retained message.
Retain Handling is equal to 1, if the client successfully subscribes and this subscription does not exist previously, the server sends the retained message. After all, sometimes the client re-initiate the subscription just to change the QoS, but it does not mean that it wants to receive the reserved messages again.
Retain Handling is equal to 2, even if the client successfully subscribes, the server does not send the retained message.

rap
integer [ 0 .. 1 ]
Default: 0

Default value 0. This option is used to specify whether the server retains the RETAIN mark when forwarding messages to the client, and this option does not affect the RETAIN mark in the retained message. Therefore, when the option Retain As Publish is set to 0, the client will directly distinguish whether this is a normal forwarded message or a retained message according to the RETAIN mark in the message, instead of judging whether this message is the first received after subscribing(the forwarded message may be sent before the retained message, which depends on the specific implementation of different brokers).

nl
integer [ 0 .. 1 ]
Default: 0

Default value 0.
MQTT v3.1.1: if you subscribe to the topic published by yourself, you will receive all messages that you published.
MQTT v5: if you set this option as 1 when subscribing, the server will not forward the message you published to you.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Gateway Listeners

Get the listener's authenticator

Get the listener's authenticator configs.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Responses

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Update config of authenticator for listener

Update authenticator configs for the listener, or disable/enable it.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Request Body schema: application/json
One of
mechanism
required
string
Value: "password_based"

Authentication mechanism.

backend
required
string
Value: "ldap"

Backend type.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

Indicates which attribute is used to represent the user's password.

is_superuser_attribute
string
Default: "isSuperuser"

Indicates which attribute is used to represent whether the user is a superuser.

Responses

Request samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Delete the listener's authenticator

Remove authenticator for the listener.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Create authenticator for listener

Enable authenticator for specified listener for client authentication.

When authenticator is enabled for a listener, all clients connecting to that listener will use that authenticator for authentication.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Request Body schema: application/json
One of
mechanism
required
string
Value: "password_based"

Authentication mechanism.

backend
required
string
Value: "ldap"

Backend type.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

Indicates which attribute is used to represent the user's password.

is_superuser_attribute
string
Default: "isSuperuser"

Indicates which attribute is used to represent whether the user is a superuser.

Responses

Request samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

List all listeners

Gets a list of gateway listeners. This interface returns all the configs of the listener (including the authenticator on that listener), as well as the status of that listener running in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Add listener

Create the gateway listener.

Note: For listener types not supported by a gateway, this API returns 400: BAD_REQUEST.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Request Body schema: application/json
One of
id
string

Listener ID

type
string
Value: "wss"

Listener Type

name
string

Listener Name

running
boolean

Listener Running status

acceptors
integer
Default: 16

Size of the acceptor pool.

object (emqx.tcp_opts)
proxy_protocol
boolean
Default: false

If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP,
this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.
EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.

For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

Timeout for proxy protocol.
EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

enable
boolean
Default: true

Enable the listener.

bind
string

The IP address and port that the listener will bind.

string or integer
Default: 1024

The maximum number of concurrent connections allowed by the listener.

max_conn_rate
integer
Default: 1000

Maximum connections per second.

enable_authn
boolean
Default: true

Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.

mountpoint
string

When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber.
The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant,
then the client actually subscribes to the topic some_tenant/t.
Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t,
the message is routed to all the clients subscribed some_tenant/t,
so client A will receive the message, with topic name t. Set to "" to disable the feature.
Supported placeholders in mountpoint string:

- ${clientid}: clientid

- ${username}: username

- ${endpoint_name}: endpoint name

access_rules
Array of strings
Default: []

An access rule list consisting of string rules to restrict or allow access from some addresses.
The rules that appear earlier in the list are matched first.
The format is allow | deny <address> | <CIDR> | all.

For example:

["deny 192.168.1.1", "allow 192.168.1.0/24", "deny all"]

object (emqx.listener_wss_opts)
object (gateway.websocket)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Get listener config

Get the gateway listener configs

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Responses

Response samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Update listener config

Update the gateway listener. The listener being updated performs a restart and all clients connected to that listener will be disconnected.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Request Body schema: application/json
One of
id
string

Listener ID

type
string
Value: "wss"

Listener Type

name
string

Listener Name

running
boolean

Listener Running status

acceptors
integer
Default: 16

Size of the acceptor pool.

object (emqx.tcp_opts)
proxy_protocol
boolean
Default: false

If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP,
this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.
EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.

For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

Timeout for proxy protocol.
EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.

enable
boolean
Default: true

Enable the listener.

bind
string

The IP address and port that the listener will bind.

string or integer
Default: 1024

The maximum number of concurrent connections allowed by the listener.

max_conn_rate
integer
Default: 1000

Maximum connections per second.

enable_authn
boolean
Default: true

Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.

mountpoint
string

When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber.
The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant,
then the client actually subscribes to the topic some_tenant/t.
Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t,
the message is routed to all the clients subscribed some_tenant/t,
so client A will receive the message, with topic name t. Set to "" to disable the feature.
Supported placeholders in mountpoint string:

- ${clientid}: clientid

- ${username}: username

- ${endpoint_name}: endpoint name

access_rules
Array of strings
Default: []

An access rule list consisting of string rules to restrict or allow access from some addresses.
The rules that appear earlier in the list are matched first.
The format is allow | deny <address> | <CIDR> | all.

For example:

["deny 192.168.1.1", "allow 192.168.1.0/24", "deny all"]

object (emqx.listener_wss_opts)
object (gateway.websocket)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "udp-def",
  • "type": "udp",
  • "bind": "22212",
  • "udp_options": {
    }
}

Delete listener

Delete the gateway listener. All connected clients under the deleted listener will be disconnected.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get user info

Get user info from the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

uid
required
string

User ID

Responses

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Update user info

Update the user info for the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

uid
required
string

User ID

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Delete user

Delete the user for the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

uid
required
string

User ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List authenticator's users

Get the users for the authenticator (only supported by built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Add user for an authenticator

Add user for the authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string

Listener ID

Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Configs

Get the sub-configurations under *sys_topics*

Get the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "sys_msg_interval": "1m",
  • "sys_heartbeat_interval": "30s",
  • "sys_event_messages": {
    }
}

Update the sub-configurations under *sys_topics*

Update the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
string or string
Default: "1m"

Time interval for publishing following system messages:
- $SYS/brokers
- $SYS/brokers/<node>/version
- $SYS/brokers/<node>/sysdescr
- $SYS/brokers/<node>/stats/<name>
- $SYS/brokers/<node>/metrics/<name>

string or string
Default: "30s"

Time interval for publishing following heartbeat messages:
- $SYS/brokers/<node>/uptime
- $SYS/brokers/<node>/datetime

object (emqx.event_names)

Responses

Request samples

Content type
application/json
{
  • "sys_msg_interval": "1m",
  • "sys_heartbeat_interval": "30s",
  • "sys_event_messages": {
    }
}

Response samples

Content type
application/json
{
  • "sys_msg_interval": "1m",
  • "sys_heartbeat_interval": "30s",
  • "sys_event_messages": {
    }
}

Get the sub-configurations under *sysmon*

Get the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "vm": {
    },
  • "os": {
    },
  • "mnesia_tm_mailbox_size_alarm_threshold": 500,
  • "broker_pool_mailbox_size_alarm_threshold": 500
}

Update the sub-configurations under *sysmon*

Update the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx.sysmon_vm)
object (emqx.sysmon_os)
mnesia_tm_mailbox_size_alarm_threshold
integer >= 1
Default: 500

The threshold above which an alarm is raised for the mailbox size of the mnesia transaction manager. This process handles all transactions in EMQX's internal database mnesia.

There are several reasons that could give raise to this alarm. A few things to check for or consider:
- Lower max_conn_rate, so that clients join at a slower pace;
- Increase CPU / RAM resources for EMQX;
- Lower retained message rate from the client side;
- Check if intra-cluster network bandwidth is reaching a maximum.

broker_pool_mailbox_size_alarm_threshold
integer >= 1
Default: 500

The threshold above which an alarm is raised for the maximum mailbox size among the broker pool workers. Broker pool workers handle adding and removing subscriptions, and replication of routing information.

There are several reasons that could give raise to this alarm. A few things to check for or consider:
- Increase CPU / RAM resources for EMQX;
- Review the subscriptions that clients are doing, for example, try to compact topic filters;
- Check if intra-cluster network bandwidth is reaching a maximum.

Responses

Request samples

Content type
application/json
{
  • "vm": {
    },
  • "os": {
    },
  • "mnesia_tm_mailbox_size_alarm_threshold": 500,
  • "broker_pool_mailbox_size_alarm_threshold": 500
}

Response samples

Content type
application/json
{
  • "vm": {
    },
  • "os": {
    },
  • "mnesia_tm_mailbox_size_alarm_threshold": 500,
  • "broker_pool_mailbox_size_alarm_threshold": 500
}

Get the MQTT-related configuration

Get the MQTT-related configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "mqtt": {
    },
  • "flapping_detect": {
    },
  • "force_shutdown": {
    },
  • "force_gc": {
    },
  • "durable_sessions": {
    }
}

Update MQTT-related configuration

Update MQTT-related configuration

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx.mqtt)
object (emqx.flapping_detect)
object (emqx.force_shutdown)
object (emqx.force_gc)
object (emqx.durable_sessions)

Responses

Request samples

Content type
application/json
{
  • "mqtt": {
    },
  • "flapping_detect": {
    },
  • "force_shutdown": {
    },
  • "force_gc": {
    },
  • "durable_sessions": {
    }
}

Response samples

Content type
application/json
{
  • "mqtt": {
    },
  • "flapping_detect": {
    },
  • "force_shutdown": {
    },
  • "force_gc": {
    },
  • "durable_sessions": {
    }
}

Get the sub-configurations under *alarm*

Get the sub-configurations under alarm

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "size_limit": 1000,
  • "validity_period": "24h"
}

Update the sub-configurations under *alarm*

Update the sub-configurations under alarm

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
actions
Array of strings
Default: ["log","publish"]
Items Enum: "log" "publish"

The actions triggered when the alarm is activated.
Currently, the following actions are supported: log and publish.
log is to write the alarm to log (console or file).
publish is to publish the alarm as an MQTT message to the system topics:
$SYS/brokers/emqx@xx.xx.xx.x/alarms/activate and
$SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivate

size_limit
integer [ 1 .. 3000 ]
Default: 1000

The maximum number of historical alarms that can be stored.

When the maximum number is reached, the oldest historical alarms will be deleted to store new historical alarms.

validity_period
string
Default: "24h"

The validity period of historical alarms. Calculated from the time of activation of the historical alarm instead of the time of cancelation.

If it exists longer than the validity period, the alarm will be deleted.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "size_limit": 1000,
  • "validity_period": "24h"
}

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "size_limit": 1000,
  • "validity_period": "24h"
}

Get the sub-configurations under *dashboard*

Get the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "listeners": {
    },
  • "default_password": "public",
  • "token_expired_time": "12m",
  • "cors": false,
  • "swagger_support": true
}

Update the sub-configurations under *dashboard*

Update the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (dashboard.listeners)
token_expired_time
string
Default: "60m"

JWT token expiration time. Default is 60 minutes

cors
boolean
Default: false

Support Cross-Origin Resource Sharing (CORS).
Allows a server to indicate any origins (domain, scheme, or port) other than
its own from which a browser should permit loading resources.

swagger_support
boolean
Default: true

Enable or disable support for swagger API documentation.

Responses

Request samples

Content type
application/json
{
  • "listeners": {
    },
  • "token_expired_time": "12m",
  • "cors": false,
  • "swagger_support": true
}

Response samples

Content type
application/json
{
  • "listeners": {
    },
  • "default_password": "public",
  • "token_expired_time": "12m",
  • "cors": false,
  • "swagger_support": true
}

Get the sub-configurations under *broker*

Get the sub-configurations under broker

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable_session_registry": true,
  • "session_history_retain": "1h"
}

Update the sub-configurations under *broker*

Update the sub-configurations under broker

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable_session_registry
boolean
Default: true

The Global Session Registry is a cluster-wide mechanism designed to maintain the uniqueness of client IDs within the cluster.
Recommendations for Use

- Default Setting: It is generally advisable to enable. This feature is crucial for session takeover to work properly. For example if a client reconnected to another node in the cluster, the new connection will need to find the old session and take it over.
- Disabling the Feature: Disabling is an option for scenarios when all sessions expire immediately after client is disconnected (i.e. session expiry interval is zero). This can be relevant in certain specialized use cases.

Advantages of Disabling

- Reduced Memory Usage: Turning off the session registry can lower the overall memory footprint of the system.
- Improved Performance: Without the overhead of maintaining a global registry, the node can process client connections faster.

session_history_retain
string
Default: "0s"

The duration to retain the session registration history. Setting this to a value greater than 0s will increase memory usage and impact peformance.
This retained history can be used to monitor how many sessions were registered in the past configured duration.
Note: This config has no effect if enable_session_registry is set to false.

Note: If the clients are using random client IDs, it's not recommended to enable this feature, at least not for a long retention period.

Note: When clustered, the lowest (but greater than 0s) value among the nodes in the cluster will take effect.

Responses

Request samples

Content type
application/json
{
  • "enable_session_registry": true,
  • "session_history_retain": "1h"
}

Response samples

Content type
application/json
{
  • "enable_session_registry": true,
  • "session_history_retain": "1h"
}

Reset the config entry specified by the query stri

Reset the config entry specified by the query string parameter conf_path.

- For a config entry that has default value, this resets it to the default value;
- For a config entry that has no default value, an error 400 will be returned

Authorizations:
basicAuthbearerAuth
path Parameters
rootname
required
string
Enum: "broker" "log" "sysmon" "sys_topics" "alarm" "dashboard"
Example: sysmon
query Parameters
conf_path
string
Example: conf_path=os.sysmem_high_watermark

The config path separated by '.' character

Responses

Response samples

Content type
application/json
{
  • "code": "NO_DEFAULT_VALUE",
  • "message": "string"
}

Get all the configurations of the specified keys,

Get all the configurations of the specified keys, including hot and non-hot updatable items.

Authorizations:
basicAuthbearerAuth
query Parameters
key
string
Enum: "actions" "alarm" "api_key" "authentication" "authorization" "auto_subscribe" "banned" "bridges" "cluster" "conn_congestion" "connectors" "crl_cache" "dashboard" "delayed" "durable_sessions" "durable_storage" "exhook" "flapping_detect" "force_gc" "force_shutdown" "gateway" "limiter" "listeners" "log" "mqtt" "node" "overload_protection" "prometheus" "psk_authentication" "retainer" "rewrite" "rpc" "rule_engine" "slow_subs" "sources" "sys_topics" "sysmon" "telemetry" "topic_metrics"
Example: key=sysmon
node
string

Node's name. Will deprecated in 5.2.0.

Responses

Response samples

Content type
No sample

Update the configurations of the specified keys.

Update the configurations of the specified keys.

Authorizations:
basicAuthbearerAuth
query Parameters
mode
string
Default: "merge"
Enum: "replace" "merge"
ignore_readonly
boolean
Default: false
Request Body schema: text/plain
string

Responses

Response samples

Content type
application/json
{
  • "code": "UPDATE_FAILED",
  • "message": "string"
}

Get the sub-configurations under *log*

Get the sub-configurations under log

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "console": {
    },
  • "file": {
    },
  • "throttling": {
    }
}

Update the sub-configurations under *log*

Update the sub-configurations under log

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx.console_handler)
object or emqx.log_file_handler (object)
Default: {"level":"warning"}

File-based log handlers.

object (emqx.log_throttling)

Responses

Request samples

Content type
application/json
{
  • "console": {
    },
  • "file": {
    },
  • "throttling": {
    }
}

Response samples

Content type
application/json
{
  • "console": {
    },
  • "file": {
    },
  • "throttling": {
    }
}

Clients

Kick out a batch of client by client IDs

Kick out a batch of client by client IDs

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "emqx_clientid_985bb09d",
  • "emqx_clientid_211cc01c"
]

Get the total number of sessions in the cluster.<b

Get the total number of sessions in the cluster.
By default, it includes only those sessions that have not expired.
If the broker.session_history_retain config is set to a duration greater than 0s,
this count will also include sessions that expired within the specified retain time.
By specifying the since parameter, it can return the number of sessions that have expired within the specified time.

Authorizations:
basicAuthbearerAuth
query Parameters
since
integer >= 0
Default: 0
Example: since=1705391625

Include sessions expired after this time (UNIX Epoch in seconds precision)

Responses

Response samples

Content type
application/json
"string"

Get client authz cache in the cluster.

Get client authz cache in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "access": "publish",
  • "result": "allow",
  • "topic": "testtopic/1",
  • "updated_time": 1687850712989
}

Clean client authz cache in the cluster.

Clean client authz cache in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Get clients info by client ID

Get clients info by client ID

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "heap_size": 610,
  • "send_msg.dropped.expired": 0,
  • "send_oct": 31,
  • "recv_msg.qos1": 0,
  • "is_persistent": false,
  • "send_pkt": 4,
  • "clean_start": true,
  • "inflight_cnt": 0,
  • "node": "emqx@127.0.0.1",
  • "send_msg.dropped.queue_full": 0,
  • "awaiting_rel_cnt": 0,
  • "inflight_max": 32,
  • "created_at": "2024-01-01T12:34:56.789+08:00",
  • "subscriptions_cnt": 1,
  • "mailbox_len": 0,
  • "send_cnt": 4,
  • "connected": true,
  • "ip_address": "127.0.0.1",
  • "awaiting_rel_max": 100,
  • "recv_msg.qos2": 0,
  • "proto_ver": 5,
  • "mountpoint": "null",
  • "proto_name": "MQTT",
  • "durable": false,
  • "port": 52571,
  • "connected_at": "2024-01-01T12:34:56.789+08:00",
  • "enable_authn": true,
  • "expiry_interval": 0,
  • "username": null,
  • "recv_msg": 0,
  • "recv_oct": 49,
  • "send_msg.dropped.too_large": 0,
  • "keepalive": 60,
  • "send_msg.qos1": 0,
  • "send_msg.qos2": 0,
  • "recv_msg.qos0": 0,
  • "send_msg.qos0": 0,
  • "subscriptions_max": "infinity",
  • "mqueue_max": 1000,
  • "mqueue_dropped": 0,
  • "clientid": "01",
  • "is_bridge": false,
  • "peerport": 52571,
  • "send_msg": 0,
  • "listener": "tcp:default",
  • "recv_cnt": 4,
  • "recv_pkt": 4,
  • "recv_msg.dropped": 0,
  • "send_msg.dropped": 0,
  • "recv_msg.dropped.await_pubrel_timeout": 0,
  • "reductions": 6836,
  • "mqueue_len": 0
}

Kick out client by client ID

Kick out client by client ID

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Unsubscribe bulk

Unsubscribe bulk

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
topic
string

Topic

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Subscribe bulk

Subscribe bulk

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
topic
required
string

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Subscribe

Subscribe

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
topic
required
string

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/#",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0
}

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "topic": "testtopic/1",
  • "clientid": "emqx_clientid_xx128cdhfc",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0,
  • "durable": false
}

Get client mqueue messages

Get client mqueue messages

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

Client's inflight/mqueue messages payload encoding. If set to none, no payload is returned in the response.

max_payload_bytes
string
Default: "1MB"
Example: max_payload_bytes=32MB

Client's inflight/mqueue messages payload limit. The total payload size of all messages in the response will not exceed this value. Messages beyond the limit will be silently omitted in the response. The only exception to this rule is when the first message payload is already larger than the limit. In this case, the first message will be returned in the response.

string or string or string
Example: position=none

An opaque token that can then be in subsequent requests to get the next chunk of results: "?position={prev_response.meta.position}"
It is used instead of "page" parameter to traverse highly volatile data.
Can be omitted or set to "none" to get the first chunk of data.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get client in-flight messages

Get client in-flight messages

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

Client's inflight/mqueue messages payload encoding. If set to none, no payload is returned in the response.

max_payload_bytes
string
Default: "1MB"
Example: max_payload_bytes=32MB

Client's inflight/mqueue messages payload limit. The total payload size of all messages in the response will not exceed this value. Messages beyond the limit will be silently omitted in the response. The only exception to this rule is when the first message payload is already larger than the limit. In this case, the first message will be returned in the response.

string or string or string
Example: position=none

An opaque token that can then be in subsequent requests to get the next chunk of results: "?position={prev_response.meta.position}"
It is used instead of "page" parameter to traverse highly volatile data.
Can be omitted or set to "none" to get the first chunk of data.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Unsubscribe

Unsubscribe

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
topic
string

Topic

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/#"
}

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Get client subscriptions

Get client subscriptions

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List clients

List clients

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

node
string
Example: node=emqx@127.0.0.1

Node name

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

username
Array of strings

User name, multiple values can be specified by repeating the parameter: username=u1&username=u2

ip_address
string
Example: ip_address=127.0.0.1

Client's IP address

conn_state
string
Enum: "connected" "idle" "disconnected"

The current connection status of the client, the possible values are connected,idle,disconnected

clean_start
boolean

Whether the client uses a new session

proto_ver
string

Client protocol version

like_clientid
string

Fuzzy search clientid as substring

like_username
string

Fuzzy search username as substring

integer or string

Search client session creation time by greater than or equal method, rfc3339 or timestamp(millisecond)

integer or string

Search client session creation time by less than or equal method, rfc3339 or timestamp(millisecond)

integer or string

Search client connection creation time by greater than or equal method, rfc3339 or timestamp(epoch millisecond)

integer or string

Search client connection creation time by less than or equal method, rfc3339 or timestamp(millisecond)

clientid
Array of strings

Client ID, multiple values can be specified by repeating the parameter: clientid=c1&clientid=c2

Array of strings or string
Default: "all"

Comma separated list of client fields to return in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Connectors

Test creating connector

Test creating a new connector.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"

The type of the connector.

name
required
string

The name of the connector.

enable
boolean
Default: true

Enable (true) or disable (false) this connector.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

pool_size
integer >= 1
Default: 8

Size of the pool of MQTT clients that will publish messages to the remote broker.

Each MQTT client will be assigned 'clientid' of the form '${clientid_prefix}:${bridge_name}:egress:${node}:${n}'
where 'n' is the number of a client inside the pool.

This option does not take effect if static_clientids is not empty. When static client IDs is in use, pool size is always derived from the number of assigned IDs for each node.

object (connector_mqtt.resource_opts)
mode
string
Deprecated
Default: "cluster_shareload"
Value: "cluster_shareload"

The mode of the MQTT Bridge.

- cluster_shareload: create an MQTT connection on each node in the emqx cluster.

In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
using shared subscription.

Note that the 'clientid' is suffixed by the node name, this is to avoid
clientid conflicts between different nodes. And we can only use shared subscription
topic filters for remote.topic of ingress connections.

server
required
string

The host and port of the remote MQTT broker

clientid_prefix
string

Optional prefix to prepend to the clientid used by egress bridges.
Does not apply if static_clientids is used.

Array of objects (connector_mqtt.static_clientid_entry)
Default: []

Entries mapping EMQX node names to static client IDs.

If any entries are defined, then only EMQX nodes matching those entries will start MQTT clients with the corresponding clientids.

reconnect_interval
string
Deprecated
proto_ver
string
Default: "v4"
Enum: "v3" "v4" "v5"

The MQTT protocol version

bridge_mode
boolean
Default: false

If enable bridge mode.
NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT
broker MUST support this feature.
If bridge_mode is set to true, the bridge will indicate to the remote broker that it is a bridge not an ordinary client.
This means that loop detection will be more effective and that retained messages will be propagated correctly.

username
string

The username of the MQTT protocol

password
string <password>

The password of the MQTT protocol

clean_start
boolean
Default: true

Whether to start a clean session when reconnecting a remote broker for ingress bridge

keepalive
string
Default: "160s"

MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

connect_timeout
string
Default: "10s"

Timeout for connecting to the remote broker. The connection worker process is blocked up to this amount of time when attempting the initial connection.

retry_interval
string
Default: "15s"

Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

max_inflight
integer >= 0
Default: 32

Max inflight (sent, but un-acked) messages of the MQTT protocol

object (emqx.ssl_client_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_connector",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

Get connector

Get a connector by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "my_http_connector",
  • "status": "connected",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "node_status": [
    ],
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Update connector

Update a connector by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

Request Body schema: application/json
One of
enable
boolean
Default: true

Enable (true) or disable (false) this connector.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

pool_size
integer >= 1
Default: 8

Size of the pool of MQTT clients that will publish messages to the remote broker.

Each MQTT client will be assigned 'clientid' of the form '${clientid_prefix}:${bridge_name}:egress:${node}:${n}'
where 'n' is the number of a client inside the pool.

This option does not take effect if static_clientids is not empty. When static client IDs is in use, pool size is always derived from the number of assigned IDs for each node.

object (connector_mqtt.resource_opts)
mode
string
Deprecated
Default: "cluster_shareload"
Value: "cluster_shareload"

The mode of the MQTT Bridge.

- cluster_shareload: create an MQTT connection on each node in the emqx cluster.

In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
using shared subscription.

Note that the 'clientid' is suffixed by the node name, this is to avoid
clientid conflicts between different nodes. And we can only use shared subscription
topic filters for remote.topic of ingress connections.

server
required
string

The host and port of the remote MQTT broker

clientid_prefix
string

Optional prefix to prepend to the clientid used by egress bridges.
Does not apply if static_clientids is used.

Array of objects (connector_mqtt.static_clientid_entry)
Default: []

Entries mapping EMQX node names to static client IDs.

If any entries are defined, then only EMQX nodes matching those entries will start MQTT clients with the corresponding clientids.

reconnect_interval
string
Deprecated
proto_ver
string
Default: "v4"
Enum: "v3" "v4" "v5"

The MQTT protocol version

bridge_mode
boolean
Default: false

If enable bridge mode.
NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT
broker MUST support this feature.
If bridge_mode is set to true, the bridge will indicate to the remote broker that it is a bridge not an ordinary client.
This means that loop detection will be more effective and that retained messages will be propagated correctly.

username
string

The username of the MQTT protocol

password
string <password>

The password of the MQTT protocol

clean_start
boolean
Default: true

Whether to start a clean session when reconnecting a remote broker for ingress bridge

keepalive
string
Default: "160s"

MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

connect_timeout
string
Default: "10s"

Timeout for connecting to the remote broker. The connection worker process is blocked up to this amount of time when attempting the initial connection.

retry_interval
string
Default: "15s"

Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

max_inflight
integer >= 0
Default: 32

Max inflight (sent, but un-acked) messages of the MQTT protocol

object (emqx.ssl_client_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_connector",
  • "status": "connected",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "node_status": [
    ],
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Delete connector

Delete a connector by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Manually start a connector

Start connector on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Manually start a connector on a given node

Start connector on a specific node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

The node name, e.g. 'emqx@127.0.0.1'.

id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Enable or disable connector

Enable or Disable connector on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

enable
required
boolean
Example: true

Whether to enable this connector.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List connectors

List all created connectors.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create connector

Create a new connector by type and name.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"

The type of the connector.

name
required
string

The name of the connector.

enable
boolean
Default: true

Enable (true) or disable (false) this connector.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

pool_size
integer >= 1
Default: 8

Size of the pool of MQTT clients that will publish messages to the remote broker.

Each MQTT client will be assigned 'clientid' of the form '${clientid_prefix}:${bridge_name}:egress:${node}:${n}'
where 'n' is the number of a client inside the pool.

This option does not take effect if static_clientids is not empty. When static client IDs is in use, pool size is always derived from the number of assigned IDs for each node.

object (connector_mqtt.resource_opts)
mode
string
Deprecated
Default: "cluster_shareload"
Value: "cluster_shareload"

The mode of the MQTT Bridge.

- cluster_shareload: create an MQTT connection on each node in the emqx cluster.

In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
using shared subscription.

Note that the 'clientid' is suffixed by the node name, this is to avoid
clientid conflicts between different nodes. And we can only use shared subscription
topic filters for remote.topic of ingress connections.

server
required
string

The host and port of the remote MQTT broker

clientid_prefix
string

Optional prefix to prepend to the clientid used by egress bridges.
Does not apply if static_clientids is used.

Array of objects (connector_mqtt.static_clientid_entry)
Default: []

Entries mapping EMQX node names to static client IDs.

If any entries are defined, then only EMQX nodes matching those entries will start MQTT clients with the corresponding clientids.

reconnect_interval
string
Deprecated
proto_ver
string
Default: "v4"
Enum: "v3" "v4" "v5"

The MQTT protocol version

bridge_mode
boolean
Default: false

If enable bridge mode.
NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT
broker MUST support this feature.
If bridge_mode is set to true, the bridge will indicate to the remote broker that it is a bridge not an ordinary client.
This means that loop detection will be more effective and that retained messages will be propagated correctly.

username
string

The username of the MQTT protocol

password
string <password>

The password of the MQTT protocol

clean_start
boolean
Default: true

Whether to start a clean session when reconnecting a remote broker for ingress bridge

keepalive
string
Default: "160s"

MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

connect_timeout
string
Default: "10s"

Timeout for connecting to the remote broker. The connection worker process is blocked up to this amount of time when attempting the initial connection.

retry_interval
string
Default: "15s"

Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- ms for milliseconds,
- s for seconds,
- m for minutes,
- h for hours;

or combination of whereof: 1h5m0s

max_inflight
integer >= 0
Default: 32

Max inflight (sent, but un-acked) messages of the MQTT protocol

object (emqx.ssl_client_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_connector",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_connector",
  • "status": "connected",
  • "type": "http",
  • "connect_timeout": "15s",
  • "pool_size": 1,
  • "enable": true,
  • "headers": {
    },
  • "url": "http://localhost:8080/api/v1",
  • "node_status": [
    ],
  • "pool_type": "hash",
  • "enable_pipelining": 100
}

Sources

Manually start a bridge on a given node

Start bridge on a specific node.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

The node name, e.g. 'emqx@127.0.0.1'.

id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List sources

List all created bridges.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create source

Create a new bridge by type and name.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"
name
required
string
required
object (bridge_mqtt_publisher.ingress_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (bridge_mqtt_publisher.source_resource_opts)

Responses

Request samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "status": "connected",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Get source

Get a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "status": "connected",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Update source

Update a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Request Body schema: application/json
One of
required
object (bridge_mqtt_publisher.ingress_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (bridge_mqtt_publisher.source_resource_opts)

Responses

Request samples

Content type
application/json
{
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "status": "connected",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Delete source

Delete a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

query Parameters
also_delete_dep_actions
boolean
Default: false

Whether to cascade delete dependent actions.

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List available source types

Lists the available source types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "mqtt"
]

Reset source metrics

Reset a bridge metrics by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Enable or disable bridge

Enable or Disable bridge on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

enable
required
boolean
Example: true

Whether to enable this bridge.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Test creating bridge

Test creating a new bridge.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "mqtt"
name
required
string
required
object (bridge_mqtt_publisher.ingress_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (bridge_mqtt_publisher.source_resource_opts)

Responses

Request samples

Content type
application/json
{
  • "name": "mqtt_source",
  • "type": "mqtt",
  • "description": "My example mqtt source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "mqtt_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

Get source metrics

Get bridge metrics by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

Manually start a bridge

Start bridge on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Summarize sources

Summarize actions.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Telemetry

Get telemetry status

Get telemetry status

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false
}

Enable or disable telemetry

Enable or disable telemetry

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: true

Enable telemetry

Responses

Request samples

Content type
application/json
{
  • "enable": false
}

Response samples

Content type
application/json
{
  • "enable": false
}

Get telemetry data

Get telemetry data

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "emqx_version": "5.0.0-beta.3-32d1547c",
  • "license": {
    },
  • "os_name": "Linux",
  • "os_version": "20.04",
  • "otp_version": "24",
  • "up_time": 20220113,
  • "uuid": "AAAAAAAA-BBBB-CCCC-2022-DDDDEEEEFFF",
  • "nodes_uuid": [
    ],
  • "active_plugins": [
    ],
  • "active_modules": [
    ],
  • "num_clients": 20220113,
  • "messages_received": 2022,
  • "messages_sent": 2022
}

Data Backup

Download a data backup file

Download a data backup file

Authorizations:
basicAuthbearerAuth
path Parameters
filename
required
string

Data backup file name

query Parameters
node
string

Node name

Responses

Response samples

Content type
application/json
"binary"

Delete a data backup file

Delete a data backup file

Authorizations:
basicAuthbearerAuth
path Parameters
filename
required
string

Data backup file name

query Parameters
node
string

Node name

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Export a data backup file

Export a data backup file

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
table_sets
Array of strings

Sets of tables to export. Exports all if omitted. Valid values:

- api_keys
- banned
- builtin_authn
- builtin_authz
- builtin_retainer
- dashboard_users
- psk

root_keys
Array of strings

Sets of root configuration keys to export. Exports all if omitted.

Responses

Request samples

Content type
application/json
{
  • "root_keys": [
    ],
  • "table_sets": [
    ]
}

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "size": 22740,
  • "filename": "emqx-export-2023-11-23-19-13-19.043.tar.gz",
  • "created_at": "2023-11-23T19:13:19+02:00",
  • "created_at_sec": 1700759599
}

Import a data backup file

Import a data backup file

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
node
string

Node name

filename
required
string

Data backup file name

Responses

Request samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "filename": "emqx-export-2023-11-23-19-13-19.043.tar.gz"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List backup files

List backup files

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Upload a data backup file

Upload a data backup file

Authorizations:
basicAuthbearerAuth
Request Body schema: multipart/form-data
filename
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Cluster

Get cluster info

Get cluster info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "nodes": [
    ],
  • "self": "string"
}

Force leave node from cluster

Force leave node from cluster

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx2@127.0.0.1

node name

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Send a join invitation to a node to join the clust

Send a join invitation to a node to join the cluster but do not wait for the join result. Join status can be retrieved with GET api/<version>/invitation

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx2@127.0.0.1

node name

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Invite node to cluster

Invite node to cluster

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx2@127.0.0.1

node name

Request Body schema: application/json
timeout
integer >= 0

Timeout in milliseconds

Responses

Request samples

Content type
application/json
{
  • "timeout": "15000"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get RLOG cluster topology: connections between cor

Get RLOG cluster topology: connections between core and replicant nodes.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the execution status of all asynchronous invit

Get the execution status of all asynchronous invite status per node

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "succeed": [
    ],
  • "in_progress": [
    ],
  • "failed": [
    ]
}

Gateway Clients

Get client info

Get the gateway client information

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

Gateway Name

Responses

Response samples

Content type
application/json
Example
{
  • "clientid": "MzAyMzEzNTUwNzk1NDA1MzYyMzIwNzUxNjQwMTY1NzQ0NjE",
  • "mailbox_len": 0,
  • "endpoint_name": "urn:imei:154928475237123",
  • "send_msg": 0,
  • "recv_msg": 0,
  • "recv_pkt": 1,
  • "inflight_cnt": 0,
  • "username": "guest",
  • "subscriptions_cnt": 0,
  • "disconnected_at": null,
  • "created_at": "2021-12-07T10:44:02.721+08:00",
  • "proto_name": "LwM2M",
  • "is_bridge": false,
  • "mqueue_dropped": 0,
  • "expiry_interval": 0,
  • "lifetime": 86400,
  • "recv_cnt": 1,
  • "send_oct": 61,
  • "heap_size": 4185,
  • "inflight_max": "infinity",
  • "clean_start": true,
  • "reductions": 72022,
  • "mqueue_len": 0,
  • "ip_address": "127.0.0.1",
  • "proto_ver": "1.0",
  • "node": "emqx@127.0.0.1",
  • "awaiting_rel_cnt": 0,
  • "connected_at": "2021-12-07T10:44:02.721+08:00",
  • "send_cnt": 1,
  • "send_pkt": 1,
  • "port": 50675,
  • "mqueue_max": "infinity",
  • "recv_oct": 56,
  • "connected": true,
  • "awaiting_rel_max": "infinity",
  • "subscriptions_max": "infinity",
  • "keepalive": 0
}

Kick out client

Kick out the gateway client

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

Gateway Name

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List client's subscription

Get the gateway client subscriptions

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

Gateway Name

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Add subscription for client

Create a subscription membership

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

Gateway Name

Request Body schema: application/json
topic
string

Topic Filter/Name

qos
integer

QoS level, enum: 0, 1, 2

nl
integer

No Local option, enum: 0, 1

rap
integer

Retain as Published option, enum: 0, 1

rh
integer

Retain Handling option, enum: 0, 1, 2

object (emqx_gateway_api_clients.extra_sub_props)

Responses

Request samples

Content type
application/json
Example
{
  • "nl": 0,
  • "topic": "test/topic",
  • "qos": 1,
  • "rap": 0,
  • "rh": 0
}

Response samples

Content type
application/json
Example
{
  • "nl": 0,
  • "topic": "test/topic",
  • "qos": 1,
  • "rap": 0,
  • "rh": 0
}

Delete client's subscription

Delete a subscriptions membership

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic Filter/Name

clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

Gateway Name

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List gateway's clients

Get the gateway client list

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"

Gateway Name

query Parameters
node
string

Match the client's node name

clientid
string

Match the client's ID

username
string

Match the client's Username

ip_address
string

Match the client's ip address

conn_state
string

Match the client's connection state

proto_ver
string

Match the client's protocol version

clean_start
boolean

Match the client's clean start flag

like_clientid
string

Use sub-string to match client's ID

like_username
string

Use sub-string to match client's username

integer or string

Match the session created datetime greater than a certain value

integer or string

Match the session created datetime less than a certain value

integer or string

Match the client socket connected datetime greater than a certain value

integer or string

Match the client socket connected datatime less than a certain value

endpoint_name
string

Match the lwm2m client's endpoint name

like_endpoint_name
string

Use sub-string to match lwm2m client's endpoint name

gte_lifetime
string

Match the lwm2m client registered lifetime greater than a certain value

lte_lifetime
string

Match the lwm2m client registered lifetime less than a certain value

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Publish

Publish a batch of messages

Possible HTTP response status code are:

200: All messages are delivered to at least one subscriber;

202: At least one message was not delivered to any subscriber;

400: At least one message is invalid. For example bad topic name, or QoS is out of range;

503: Failed to deliver at least one of the messages;


In case there is at lest one invalid message in the batch, the HTTP response body
is the same as for /publish API.

Otherwise the HTTP response body is an array of JSON objects indicating the publish
result of each individual message in the batch.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT Payload Encoding, base64 or plain. When set to base64, the message is decoded before it is published.

topic
required
string

Topic Name

qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

clientid
string
Deprecated
payload
required
string

The MQTT message payload.

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

A boolean field to indicate if this message should be retained.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Publish a message

Possible HTTP status response codes are:

200: The message is delivered to at least one subscriber;

202: No matched subscribers;

400: Message is invalid. for example bad topic name, or QoS is out of range;

503: Failed to deliver the message to subscriber(s)

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT Payload Encoding, base64 or plain. When set to base64, the message is decoded before it is published.

topic
required
string

Topic Name

qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

clientid
string
Deprecated
payload
required
string

The MQTT message payload.

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

A boolean field to indicate if this message should be retained.

Responses

Request samples

Content type
application/json
{
  • "payload_encoding": "plain",
  • "topic": "api/example/topic",
  • "qos": 0,
  • "clientid": "string",
  • "payload": "hello emqx api",
  • "properties": {
    },
  • "retain": false
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Rules

Test a rule

Test a rule

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
rule_engine.ctx_unsub (object) or rule_engine.ctx_sub (object) or rule_engine.ctx_schema_validation_failed (object) or rule_engine.ctx_message_transformation_failed (object) or rule_engine.ctx_pub (object) or rule_engine.ctx_dropped (object) or rule_engine.ctx_delivered (object) or rule_engine.ctx_acked (object) or rule_engine.ctx_delivery_dropped (object) or rule_engine.ctx_disconnected (object) or rule_engine.ctx_connected (object) or rule_engine.ctx_connack (object) or rule_engine.ctx_check_authz_complete (object) or rule_engine.ctx_check_authn_complete (object) or rule_engine.ctx_alarm_deactivated (object) or rule_engine.ctx_alarm_activated (object) or rule_engine.ctx_bridge_mqtt (object)
Default: {}

The context of the event for testing

sql
required
string

The SQL of the rule for testing

Responses

Request samples

Content type
application/json
{
  • "context": { },
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Apply a rule for testing

Apply a rule with the given message and environment

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
rule_engine.ctx_unsub (object) or rule_engine.ctx_sub (object) or rule_engine.ctx_schema_validation_failed (object) or rule_engine.ctx_message_transformation_failed (object) or rule_engine.ctx_pub (object) or rule_engine.ctx_dropped (object) or rule_engine.ctx_delivered (object) or rule_engine.ctx_acked (object) or rule_engine.ctx_delivery_dropped (object) or rule_engine.ctx_disconnected (object) or rule_engine.ctx_connected (object) or rule_engine.ctx_connack (object) or rule_engine.ctx_check_authz_complete (object) or rule_engine.ctx_check_authn_complete (object) or rule_engine.ctx_alarm_deactivated (object) or rule_engine.ctx_alarm_activated (object) or rule_engine.ctx_bridge_mqtt (object)
Default: {}

The context of the event for testing

stop_action_after_template_rendering
boolean
Default: true

Set this to true if the action should be stopped after its template has been rendered (default is true).

Responses

Request samples

Content type
application/json
{
  • "context": { },
  • "stop_action_after_template_rendering": true
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List rules

List all rules

Authorizations:
basicAuthbearerAuth
query Parameters
enable
boolean

Filter enable/disable rules

from
string

Filter rules by from(topic), exact match

like_id
string

Filter rules by id, Substring matching

like_from
string

Filter rules by from(topic), Substring matching

like_description
string

Filter rules by description, Substring matching

match_from
string

Filter rules by from(topic), Mqtt topic matching

action
Array of strings

Filters rules that contain any of the given action id(s). When used in conjunction with source id filtering, the rules must contain sources and actions that match some of the criteria.

source
Array of strings

Filters rules that contain any of the given source id(s). When used in conjunction with action id filtering, the rules must contain sources and actions that match some of the criteria.

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a rule

Create a new rule using given Id

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
string
Default: ""

The name of the rule

sql
required
string

SQL query to transform the messages.
Example: SELECT * FROM "test/topic" WHERE payload.x = 1

Array of rule_engine.user_provided_function (object) or rule_engine.builtin_action_console (object) or rule_engine.builtin_action_republish (object) or strings
Default: []

A list of actions of the rule.
An action can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.
There a some built-in functions like "republish" and "console", and we also support user
provided functions in the format: "{module}:{function}".
The actions in the list are executed sequentially.
This means that if one of the action is executing slowly, all the following actions will not
be executed until it returns.
If one of the action crashed, all other actions come after it will still be executed, in the
original order.
If there's any error when running an action, there will be an error message, and the 'failure'
counter of the function action or the bridge channel will increase.

enable
boolean
Default: true

Enable or disable the rule

description
string
Default: ""

The description of the rule

metadata
object

Rule metadata, do not change manually

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "last_modified_at": "2021-12-24T15:00:44.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Get rule metrics

Get a rule's metrics by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

List rule events

List all events can be used in rules

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "event": "$events/sys/alarm_activated",
  • "title": "some title",
  • "description": "some desc",
  • "columns": { },
  • "test_columns": { },
  • "sql_example": "string"
}

Reset rule metrics

Reset a rule metrics

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Get rule

Get a rule by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "last_modified_at": "2021-12-24T15:00:44.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Update rule

Update a rule by given Id to all nodes in the cluster

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
name
string
Default: ""

The name of the rule

sql
required
string

SQL query to transform the messages.
Example: SELECT * FROM "test/topic" WHERE payload.x = 1

Array of rule_engine.user_provided_function (object) or rule_engine.builtin_action_console (object) or rule_engine.builtin_action_republish (object) or strings
Default: []

A list of actions of the rule.
An action can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.
There a some built-in functions like "republish" and "console", and we also support user
provided functions in the format: "{module}:{function}".
The actions in the list are executed sequentially.
This means that if one of the action is executing slowly, all the following actions will not
be executed until it returns.
If one of the action crashed, all other actions come after it will still be executed, in the
original order.
If there's any error when running an action, there will be an error message, and the 'failure'
counter of the function action or the bridge channel will increase.

enable
boolean
Default: true

Enable or disable the rule

description
string
Default: ""

The description of the rule

metadata
object

Rule metadata, do not change manually

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "last_modified_at": "2021-12-24T15:00:44.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Delete rule

Delete a rule by given Id from all nodes in the cluster

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Get rule engine configuration.

Get rule engine configuration.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

Update rule engine configuration.

Update rule engine configuration.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
ignore_sys_message
boolean
Default: true

When set to 'true' (default), rule-engine will ignore messages published to $SYS topics.

jq_function_default_timeout
string
Default: "10s"

Default timeout for the jq rule engine function

Responses

Request samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

Response samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

Relup

Upgrade a specified node

Upgrade a specified node to the target version with the installed package.

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Default: "all"
Example: emqx@127.0.0.1

The node to be upgraded

Responses

Response samples

Content type
application/json
{
  • "code": "UNEXPECTED_ERROR",
  • "message": "string"
}

Upgrade all nodes

Upgrade all nodes to the target version with the installed package.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "UNEXPECTED_ERROR",
  • "message": "string"
}

Upload a hot upgrade package

Upload a hot upgrade package (emqx_relup-vsn.tar.gz).
Note that only one package is alllowed to be installed at a time.

Authorizations:
basicAuthbearerAuth
Request Body schema: multipart/form-data
plugin
string <binary>

Responses

Response samples

Content type
application/json
{
  • "code": "UNEXPECTED_ERROR",
  • "message": "string"
}

Get the hot upgrade status of all nodes

Get the hot upgrade status of all nodes

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the installed hot upgrade package

Get information of the installed hot upgrade package.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "emqx_relup-5.8.2.tar.gz",
  • "target_vsn": "5.8.2",
  • "built_on_otp_release": "24",
  • "applicable_vsns": [
    ],
  • "build_date": "2021-12-25",
  • "change_logs": [
    ],
  • "md5_sum": "d41d8cd98f00b204e9800998ecf8427e"
}

Delete the installed hot upgrade package

Delete the installed hot upgrade package.

Authorizations:
basicAuthbearerAuth

Responses

Get the hot upgrade status of a specified node

Get the hot upgrade status of a specified node

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Default: "all"
Example: emqx@127.0.0.1

The node to be upgraded

Responses

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "status": "in-progress",
  • "role": "core",
  • "live_connections": 100,
  • "current_vsn": "5.8.0",
  • "upgrade_history": [
    ]
}

Gateways

Enable or disable gateway

Update the gateway basic configurations and running status.

Note: The Authentication and Listener configurations should be updated by other special APIs.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

enable
required
boolean
Example: true

Whether to enable this gateway

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List all gateways

This API returns an overview info for the specified or all gateways.
including current running status, number of connections, listener status, etc.

Authorizations:
basicAuthbearerAuth
query Parameters
status
string
Enum: "running" "stopped" "unloaded"
Example: status=running

Filter gateways by status.

It is enum with running, stopped, unloaded

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get gateway

Get the gateway configurations

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Responses

Response samples

Content type
application/json
Example
{
  • "name": "coap",
  • "enable": true,
  • "heartbeat": "30s",
  • "listeners": [
    ],
  • "idle_timeout": "30s",
  • "mountpoint": "coap/",
  • "enable_stats": true,
  • "connection_required": false,
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Load or update the gateway confs

Update the gateway basic configurations and running status.

Note: The Authentication and Listener configurations should be updated by other special APIs.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Request Body schema: application/json
One of
object (gateway.stomp_frame)
mountpoint
string
Default: ""

When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber.
The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to t with listeners.tcp.\<name>.mountpoint set to some_tenant,
then the client actually subscribes to the topic some_tenant/t.
Similarly, if another client B (connected to the same listener as the client A) sends a message to topic t,
the message is routed to all the clients subscribed some_tenant/t,
so client A will receive the message, with topic name t. Set to "" to disable the feature.
Supported placeholders in mountpoint string:

- ${clientid}: clientid

- ${username}: username

- ${endpoint_name}: endpoint name

enable
boolean
Default: true

Whether to enable this gateway

enable_stats
boolean
Default: true

Whether to enable client process statistic

idle_timeout
string
Default: "30s"

The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.

object (gateway.clientinfo_override)

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "mountpoint": "coap2/",
  • "enable_stats": true,
  • "connection_required": false,
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Trace

get trace log file's metadata, such as size, last

get trace log file's metadata, such as size, last update time

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download trace log by name

Download trace log by name

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

query Parameters
node
string
Example: node=emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List all trace

List all trace

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear all traces

Clear all traces

Authorizations:
basicAuthbearerAuth

Responses

Create new trace

Create new trace

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
required
string

Unique name of the trace. Only ASCII letters in a-z, A-Z, 0-9 and underscore '_' are allowed.

type
required
string
Enum: "clientid" "topic" "ip_address" "ruleid"

Filter type

topic
string

Specify the topic or topic filter if the trace 'type' is 'topic'.

clientid
string

Specify the MQTT clientid if the trace 'type' is 'clientid'.

ip_address
string

Specify the client's IP address if the trace type is 'ip_address'.

ruleid
string
payload_encode
string
Default: "text"
Enum: "hex" "text" "hidden"

Determine the format of the payload format in the trace file.

text: Text-based protocol or plain text protocol.
It is recommended when payload is JSON encoded.

hex: Binary hexadecimal encode.It is recommended when payload is a custom binary protocol.

hidden: payload is obfuscated as ******

integer or string

rfc3339 timestamp or epoch second

integer or string

rfc3339 timestamp or epoch second

string or string

The formatter that will be used to format the trace log entries. Set this to text to format the log entries as plain text (default). Set it to json to format each log entry as a JSON object.

Responses

Request samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "ruleid": "my_rule",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "formatter": "text"
}

Response samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "ruleid": "my_rule",
  • "status": "running",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "log_size": [
    ],
  • "formatter": "text"
}

view trace log

view trace log

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

query Parameters
bytes
integer [ 0 .. 2147483647 ]
Default: 1000

Maximum number of bytes to send in response

position
integer
Default: 0

Offset from the current trace position.

node
string
Example: node=emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "items": "TEXT-LOG-ITEMS",
  • "meta": {
    }
}

Delete specified trace

Delete specified trace

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Stop trace by name

Stop trace by name

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "ruleid": "my_rule",
  • "status": "running",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "log_size": [
    ],
  • "formatter": "text"
}

Dashboard

Dashboard list users

Dashboard list users

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create dashboard user

Create dashboard user

Authorizations:
bearerAuth
Request Body schema: application/json
username
string <= 100 characters

Dashboard Username

password
string <= 100 characters

Dashboard Password

description
string

Dashboard User Description

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "public",
  • "description": "administrator"
}

Response samples

Content type
application/json
{
  • "username": "admin",
  • "description": "administrator",
  • "backend": "local"
}

Dashboard authentication

Get Dashboard Auth Token.

Request Body schema: application/json
username
string <= 100 characters

Dashboard Username

password
string <= 100 characters

Dashboard Password

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "public"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "version": "5.0.0",
  • "license": {
    }
}

Update dashboard user description

Update dashboard user description

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Request Body schema: application/json
description
string

Dashboard User Description

Responses

Request samples

Content type
application/json
{
  • "description": "administrator"
}

Response samples

Content type
application/json
{
  • "username": "admin",
  • "description": "administrator",
  • "backend": "local"
}

Delete dashboard user

Delete dashboard user

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Change dashboard user password

Change dashboard user password

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Request Body schema: application/json
old_pwd
string

Old password

new_pwd
string

New password

Responses

Request samples

Content type
application/json
{
  • "old_pwd": "string",
  • "new_pwd": "string"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get the schema JSON of the specified name. NOTE: o

Get the schema JSON of the specified name. NOTE: only intended for EMQX Dashboard.

path Parameters
name
required
string
Enum: "hotconf" "bridges" "actions" "connectors"

Responses

Response samples

Content type
application/json
"string"

Dashboard user logout.<br/>This endpoint is only f

Dashboard user logout.
This endpoint is only for the Dashboard, not the API Key.
The token from the /login endpoint must be a bearer authorization in the headers.

Authorizations:
bearerAuth
Request Body schema: application/json
username
string <= 100 characters

Dashboard Username

Responses

Request samples

Content type
application/json
{
  • "username": "admin"
}

Response samples

Content type
application/json
{
  • "code": "BAD_USERNAME_OR_PWD",
  • "message": "string"
}

Listeners

List all running node's listeners for the specifie

List all running node's listeners for the specified type.

Authorizations:
basicAuthbearerAuth
query Parameters
type
string
Enum: "tcp" "ssl" "ws" "wss" "quic"
Example: type=tcp

Listener type

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create the specified listener on all nodes.

Create the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "quic"

Listener type

running
boolean

Listener status

name
required
string

Listener name

current_connections
integer >= 0

Current connections

ciphers
Array of strings
Default: ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256","TLS_CHACHA20_POLY1305_SHA256"]

This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or
["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].


Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.

The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.


NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.



NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config

If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.

PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"


NOTE: QUIC listener supports only 'tlsv1.3' ciphers

object (emqx.listener_quic_ssl_opts)
enable
boolean
Default: true

Enable listener.

bind
required
string
Default: 14567

IP address and port for the listening socket.

acceptors
integer >= 1
Default: 16

The size of the listener's receiving pool.

integer or string
Default: "infinity"

The maximum number of concurrent connections allowed by the listener.

mountpoint
string
Default: ""
  • Adds a static or templated prefix (e.g., n1/ or ${username}/) to topics used by clients in SUBSCRIBE and UNSUBSCRIBE requests, PUBLISH messages, and Will Message (if supplied in the CONNECT packet).
    - Removes this prefix from topics of messages published to the respective subscriptions.

    The supported placeholders are:
    - ${username}
    - ${clientid}
    - ${zone}
    - ${client_attrs.NAME}

    For example, with mountpoint="${username}/" a client using u1 as username will have:
    - Client SUBSCRIBE sensors/# -> u1/sensors/# internally in the broker.
    - Broker PUBLISH u1/sensors/data -> sensors/data sent to the client.

    The prefix mount/unmount is applied to:
    - Will in CONNECT
    - PUBLISH
    - SUBSCRIBE
    - UNSUBSCRIBE

    Note: mounting occurs after authorization/ACL checks.
zone
string
Default: "default"

The configuration zone to which the listener belongs.
Clients connected to this listener will inherit zone-settings created under this zone name.

A zone can override the configs under below root names:
- mqtt
- force_shutdown
- force_gc
- flapping_detect
- durable_sessions

enable_authn
string
Default: true
Enum: true false "quick_deny_anonymous"

Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false, any client (with or without username/password) is allowed to connect.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.

max_conn_rate
string
Default: "infinity"

Used to limit the rate at which the current listener accepts connections.

Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.

For example:

- 1000/s: Only accepts 1000 connections per second.
- 1000/10s: Only accepts 1000 connections every 10 seconds.

messages_rate
string

Used to limit the number of messages a single client can send to EMQX per second.

Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.

For example:

- 500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.
- 500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.

bytes_rate
string

Used to limit the number of bytes a single client can send to EMQX per second.

Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.

The unit of the bytes could be: B, KB, MB, GB.

For example:

- 500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.
- 500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.

Responses

Request samples

Content type
application/json
{
  • "name": "demo",
  • "running": true,
  • "type": "tcp",
  • "bind": "0.0.0.0:1884",
  • "tcp_options": {
    },
  • "access_rules": [
    ],
  • "max_connections": 204800,
  • "proxy_protocol_timeout": "3s",
  • "acceptors": 16,
  • "proxy_protocol": false,
  • "zone": "default",
  • "mountpoint": "/",
  • "current_connections": 10240
}

Response samples

Content type
application/json
{
  • "id": "tcp:demo",
  • "running": true,
  • "type": "tcp",
  • "bind": "0.0.0.0:1884",
  • "tcp_options": {
    },
  • "access_rules": [
    ],
  • "max_connections": 204800,
  • "proxy_protocol_timeout": "3s",
  • "acceptors": 16,
  • "proxy_protocol": false,
  • "zone": "default",
  • "mountpoint": "/",
  • "current_connections": 10240
}

Stop the listener on all nodes.

Stop the listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Start the listener on all nodes.

Start the listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Restart listeners on all nodes.

Restart listeners on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List all running node's listeners for the specifie

List all running node's listeners for the specified id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "id": "tcp:demo",
  • "running": true,
  • "type": "tcp",
  • "bind": "0.0.0.0:1884",
  • "tcp_options": {
    },
  • "access_rules": [
    ],
  • "max_connections": 204800,
  • "proxy_protocol_timeout": "3s",
  • "acceptors": 16,
  • "proxy_protocol": false,
  • "zone": "default",
  • "mountpoint": "/",
  • "current_connections": 10240
}

Update the specified listener on all nodes.

Update the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Request Body schema: application/json
One of
type
required
string
Value: "wss"

Listener type

running
boolean

Listener status

id
required
string

Listener id

current_connections
integer >= 0

Current connections

bind
string
Default: 8084

IP address and port for the listening socket.

enable
boolean
Default: true

Enable listener.

acceptors
integer >= 1
Default: 16

The size of the listener's receiving pool.

integer or string
Default: "infinity"

The maximum number of concurrent connections allowed by the listener.

mountpoint
string
Default: ""
  • Adds a static or templated prefix (e.g., n1/ or ${username}/) to topics used by clients in SUBSCRIBE and UNSUBSCRIBE requests, PUBLISH messages, and Will Message (if supplied in the CONNECT packet).
    - Removes this prefix from topics of messages published to the respective subscriptions.

    The supported placeholders are:
    - ${username}
    - ${clientid}
    - ${zone}
    - ${client_attrs.NAME}

    For example, with mountpoint="${username}/" a client using u1 as username will have:
    - Client SUBSCRIBE sensors/# -> u1/sensors/# internally in the broker.
    - Broker PUBLISH u1/sensors/data -> sensors/data sent to the client.

    The prefix mount/unmount is applied to:
    - Will in CONNECT
    - PUBLISH
    - SUBSCRIBE
    - UNSUBSCRIBE

    Note: mounting occurs after authorization/ACL checks.
zone
string
Default: "default"

The configuration zone to which the listener belongs.
Clients connected to this listener will inherit zone-settings created under this zone name.

A zone can override the configs under below root names:
- mqtt
- force_shutdown
- force_gc
- flapping_detect
- durable_sessions

enable_authn
string
Default: true
Enum: true false "quick_deny_anonymous"

Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false, any client (with or without username/password) is allowed to connect.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.

max_conn_rate
string
Default: "infinity"

Used to limit the rate at which the current listener accepts connections.

Once the limit is reached, EMQX will pause fetching connections from the Accept queue, thereby delaying or rejecting new connections.

For example:

- 1000/s: Only accepts 1000 connections per second.
- 1000/10s: Only accepts 1000 connections every 10 seconds.

messages_rate
string

Used to limit the number of messages a single client can send to EMQX per second.

Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.

For example:

- 500/s: Only 500 messages will be received per second, and the remaining messages will be delayed.
- 500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be delayed.

bytes_rate
string

Used to limit the number of bytes a single client can send to EMQX per second.

Once the limit is reached, EMQX will pause reading data from the receive-buffer, thus slowing down or even temporarily hanging the sender.

The unit of the bytes could be: B, KB, MB, GB.

For example:

- 500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be delayed.
- 500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be delayed.

access_rules
Array of strings
Default: ["allow all"]

An access rule list consisting of string rules to restrict or allow access from some addresses. The rules that appear earlier in the list are matched first.
The format is allow | deny <address> | <CIDR> | all.

For example:

["deny 192.168.1.1", "allow 192.168.1.0/24", "deny all"]

proxy_protocol
boolean
Default: false

Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.

See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

If a reverse proxy is deployed for EMQX, and the PROXY protocol is enabled at the proxy to pass the client's real IP, this option needs to be turned on so that EMQX can extract the client's real IP from the PROXY protocol header.

EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.

For a detailed description of the PROXY protocol, please refer to: https://www.haproxy.com/blog/haproxy/proxy-protocol/

object (emqx.tcp_opts)
object (emqx.listener_wss_opts)
object (emqx.ws_opts)

Responses

Request samples

Content type
application/json
{
  • "id": "tcp:demo",
  • "running": true,
  • "type": "tcp",
  • "bind": "0.0.0.0:1884",
  • "tcp_options": {
    },
  • "access_rules": [
    ],
  • "max_connections": 204800,
  • "proxy_protocol_timeout": "3s",
  • "acceptors": 16,
  • "proxy_protocol": false,
  • "zone": "default",
  • "mountpoint": "/",
  • "current_connections": 10240
}

Response samples

Content type
application/json
{
  • "id": "tcp:demo",
  • "running": true,
  • "type": "tcp",
  • "bind": "0.0.0.0:1884",
  • "tcp_options": {
    },
  • "access_rules": [
    ],
  • "max_connections": 204800,
  • "proxy_protocol_timeout": "3s",
  • "acceptors": 16,
  • "proxy_protocol": false,
  • "zone": "default",
  • "mountpoint": "/",
  • "current_connections": 10240
}

Delete the specified listener on all nodes.

Delete the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_LISTENER_ID",
  • "message": "string"
}

List all running node's listeners live status. gro

List all running node's listeners live status. group by listener type

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Gateway Authentication

Get authenticator configuration

Gets the configuration of the specified gateway authenticator.

Returns 404 when gateway or authentication is not enabled.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Responses

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Update authenticator configuration

Update the configuration of the specified gateway authenticator, or disable the authenticator.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Request Body schema: application/json
One of
mechanism
required
string
Value: "password_based"

Authentication mechanism.

backend
required
string
Value: "ldap"

Backend type.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

Indicates which attribute is used to represent the user's password.

is_superuser_attribute
string
Default: "isSuperuser"

Indicates which attribute is used to represent whether the user is a superuser.

Responses

Request samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Delete gateway authenticator

Delete the authenticator of the specified gateway.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Create authenticator for gateway

Enables the authenticator for client authentication for the specified gateway.

When the authenticator is not configured or turned off, all client connections are assumed to be allowed.

Note: Only one authenticator is allowed to be enabled at a time in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Request Body schema: application/json
One of
mechanism
required
string
Value: "password_based"

Authentication mechanism.

backend
required
string
Value: "ldap"

Backend type.

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The LDAP default port 389 is used if [:Port] is not specified.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

base_dn
required
string

The name of the base object entry (or possibly the root) relative to
which the Search is to be performed.

filter
string
Default: "(objectClass=mqttUser)"

The filter that defines the conditions that must be fulfilled in order
for the Search to match a given entry.

The syntax of the filter follows RFC 4515 and also supports placeholders.

request_timeout
string
Default: "10s"

Sets the maximum time in milliseconds that is used for each individual request.

object (ldap.ssl)
password_attribute
string
Default: "userPassword"

Indicates which attribute is used to represent the user's password.

is_superuser_attribute
string
Default: "isSuperuser"

Indicates which attribute is used to represent whether the user is a superuser.

Responses

Request samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Response samples

Content type
application/json
Example
{
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "algorithm": "hmac-based",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Import users

Import users into the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Request Body schema: multipart/form-data
filename
string <binary>

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "success": 0,
  • "override": 0,
  • "skipped": 0,
  • "failed": 0
}

List users for gateway authenticator

Get the users for the authenticator (only supported by built_in_database).

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_user_id
string
Example: like_user_id=test_

Fuzzy search using user ID (username or clientid), only supports search by substring.

is_superuser
boolean

Is superuser

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add user for gateway authenticator

Add user for the authenticator (only supports built_in_database).

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Get user info for gateway authenticator

Get user info from the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

uid
required
string
Example: test_username

User ID

Responses

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Update user info for gateway authenticator

Update the user info for the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

uid
required
string
Example: test_username

User ID

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Delete user for gateway authenticator

Delete the user for the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

uid
required
string
Example: test_username

User ID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Import users

Import users into the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "lwm2m" "mqttsn" "stomp"
Example: stomp

Gateway Name

id
required
string
Example: stomp:tcp:def

Listener ID

Request Body schema: multipart/form-data
filename
string <binary>

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "success": 0,
  • "override": 0,
  • "skipped": 0,
  • "failed": 0
}

CoAP Gateways

Send a Request to a Client

Send a CoAP request message to the client

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
token
string

Message token, can be empty

method
string
Enum: "get" "put" "post" "delete"

Request method type

timeout
string

Timespan for response

content_type
string
Enum: "text/plain" "application/json" "application/octet-stream"

Payload type

payload
string

The content of the payload

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "method": "get",
  • "timeout": "32s",
  • "content_type": "text/plain",
  • "payload": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "token": "string",
  • "method": "string",
  • "payload": "string"
}

Retainer

List retained messages.

List retained messages.

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

Topic filter, supports wildcards, omit this to match all messages.

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Delete all retained messages

Delete all retained messages

Authorizations:
basicAuthbearerAuth

Responses

Lookup a message by a topic without wildcards.

Lookup a message by a topic without wildcards.

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic.

Responses

Response samples

Content type
application/json
{
  • "payload": "string",
  • "msgid": "string",
  • "topic": "string",
  • "qos": 0,
  • "publish_at": "string",
  • "from_clientid": "string",
  • "from_username": "string"
}

Delete matching messages.

Delete matching messages.

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

View config

View config

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_expiry_interval_override": "disabled",
  • "allow_never_expire": true,
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "delivery_rate": "1000/s",
  • "max_publish_rate": "1000/s",
  • "backend": {
    }
}

Update retainer config.

Update retainer config.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: true

Enable retainer feature

msg_expiry_interval
string
Default: "0s"

Expired retained messages will not be delivered again, and a setting of 0 means that retained messages will never expire.

However, if the Message-Expiry-Interval property is specified in the MQTT message, the value of that property prevails.

string or string
Default: "disabled"

If set, this value will take precedence over any Message-Expiry-Interval property specified in retained MQTT messages, allowing messages to expire earlier if necessary. This override only applies to the garbage collection process: it does not affect the expiry time of messages being written nor that of already written messages while iterating over them. Therefore, messages that are candidate for garbage collection when overridden may still be visible when subscribing to retained topics.

allow_never_expire
boolean
Default: true

If true, retained messages set to never expire (i.e., whose Message-Expiry-Interval = 0) are not affected by the expiry time override. This configuration only takes effect when msg_expiry_interval_override is set.

msg_clear_interval
string
Default: "0s"

The time interval for checking and clearing expired retained messages. This can prevent expired retained messages from being stored for a long time.

If msg_clear_interval is set to 0, that is, expired retained messages are not actively checked regularly, EMQX will only check and delete expired retained messages when preparing for delivery.

max_payload_size
string
Default: "1MB"

The maximum size of retained messages allowed to be stored. EMQX will refuse to store retained messages larger than this size and output an Error log with the keyword 'retain_failed_for_payload_size_exceeded_limit'.

0 means unlimited retained message size.

stop_publish_clear_msg
boolean
Default: false

When the retained flag of the PUBLISH message is set and Payload is empty,
whether to continue to publish the message.
See:
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718038

delivery_rate
string
Default: "1000/s"

The maximum rate of delivering retained messages

max_publish_rate
string
Default: "1000/s"

The maximum rate of publishing retained messages. Messages that are published over the limit are delivered but not stored as retained.

object (retainer.mnesia_config)

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_expiry_interval_override": "disabled",
  • "allow_never_expire": true,
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "delivery_rate": "1000/s",
  • "max_publish_rate": "1000/s",
  • "backend": {
    }
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_expiry_interval_override": "disabled",
  • "allow_never_expire": true,
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "delivery_rate": "1000/s",
  • "max_publish_rate": "1000/s",
  • "backend": {
    }
}

Alarms

List currently activated alarms or historical alar

List currently activated alarms or historical alarms, determined by query parameters.

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

activated
boolean

It is used to specify the alarm type of the query.
When true, it returns the currently activated alarm,
and when it is false, it returns the historical alarm.
The default is false.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Remove all historical alarms.

Remove all historical alarms.

Authorizations:
basicAuthbearerAuth

Responses

Subscriptions

List subscriptions

List subscriptions

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

node
string
Example: node=emqx@127.0.0.1

Node name

clientid
string

Client ID

qos
integer [ 0 .. 2 ]
Example: qos=0

QoS

topic
string

Topic, url encoding

match_topic
string

Match topic string, url encoding

share_group
string

Shared subscription group name

durable
boolean

Filter subscriptions by durability

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Error Codes

API Error Codes

API Error Codes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

API Error Codes

API Error Codes

path Parameters
code
required
string
Enum: "BAD_USERNAME_OR_PWD" "BAD_API_KEY_OR_SECRET" "BAD_REQUEST" "NOT_MATCH" "ALREADY_EXISTS" "BAD_CONFIG_SCHEMA" "BAD_LISTENER_ID" "BAD_NODE_NAME" "BAD_RPC" "BAD_TOPIC" "EXCEED_LIMIT" "INVALID_PARAMETER" "CONFLICT" "NO_DEFAULT_VALUE" "DEPENDENCY_EXISTS" "MESSAGE_ID_SCHEMA_ERROR" "INVALID_ID" "MESSAGE_ID_NOT_FOUND" "NOT_FOUND" "CLIENTID_NOT_FOUND" "CLIENT_NOT_FOUND" "RESOURCE_NOT_FOUND" "TOPIC_NOT_FOUND" "USER_NOT_FOUND" "INTERNAL_ERROR" "SERVICE_UNAVAILABLE" "SOURCE_ERROR" "UPDATE_FAILED" "REST_FAILED" "CLIENT_NOT_RESPONSE" "UNSUPPORTED_MEDIA_TYPE"
Example: BAD_USERNAME_OR_PWD

API Error Codes

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Slow Subscriptions

View slow subs settings

View slow subs settings

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

Update slow subs settings

Update slow subs settings

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
enable
boolean
Default: false

Enable Slow Subscriptions

threshold
string
Default: "500ms"

The Client ID and topic of the consumer whose message latency is greater than this threshold will be recorded in the slow subscription list.

expire_interval
string
Default: "300s"

The expiration time of the slow subscription record, if the record is not updated within the expiration time, then the record will be deleted.

top_k_num
integer >= 1
Default: 10

The maximum number of slow-subscription records, up to a maximum of 1000.

stats_type
string
Default: "whole"
Enum: "whole" "internal" "response"

Message latency calculation method:

- whole: The time from when the message arrives at the EMQX (the EMQX gets the message from the receive-buffer) until the message completes delivery.
- internal: The time from when the message arrives at the EMQX (the EMQX gets the message from the receive-buffer) to when the message begins to be delivered (the EMQX attempts to write the message to the send-buffer).
- response: The time from the start of message delivery to the completion.

Note: The completion delivery time refers to the time when QoS 1 and 2 messages complete the MQTT message response process, i.e., the time when QoS 1 message receives the PUBACK packet and QoS 2 message receives the PUBCOMP packet.
Since there is no response packet for QoS 0 message, the completion delivery time of the QoS 0 message will be replaced by the time when the message starts to be delivered. Therefore, when using the response method to calculate the latency, the latency of a QoS 0 message will always be equal to 0.

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

Response samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

View slow topics statistics record data

View slow topics statistics record data

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Clear current data and re count slow topic

Clear current data and re count slow topic

Authorizations:
basicAuthbearerAuth

Responses

API Keys

Return api_key list. This API can only be requeste

Return api_key list. This API can only be requested using a bearer token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Create new api_key. This API can only be requested

Create new api_key. This API can only be requested using a bearer token.

Authorizations:
bearerAuth
Request Body schema: application/json
name
string

Unique and format by [a-zA-Z0-9-_]

(integer or string) or string
Default: "infinity"

No longer valid datetime

desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

Responses

Request samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "api_secret": "MzAyMjk3ODMwMDk0NjIzOTUxNjcwNzQ0NzQ3MTE2NDYyMDI",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Return the specific api_key. This API can only be

Return the specific api_key. This API can only be requested using a bearer token.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

^[A-Za-z]+[A-Za-z0-9-_]*$

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Update the specific api_key. This API can only be

Update the specific api_key. This API can only be requested using a bearer token.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

^[A-Za-z]+[A-Za-z0-9-_]*$

Request Body schema: application/json
(integer or string) or string
Default: "infinity"

No longer valid datetime

desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

Responses

Request samples

Content type
application/json
{
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true
}

Delete the specific api_key. This API can only be

Delete the specific api_key. This API can only be requested using a bearer token.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

^[A-Za-z]+[A-Za-z0-9-_]*$

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Banned

List all currently banned client IDs, usernames an

List all currently banned client IDs, usernames and IP addresses.
Filters are supported. Since filters are mutually exclusive, only one filter is allowed in a query.

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

clientid
string

Query the banning rules with an exact client ID.

username
string

Query the banning rules with an exact username.

peerhost
string
Example: peerhost=127.0.0.1

Query the banning rules with an exact IP address.

like_clientid
string

Fuzzy query banning rules with a regular expression for client ID.

like_username
string

Fuzzy query banning rules with a regular expression for username.

like_peerhost
string
Example: like_peerhost=127.0.0.1

Fuzzy query banning rules with a regular expression for IP address.

like_peerhost_net
string
Example: like_peerhost_net=192.1.0.0/16

Fuzzy query banning rules with a regular expression for CIDR.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Clear all banned data.

Clear all banned data.

Authorizations:
basicAuthbearerAuth

Responses

Add a client ID, username or IP address to the bla

Add a client ID, username or IP address to the blacklist.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"

Ban method, which can be exact client ID, client ID regular expression, exact username, username regular expression,
IP address or an IP address range.

who
required
string

Ban object, specific client ID, username or IP address.

by
string

Initiator of the ban.

reason
string

Ban reason, record the reason why the current object was banned.

integer or string

The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated.

(integer or string) or string
Default: "infinity"

The end time of the ban, the format is rfc3339, the default is the time when the operation was initiated + 1 year.

Responses

Request samples

Content type
application/json
{
  • "as": "username",
  • "who": "Banned name",
  • "by": "mgmt_api",
  • "reason": "Too many requests",
  • "at": "2021-10-25T21:48:47+08:00",
  • "until": "2021-10-25T21:53:47+08:00"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Remove a client ID, username or IP address from th

Remove a client ID, username or IP address from the blacklist.

Authorizations:
basicAuthbearerAuth
path Parameters
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"
Example: username

Ban method, which can be exact client ID, client ID regular expression, exact username, username regular expression,
IP address or an IP address range.

who
required
string
Example: Badass

Ban object, specific client ID, username or IP address.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}