< 反馈文档问题
API docs by Redocly

EMQX API (5.0)

Download OpenAPI specification:Download

Authentication

Move authenticator

Move authenticator in global authentication chain.

Authorizations:
basicAuthNone
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"
}

Delete user in authenticator

Delete user in authenticator in global authentication chain.

Authorizations:
basicAuthNone
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"
}

Get user from authenticator

Get user from authenticator in global authentication chain.

Authorizations:
basicAuthNone
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

Update user in authenticator in global authentication chain.

Authorizations:
basicAuthNone
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": {
    }
}

Global import users into authenticator

Import users into authenticator in global authentication chain.

Authorizations:
basicAuthNone
path Parameters
id
required
string

Authenticator ID.

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

Responses

Response samples

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

List users in authenticator

List users in authenticator in global authentication chain.

Authorizations:
basicAuthNone
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 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

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

Create users for authenticator in global authentication chain.

Authorizations:
basicAuthNone
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

Get authenticator status from global authentication chain.

Authorizations:
basicAuthNone
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

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

Delete authenticator

Delete authenticator from global authentication chain.

Authorizations:
basicAuthNone
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

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

Get authenticator

Get authenticator from global authentication chain.

Authorizations:
basicAuthNone
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

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

Update authenticator

Update authenticator from global authentication chain.

Authorizations:
basicAuthNone
path Parameters
id
required
string

Authenticator ID.

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

Authentication mechanism.

backend
required
string
Value: "built_in_database"

Backend type.

algorithm
string
Default: "sha256"
Enum: "sha256" "sha512"

Hashing algorithm.

iteration_count
integer >= 0
Default: 4096

Iteration count.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

List authenticators

List authenticators for global authentication.

Authorizations:
basicAuthNone

Responses

Response samples

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

Create authenticator

Create authenticator for global authentication.

Authorizations:
basicAuthNone
Request Body schema: application/json
One of
mechanism
required
string
Value: "scram"

Authentication mechanism.

backend
required
string
Value: "built_in_database"

Backend type.

algorithm
string
Default: "sha256"
Enum: "sha256" "sha512"

Hashing algorithm.

iteration_count
integer >= 0
Default: 4096

Iteration count.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Metrics

EMQX metrics

EMQX metrics

Authorizations:
basicAuthNone
query Parameters
aggregate
boolean

Whether to aggregate all nodes Metrics

Responses

Response samples

Content type
application/json
Example
[ ]

EMQX stats

EMQX stats

Authorizations:
basicAuthNone
query Parameters
aggregate
boolean

Calculation aggregate for all nodes

Responses

Response samples

Content type
application/json
Example
[ ]

Current status. Gauge and rate.

Current status. Gauge and rate.

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "received_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0
}

Node current status. Gauge and rate.

Node current status. Gauge and rate.

Authorizations:
basicAuthNone
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,
  • "received_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0
}

List the monitor data on the node.

List the monitor data on the node.

Authorizations:
basicAuthNone
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 data.

List monitor data.

Authorizations:
basicAuthNone
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
[
  • {
    }
]

MQTT

Get delayed status

Get delayed status

Authorizations:
basicAuthNone

Responses

Response samples

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

Enable or disable delayed

Enable or disable delayed, set max delayed messages

Authorizations:
basicAuthNone
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
}

Delete delayed message

Delete delayed message

Authorizations:
basicAuthNone
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"
}

View delayed message

View delayed message

Authorizations:
basicAuthNone
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"
}

List all rewrite rules

List all rewrite rules

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update all rewrite rules

Update all rewrite rules

Authorizations:
basicAuthNone
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
[
  • {
    }
]

Delete topic metrics

Delete topic metrics

Authorizations:
basicAuthNone
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"
}

Get topic metrics

Get topic metrics

Authorizations:
basicAuthNone
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": {
    }
}

List topic metrics

List topic metrics

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create topic metrics

Create topic metrics

Authorizations:
basicAuthNone
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"
}

Reset telemetry status

Reset telemetry status

Authorizations:
basicAuthNone
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"
}

List delayed messages

List delayed messages

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

Page number of the results to fetch.

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

Results per page(max 1000)

Responses

Response samples

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

Configs

Get the node-level limiter configs

Get the node-level limiter configs

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "max_conn_rate": "1000/s",
  • "messages_rate": "1000/s",
  • "bytes_rate": "100MB/s"
}

Update the node-level limiter configs

Update the node-level limiter configs

Authorizations:
basicAuthNone
Request Body schema: application/json
max_conn_rate
string

Maximum connection rate.

This is used to limit the connection rate for this node,
once the limit is reached, new connections will be deferred or refused

messages_rate
string

Messages publish rate.

This is used to limit the inbound message numbers for this node,
once the limit is reached, the restricted client will slow down and even be hung for a while.

bytes_rate
string

Data publish rate.

This is used to limit the inbound bytes rate for this node,
once the limit is reached, the restricted client will slow down and even be hung for a while.

Responses

Request samples

Content type
application/json
{
  • "max_conn_rate": "1000/s",
  • "messages_rate": "1000/s",
  • "bytes_rate": "100MB/s"
}

Response samples

Content type
application/json
{
  • "max_conn_rate": "1000/s",
  • "messages_rate": "1000/s",
  • "bytes_rate": "100MB/s"
}

Get the sub-configurations under *sys_topics*

Get the sub-configurations under sys_topics

Authorizations:
basicAuthNone

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:
basicAuthNone
Request Body schema: application/json
string or string
Default: "1m"

Time interval of publishing $SYS messages.

string or string
Default: "30s"

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

object (broker.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:
basicAuthNone

Responses

Response samples

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

Update the sub-configurations under *sysmon*

Update the sub-configurations under sysmon

Authorizations:
basicAuthNone
Request Body schema: application/json
object (broker.sysmon_vm)
object (broker.sysmon_os)

Responses

Request samples

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

Response samples

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

Get the global zone configs

Get the global zone configs

Authorizations:
basicAuthNone

Responses

Response samples

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

Update global zone configs

Update global zone configs

Authorizations:
basicAuthNone
Request Body schema: application/json
object (broker.mqtt)
object (broker.force_shutdown)
object (broker.force_gc)

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *alarm*

Get the sub-configurations under alarm

Authorizations:
basicAuthNone

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:
basicAuthNone
Request Body schema: application/json
actions
Array of strings
Default: ["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 total number of deactivated alarms to keep as history.
When this limit is exceeded, the oldest deactivated alarms are deleted to cap the total number.

validity_period
string
Default: "24h"

Retention time of deactivated alarms. Alarms are not deleted immediately
when deactivated, but after the retention time.

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 *persistent_session_store*

Get the sub-configurations under persistent_session_store

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "enabled": false,
  • "on_disc": true,
  • "ram_cache": false,
  • "backend": {
    },
  • "max_retain_undelivered": "12m",
  • "message_gc_interval": "12m",
  • "session_message_gc_interval": "12m"
}

Update the sub-configurations under *persistent_session_store*

Update the sub-configurations under persistent_session_store

Authorizations:
basicAuthNone
Request Body schema: application/json
enabled
boolean
Default: false

Use the database to store information about persistent sessions.
This makes it possible to migrate a client connection to another
cluster node if a node is stopped.

on_disc
boolean
Default: true

Save information about the persistent sessions on disc.
If this option is enabled, persistent sessions will survive full restart of the cluster.
Otherwise, all the data will be stored in RAM, and it will be lost when all the nodes in the cluster are stopped.

ram_cache
boolean
Default: false

Maintain a copy of the data in RAM for faster access.

broker.persistent_session_builtin (object)
Default: {"messages":{"ram_cache":"false"},"session":{"ram_cache":"true"},"session_messages":{"ram_cache":"true"},"type":"builtin"}

Database management system used to store information about persistent sessions and messages.
- builtin: Use the embedded database (mria)

max_retain_undelivered
string
Default: "1h"

The time messages that was not delivered to a persistent session
is stored before being garbage collected if the node the previous
session was handled on restarts of is stopped.

message_gc_interval
string
Default: "1h"

The starting interval for garbage collection of undelivered messages to
a persistent session. This affects how often the "max_retain_undelivered"
is checked for removal.

session_message_gc_interval
string
Default: "1m"

The starting interval for garbage collection of transient data for
persistent session messages. This does not affect the lifetime length
of persistent session messages.

Responses

Request samples

Content type
application/json
{
  • "enabled": false,
  • "on_disc": true,
  • "ram_cache": false,
  • "backend": {
    },
  • "max_retain_undelivered": "12m",
  • "message_gc_interval": "12m",
  • "session_message_gc_interval": "12m"
}

Response samples

Content type
application/json
{
  • "enabled": false,
  • "on_disc": true,
  • "ram_cache": false,
  • "backend": {
    },
  • "max_retain_undelivered": "12m",
  • "message_gc_interval": "12m",
  • "session_message_gc_interval": "12m"
}

Get the sub-configurations under *dashboard*

Get the sub-configurations under dashboard

Authorizations:
basicAuthNone

Responses

Response samples

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

Update the sub-configurations under *dashboard*

Update the sub-configurations under dashboard

Authorizations:
basicAuthNone
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.

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *zones*

Get the sub-configurations under zones

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "$name": {
    }
}

Update the sub-configurations under *zones*

Update the sub-configurations under zones

Authorizations:
basicAuthNone
Request Body schema: application/json
object (broker.zone)

Responses

Request samples

Content type
application/json
{
  • "$name": {
    }
}

Response samples

Content type
application/json
{
  • "$name": {
    }
}

Reset the config entry with query

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:
basicAuthNone
path Parameters
rootname
required
string
Enum: "zones" "persistent_session_store" "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 for node.

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

Authorizations:
basicAuthNone
query Parameters
node
string
Example: node=emqx@127.0.0.1

Node's name: If you do not fill in the fields, this node will be used by default.

Responses

Response samples

Content type
application/json
{
  • "zones": {
    },
  • "log": {
    },
  • "sysmon": {
    },
  • "sys_topics": {
    },
  • "alarm": {
    },
  • "dashboard": {
    }
}

Get the sub-configurations under *log*

Get the sub-configurations under log

Authorizations:
basicAuthNone

Responses

Response samples

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

Update the sub-configurations under *log*

Update the sub-configurations under log

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

File-based log handlers.

Responses

Request samples

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

Response samples

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

LwM2M Gateways

Observe a Resource

Observe or Cancel observe a resource

Authorizations:
basicAuthNone
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:
basicAuthNone
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:
basicAuthNone
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:
basicAuthNone
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"
}

Plugins

Delete a plugin

Uninstalls a previously uploaded plugin package.

Authorizations:
basicAuthNone
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": "NOT_FOUND",
  • "message": "string"
}

Get a plugin description

Describs plugin according to its release.json and README.md.

Authorizations:
basicAuthNone
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."
}

Trigger action on an installed plugin

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

Authorizations:
basicAuthNone
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:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Move plugin within plugin hiearchy

Setting the boot order of plugins.

Authorizations:
basicAuthNone
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"
}

Install a new plugin

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

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

Responses

Response samples

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

Bridges

Reset Bridge Metrics

Reset a bridge metrics by Id

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_example

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

Responses

Response samples

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

Node Bridge Operate

Stop/Restart bridges on a specific node.

Authorizations:
basicAuthNone
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: webhook:webhook_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 Bridge Creation

Test creating a new bridge by given ID

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

Authorizations:
basicAuthNone
Request Body schema: application/json
One of
type
required
string
Value: "webhook"

The Bridge Type

name
required
string

Bridge name, used as a human-readable description of the bridge.

enable
boolean
Default: true

Enable or disable this bridge

object (bridge_webhook.creation_opts)
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

A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

object (connector-http.request)
object (broker.ssl_client_opts)
url
required
string

The URL of the HTTP Bridge.

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"

Deprecated, The direction of this bridge, MUST be '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 bridge 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.

Responses

Request samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "mode": "cluster_shareload",
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Response samples

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

Cluster Bridge Enable

Enable or Disable bridges on all nodes in the cluster.

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_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": "NOT_FOUND",
  • "message": "string"
}

Get Bridge Metrics

Get bridge metrics by Id

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_example

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

Responses

Response samples

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

Delete Bridge

Delete a bridge by Id

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_example

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

Responses

Response samples

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

Get Bridge

Get a bridge by Id

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_example

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

Responses

Response samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "mode": "cluster_shareload",
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Update Bridge

Update a bridge by Id

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_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 bridge

object (bridge_webhook.creation_opts)
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

A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

object (connector-http.request)
object (broker.ssl_client_opts)
url
required
string

The URL of the HTTP Bridge.

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"

Deprecated, The direction of this bridge, MUST be '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 bridge 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.

Responses

Request samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "mode": "cluster_shareload",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "username": "foo"
}

Response samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "mode": "cluster_shareload",
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Cluster Bridge Operate

Stop/Restart bridges on all nodes in the cluster.

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: webhook:webhook_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 All Bridges

List all created bridges

Authorizations:
basicAuthNone

Responses

Response samples

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

Create Bridge

Create a new bridge by type and name

Authorizations:
basicAuthNone
Request Body schema: application/json
One of
type
required
string
Value: "webhook"

The Bridge Type

name
required
string

Bridge name, used as a human-readable description of the bridge.

enable
boolean
Default: true

Enable or disable this bridge

object (bridge_webhook.creation_opts)
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

A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.

object (connector-http.request)
object (broker.ssl_client_opts)
url
required
string

The URL of the HTTP Bridge.

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"

Deprecated, The direction of this bridge, MUST be '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 bridge 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.

Responses

Request samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "mode": "cluster_shareload",
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Response samples

Content type
application/json
Example
{
  • "clean_start": true,
  • "egress": {
    },
  • "enable": true,
  • "ingress": {
    },
  • "keepalive": "300s",
  • "max_inflight": 100,
  • "mode": "cluster_shareload",
  • "name": "mqtt_example",
  • "password": "******",
  • "proto_ver": "v4",
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "127.0.0.1:1883",
  • "ssl": {
    },
  • "type": "mqtt",
  • "username": "foo"
}

Status

Service health check

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:
basicAuthNone
path Parameters
topic
required
string

Topic Name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Topics list

Topics list

Authorizations:
basicAuthNone
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 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

Responses

Response samples

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

Authorization

Show rules for users

Show the list of rules for users

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

Page number of the results to fetch.

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

Results per page(max 1000)

like_username
string

Fuzzy search username as substring

Responses

Response samples

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

Add rule for 'username'

Add new rule for 'username'

Authorizations:
basicAuthNone
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 rules for clients

Show the list of rules for clients

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

Page number of the results to fetch.

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

Results per page(max 1000)

like_clientid
string

Fuzzy search clientid as substring

Responses

Response samples

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

Add rule for 'clientid'

Add new rule for 'clientid'

Authorizations:
basicAuthNone
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"
}

Delete rule for 'clientid'

Delete rule for 'clientid'

Authorizations:
basicAuthNone
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

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

Get rule for 'clientid'

Get rule for 'clientid'

Authorizations:
basicAuthNone
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

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

Set rule for 'clientid'

Set rule for 'clientid'

Authorizations:
basicAuthNone
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
{
  • "clientid": "client1",
  • "rules": [
    ]
}

Response samples

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

Get a authorization source

Get a authorization source

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

Authorization type

Responses

Response samples

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

List all authorization sources

List all authorization sources

Authorizations:
basicAuthNone

Responses

Response samples

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

Add a new source

Add a new source

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

Set to true or false to disable this ACL provider.

type
required
string
Default: "file"
Value: "file"

Backend type.

rules
required
string

Authorization static file rules.

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "type": "file",
  • "rules": "{allow,{username,{re,\"^dashboard$\"}},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}."
}

Response samples

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

Delete rule for 'username'

Delete rule for 'username'

Authorizations:
basicAuthNone
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

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

Get rule for 'username'

Get rule for 'username'

Authorizations:
basicAuthNone
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:
basicAuthNone
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 all rules

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

Authorizations:
basicAuthNone

Responses

Response samples

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

Change order of sources

Change the exection order of sources

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

Authorization type

Request Body schema: application/json
position
required
string

Where to place the source.

Responses

Request samples

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

Response samples

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

Delete source

Delete source

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

Authorization type

Responses

Response samples

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

Get a authorization source

Get a authorization source

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

Authorization type

Responses

Response samples

Content type
application/json
Example
{
  • "enable": true,
  • "type": "file",
  • "rules": "{allow,{username,{re,\"^dashboard$\"}},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}."
}

Update source

Update source

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

Authorization type

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

Set to true or false to disable this ACL provider.

type
required
string
Default: "file"
Value: "file"

Backend type.

rules
required
string

Authorization static file rules.

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "type": "file",
  • "rules": "{allow,{username,{re,\"^dashboard$\"}},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}."
}

Response samples

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

Clean authorization cache in cluster

Clean all authorization cache in the cluster.

Authorizations:
basicAuthNone

Responses

Response samples

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

Get authorization settings

Get authorization settings

Authorizations:
basicAuthNone

Responses

Response samples

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

Update authorization settings

Update authorization settings

Authorizations:
basicAuthNone
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 (broker.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": {
    }
}

Delete rules for 'all'

Delete rules for 'all'

Authorizations:
basicAuthNone

Responses

Show rules for 'all'

Show the list of rules for 'all'

Authorizations:
basicAuthNone

Responses

Response samples

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

Update rules for 'all'

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

Authorizations:
basicAuthNone
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 stats

Get node stats

Authorizations:
basicAuthNone
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,
  • "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 metrics

Get node metrics

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

Node name

Responses

Response samples

Content type
application/json
{
  • "node": "string",
  • "actions.failure": 0,
  • "actions.success": 0,
  • "bytes.received": 0,
  • "bytes.sent": 0,
  • "client.auth.anonymous": 0,
  • "client.authenticate": 0,
  • "client.check_authz": 0,
  • "client.connack": 0,
  • "client.connect": 0,
  • "client.connected": 0,
  • "client.disconnected": 0,
  • "client.subscribe": 0,
  • "client.unsubscribe": 0,
  • "delivery.dropped": 0,
  • "delivery.dropped.expired": 0,
  • "delivery.dropped.no_local": 0,
  • "delivery.dropped.qos0_msg": 0,
  • "delivery.dropped.queue_full": 0,
  • "delivery.dropped.too_large": 0,
  • "messages.acked": 0,
  • "messages.delayed": 0,
  • "messages.delivered": 0,
  • "messages.dropped": 0,
  • "messages.dropped.await_pubrel_timeout": 0,
  • "messages.dropped.no_subscribers": 0,
  • "messages.forward": 0,
  • "messages.publish": 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.received": 0,
  • "messages.retained": 0,
  • "messages.sent": 0,
  • "packets.auth.received": 0,
  • "packets.auth.sent": 0,
  • "packets.connack.auth_error": 0,
  • "packets.connack.error": 0,
  • "packets.connack.sent": 0,
  • "packets.connect.received": 0,
  • "packets.disconnect.received": 0,
  • "packets.disconnect.sent": 0,
  • "packets.pingreq.received": 0,
  • "packets.pingresp.sent": 0,
  • "packets.puback.inuse": 0,
  • "packets.puback.missed": 0,
  • "packets.puback.received": 0,
  • "packets.puback.sent": 0,
  • "packets.pubcomp.inuse": 0,
  • "packets.pubcomp.missed": 0,
  • "packets.pubcomp.received": 0,
  • "packets.pubcomp.sent": 0,
  • "packets.publish.auth_error": 0,
  • "packets.publish.dropped": 0,
  • "packets.publish.error": 0,
  • "packets.publish.inuse": 0,
  • "packets.publish.received": 0,
  • "packets.publish.sent": 0,
  • "packets.pubrec.inuse": 0,
  • "packets.pubrec.missed": 0,
  • "packets.pubrec.received": 0,
  • "packets.pubrec.sent": 0,
  • "packets.pubrel.missed": 0,
  • "packets.pubrel.received": 0,
  • "packets.pubrel.sent": 0,
  • "packets.received": 0,
  • "packets.sent": 0,
  • "packets.suback.sent": 0,
  • "packets.subscribe.auth_error": 0,
  • "packets.subscribe.error": 0,
  • "packets.subscribe.received": 0,
  • "packets.unsuback.sent": 0,
  • "packets.unsubscribe.error": 0,
  • "packets.unsubscribe.received": 0,
  • "rules.matched": 0,
  • "session.created": 0,
  • "session.discarded": 0,
  • "session.resumed": 0,
  • "session.takenover": 0,
  • "session.terminated": 0
}

Get node info

Get node info

Authorizations:
basicAuthNone
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,
  • "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:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ExHook

Delete the server

Delete the server

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

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

Get server details

Get the detail information of Exhook server

Authorizations:
basicAuthNone
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:
basicAuthNone
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
{
  • "auto_reconnect": "60s",
  • "enable": true,
  • "failed_action": "deny",
  • "name": "default",
  • "pool_size": 8,
  • "request_timeout": "5s",
  • "ssl": {
    },
  • "url": "http://127.0.0.1:8081"
}

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
}

Change order of execution for registered Exhook server

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

Authorizations:
basicAuthNone
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": "front"
}

Response samples

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

List servers

List all servers

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a server

Add a server

Authorizations:
basicAuthNone
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
{
  • "auto_reconnect": "60s",
  • "enable": true,
  • "failed_action": "deny",
  • "name": "default",
  • "pool_size": 8,
  • "request_timeout": "5s",
  • "ssl": {
    },
  • "url": "http://127.0.0.1:8081"
}

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 server hooks information

Get the hooks information of server

Authorizations:
basicAuthNone
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:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "push_gateway_server": "http://127.0.0.1:9091"
}

Update Prometheus config

Update Prometheus config

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

URL of Prometheus server

interval
required
string
Default: "15s"

Data reporting interval

headers
Array of objects
Default: {}

A list of HTTP Headers when pushing to Push Gateway.

For example, { Authorization = "some-authz-tokens"}

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

Job Name that is pushed to the Push Gateway. Available variables:

- ${name}: Name of EMQX node.

- ${host}: Host name of EMQX node.

For example, when the EMQX node name is emqx@127.0.0.1 then the name variable takes value emqx and the host variable takes value 127.0.0.1.

Default value is: ${name}/instance/${name}~${host}

enable
required
boolean
Default: false

Turn Prometheus data pushing on or off

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "push_gateway_server": "http://127.0.0.1:9091"
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "push_gateway_server": "http://127.0.0.1:9091"
}

Get Prometheus Data

Get Prometheus Data

Responses

Response samples

Content type
{ }

Auto Subscribe

Get auto subscribe topics

Get auto subscribe topic list

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update auto subscribe topics

Update auto subscribe topic list

Authorizations:
basicAuthNone
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

Delete the listener's authenticator

Remove authenticator for the listener.

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Responses

Response samples

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

Get the listener's authenticator

Get the listener's authenticator configs.

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Responses

Response samples

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

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

Whether to use JWKS.

endpoint
required
string

JWKS endpoint, it's a read-only endpoint that returns the server's public key set in the JWKS format.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

refresh_interval
integer
Default: 300

JWKS refresh interval.

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

Authentication mechanism.

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: {}

A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.

from
string
Default: "password"
Enum: "username" "password"

Field to take JWT from.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

Whether to use JWKS.

endpoint
required
string

JWKS endpoint, it's a read-only endpoint that returns the server's public key set in the JWKS format.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

refresh_interval
integer
Default: 300

JWKS refresh interval.

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

Authentication mechanism.

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: {}

A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.

from
string
Default: "password"
Enum: "username" "password"

Field to take JWT from.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Request Body schema: application/json
One of
id
string

Listener ID

type
string
Value: "dtls"

Listener Type

name
string

Listener Name

running
boolean

Listener Running status

acceptors
integer
Default: 16

Size of the acceptor pool.

object (gateway.udp_opts)
enable
boolean
Default: true

Enable the listener.

integer or string

The IP address and port that the listener will bind.

max_connections
integer
Default: 1024

Maximum number of concurrent connections.

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.
Variables in mountpoint string:

- ${clientid}: clientid

- ${username}: username

access_rules
Array of strings
Default: ""

The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny

object (gateway.dtls_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Delete listener

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

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Responses

Response samples

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

Get listener config

Get the gateway listener configs

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Responses

Response samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

Request Body schema: application/json
One of
id
string

Listener ID

type
string
Value: "dtls"

Listener Type

name
string

Listener Name

running
boolean

Listener Running status

acceptors
integer
Default: 16

Size of the acceptor pool.

object (gateway.udp_opts)
enable
boolean
Default: true

Enable the listener.

integer or string

The IP address and port that the listener will bind.

max_connections
integer
Default: 1024

Maximum number of concurrent connections.

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.
Variables in mountpoint string:

- ${clientid}: clientid

- ${username}: username

access_rules
Array of strings
Default: ""

The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny

object (gateway.dtls_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Response samples

Content type
application/json
Example
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Delete user

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

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

id
required
string

Listener ID

uid
required
string

User 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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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": {
    }
}

List authenticator's users

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

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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": {
    }
}

Telemetry

Get telemetry status

Get telemetry status

Authorizations:
basicAuthNone

Responses

Response samples

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

Enable or disable telemetry

Enable or disable telemetry

Authorizations:
basicAuthNone
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:
basicAuthNone

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
}

Cluster

Get cluster info

Get cluster info

Authorizations:
basicAuthNone

Responses

Response samples

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

Force leave node from cluster

Force leave node from cluster

Authorizations:
basicAuthNone
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"
}

Invite node to cluster

Invite node to cluster

Authorizations:
basicAuthNone
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"
}

Gateway Clients

Kick out client

Kick out the gateway client

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Client ID

name
required
string

Gateway Name

Responses

Response samples

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

Get client info

Get the gateway client information

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Client ID

name
required
string

Gateway Name

Responses

Response samples

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

List client's subscription

Get the gateway client subscriptions

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Client ID

name
required
string

Gateway Name

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Add subscription for client

Create a subscription membership

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Client ID

name
required
string

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,
  • "qos": 1,
  • "rap": 0,
  • "rh": 0,
  • "topic": "test/topic"
}

Response samples

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

Delete client's subscription

Delete a subscriptions membership

Authorizations:
basicAuthNone
path Parameters
topic
required
string

Topic Filter/Name

clientid
required
string

Client ID

name
required
string

Gateway Name

Responses

Response samples

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

List gateway's clients

Get the gateway client list

Authorizations:
basicAuthNone
path Parameters
name
required
string

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 .. 1000 ]
Default: 100
Example: limit=50

Results per page(max 1000)

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:
basicAuthNone
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:
basicAuthNone
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 Rule

Test a rule

Authorizations:
basicAuthNone
Request Body schema: application/json
emqx_rule_api_schema.ctx_delivery_dropped (object) or emqx_rule_api_schema.ctx_bridge_mqtt (object) or emqx_rule_api_schema.ctx_check_authz_complete (object) or emqx_rule_api_schema.ctx_connack (object) or emqx_rule_api_schema.ctx_disconnected (object) or emqx_rule_api_schema.ctx_connected (object) or emqx_rule_api_schema.ctx_dropped (object) or emqx_rule_api_schema.ctx_acked (object) or emqx_rule_api_schema.ctx_delivered (object) or emqx_rule_api_schema.ctx_unsub (object) or emqx_rule_api_schema.ctx_sub (object) or emqx_rule_api_schema.ctx_pub (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"
}

List All Rules

List all rules

Authorizations:
basicAuthNone
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

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

Page number of the results to fetch.

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

Results per page(max 1000)

Responses

Response samples

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

Create Rule By ID

Create a new rule using given Id

Authorizations:
basicAuthNone
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",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Get Metric

Get a rule's metrics by given Id

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

List All Events Can Be Used In Rule

List all events can be used in rules

Authorizations:
basicAuthNone

Responses

Response samples

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

Reset Rule Metrics

Reset a rule metrics

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

Delete Cluster Rule

Delete a rule by given Id from all nodes in the cluster

Authorizations:
basicAuthNone
path Parameters
id
required
string
Example: my_rule_id

Responses

Get Rule

Get a rule by given Id

Authorizations:
basicAuthNone
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",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Update Cluster Rule

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

Authorizations:
basicAuthNone
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",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Get configuration

Get rule engine configuration.

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "ignore_sys_message": true,
  • "jq_function_default_timeout": "32s"
}

Update configuration

Update rule engine configuration.

Authorizations:
basicAuthNone
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"
}

Clients

Clean client authz cache in the cluster.

Clean client authz cache in the cluster.

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Responses

Response samples

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

Get client authz cache in the cluster.

Get client authz cache in the cluster.

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "access": "string",
  • "result": "string",
  • "topic": "string",
  • "updated_time": 0
}

Kick out client by client ID

Kick out client by client ID

Authorizations:
basicAuthNone
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:
basicAuthNone
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "awaiting_rel_cnt": 0,
  • "awaiting_rel_max": 0,
  • "clean_start": true,
  • "clientid": "string",
  • "connected": true,
  • "connected_at": 1640995200000,
  • "created_at": 1640995200000,
  • "disconnected_at": 1640995200000,
  • "expiry_interval": 0,
  • "heap_size": 0,
  • "inflight_cnt": 0,
  • "inflight_max": 0,
  • "ip_address": "string",
  • "is_bridge": true,
  • "keepalive": 0,
  • "mailbox_len": 0,
  • "mqueue_dropped": 0,
  • "mqueue_len": 0,
  • "mqueue_max": 0,
  • "node": "string",
  • "port": 0,
  • "proto_name": "string",
  • "proto_ver": 0,
  • "recv_cnt": 0,
  • "recv_msg": 0,
  • "recv_msg.dropped": 0,
  • "recv_msg.dropped.await_pubrel_timeout": 0,
  • "recv_msg.qos0": 0,
  • "recv_msg.qos1": 0,
  • "recv_msg.qos2": 0,
  • "recv_oct": 0,
  • "recv_pkt": 0,
  • "reductions": 0,
  • "send_cnt": 0,
  • "send_msg": 0,
  • "send_msg.dropped": 0,
  • "send_msg.dropped.expired": 0,
  • "send_msg.dropped.queue_full": 0,
  • "send_msg.dropped.too_large": 0,
  • "send_msg.qos0": 0,
  • "send_msg.qos1": 0,
  • "send_msg.qos2": 0,
  • "send_oct": 0,
  • "send_pkt": 0,
  • "subscriptions_cnt": 0,
  • "subscriptions_max": 0,
  • "username": "string",
  • "mountpoint": "string",
  • "zone": "string"
}

Unsubscribe bulk

Unsubscribe bulk

Authorizations:
basicAuthNone
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:
basicAuthNone
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:
basicAuthNone
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": "string",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0
}

Response samples

Content type
application/json
{
  • "node": "string",
  • "topic": "string",
  • "clientid": "string",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0
}

Unsubscribe

Unsubscribe

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

Topic

Responses

Request samples

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

Response samples

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

Get client subscriptions

Get client subscriptions

Authorizations:
basicAuthNone
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List clients

List clients

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

Page number of the results to fetch.

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

Results per page(max 1000)

node
string
Example: node=emqx@127.0.0.1

Node name

username
string

User name

zone
string
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)

Responses

Response samples

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

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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:
basicAuthNone
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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Responses

Response samples

Content type
application/json
Example
{
  • "connection_required": false,
  • "enable": true,
  • "enable_stats": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "listeners": [
    ],
  • "mountpoint": "coap/",
  • "name": "coap",
  • "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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Request Body schema: application/json
One of
required
object (emqx_exproto_schema.exproto_grpc_server)
required
object (emqx_exproto_schema.exproto_grpc_handler)
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.
Variables in mountpoint string:

- ${clientid}: clientid

- ${username}: username

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
{
  • "connection_required": false,
  • "enable": true,
  • "enable_stats": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "mountpoint": "coap2/",
  • "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

get trace log file's metadata, such as size, last update time

Authorizations:
basicAuthNone
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:
basicAuthNone
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"
}

Clear all traces

Clear all traces

Authorizations:
basicAuthNone

Responses

List all trace

List all trace

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new trace

Create new trace

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

Unique and format by [a-zA-Z0-9-_]

type
required
string
Enum: "clientid" "topic" "ip_address"

Filter type

topic
string

support mqtt wildcard topic.

clientid
string

mqtt clientid.

ip_address
string

client ip address

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

Responses

Request samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "payload_encode": "hex",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "end_at": "2021-11-05T18:17:38+08:00"
}

Response samples

Content type
application/json
{
  • "name": "EMQX-TRACE-1",
  • "type": "clientid",
  • "topic": "/dev/#",
  • "clientid": "dev-001",
  • "ip_address": "127.0.0.1",
  • "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": [
    ]
}

view trace log

view trace log

Authorizations:
basicAuthNone
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:
basicAuthNone
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:
basicAuthNone
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",
  • "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": [
    ]
}

Dashboard

Dashboard list users

Dashboard list users

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create dashboard user

Create dashboard user

Authorizations:
basicAuthNone
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"
}

Get Dashboard Auth Token.

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": {
    }
}

Delete dashboard user

Delete dashboard user

Authorizations:
basicAuthNone
path Parameters
username
required
string
Example: admin

Dashboard Username

Responses

Response samples

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

Update dashboard user description

Update dashboard user description

Authorizations:
basicAuthNone
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"
}

Change dashboard user password

Change dashboard user password

Authorizations:
basicAuthNone
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"

Responses

Response samples

Content type
application/json
"string"

Dashboard user logout

Dashboard user logout

Authorizations:
basicAuthNone
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 specified type.

List all running node's listeners for the specified type.

Authorizations:
basicAuthNone
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:
basicAuthNone
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 (broker.listener_quic_ssl_opts)
enabled
boolean
Default: true

Enable listener.

required
integer or 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: 5000000

The maximum number of concurrent connections allowed by the listener.

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.


Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username

zone
string
Default: "default"

The configuration zone to which the listener belongs.

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 to allow any clients with or without authentication information such as username or password to log in.
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

Maximum connection rate.

This is used to limit the connection rate for this listener,
once the limit is reached, new connections will be deferred or refused

messages_rate
string

Messages publish rate.

This is used to limit the inbound message numbers for each client connected to this listener,
once the limit is reached, the restricted client will slow down and even be hung for a while.

bytes_rate
string

Data publish rate.

This is used to limit the inbound bytes rate for each client connected to this listener,
once the limit is reached, the restricted client will slow down and even be hung for a while.

Responses

Request samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "name": "demo",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp",
  • "zone": "default"
}

Response samples

Content type
application/json
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "0.0.0.0:1884",
  • "current_connections": 10240,
  • "id": "tcp:demo",
  • "max_connections": 204800,
  • "mountpoint": "/",
  • "proxy_protocol": false,
  • "proxy_protocol_timeout": "3s",
  • "running": true,
  • "tcp_options": {
    },
  • "type": "tcp",
  • "zone": "default"
}

Stop the listener on all nodes.

Stop the listener on all nodes.

Authorizations:
basicAuthNone
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:
basicAuthNone
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:
basicAuthNone
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 live status. group by listener type

List all running node's listeners live status. group by listener type

Authorizations:
basicAuthNone

Responses

Response samples

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

Gateway Authentication

Delete gateway authenticator

Delete the authenticator of the specified gateway.

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Responses

Response samples

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

Get authenticator configuration

Gets the configuration of the specified gateway authenticator.

Returns 404 when gateway or authentication is not enabled.

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Responses

Response samples

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

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

Whether to use JWKS.

endpoint
required
string

JWKS endpoint, it's a read-only endpoint that returns the server's public key set in the JWKS format.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

refresh_interval
integer
Default: 300

JWKS refresh interval.

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

Authentication mechanism.

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: {}

A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.

from
string
Default: "password"
Enum: "username" "password"

Field to take JWT from.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

Request Body schema: application/json
One of
use_jwks
required
string
Value: true

Whether to use JWKS.

endpoint
required
string

JWKS endpoint, it's a read-only endpoint that returns the server's public key set in the JWKS format.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

refresh_interval
integer
Default: 300

JWKS refresh interval.

object (broker.ssl_client_opts)
mechanism
required
string
Value: "jwt"

Authentication mechanism.

acl_claim_name
string
Default: "acl"

JWT claim name to use for getting ACL rules.

verify_claims
Array of strings
Default: {}

A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.

from
string
Default: "password"
Enum: "username" "password"

Field to take JWT from.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Import users

Import users into the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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

Responses

Response samples

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

List users for gateway authenticator

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

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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

Page number of the results to fetch.

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

Results per page(max 1000)

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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": {
    }
}

Delete user for gateway authenticator

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

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

uid
required
string
Example: test_username

User ID

Responses

Response samples

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

Get user info for gateway authenticator

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

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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": {
    }
}

Import users

Import users into the gateway authenticator (only supports built_in_database)

Authorizations:
basicAuthNone
path Parameters
name
required
string
Example: stomp

Gateway Name.

It's enum with stomp, mqttsn, coap, lwm2m, exproto

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
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

CoAP Gateways

Send a Request to a Client

Send a CoAP request message to the client

Authorizations:
basicAuthNone
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:
basicAuthNone
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

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

Results per page(max 1000)

Responses

Response samples

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

Delete matching messages

Delete matching messages.

Authorizations:
basicAuthNone
path Parameters
topic
required
string

Topic.

Responses

Response samples

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

Lookup a message

Lookup a message by a topic without wildcards.

Authorizations:
basicAuthNone
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"
}

View config

View config

Authorizations:
basicAuthNone

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "backend": {
    }
}

Update retainer config

Update retainer config.

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

Enable retainer feature

msg_expiry_interval
string
Default: "0s"

Message retention time. 0 means message will never be expired.

msg_clear_interval
string
Default: "0s"

Periodic interval for cleaning up expired messages.
Never clear if the value is 0.

max_payload_size
string
Default: "1MB"

Maximum 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

object (retainer.mnesia_config)

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "backend": {
    }
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "msg_expiry_interval": "32s",
  • "msg_clear_interval": "32s",
  • "max_payload_size": "32MB",
  • "stop_publish_clear_msg": false,
  • "backend": {
    }
}

Alarms

Remove all historical alarms.

Remove all historical alarms.

Authorizations:
basicAuthNone

Responses

List alarms

List currently activated alarms or historical alarms, determined by query parameters.

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

Page number of the results to fetch.

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

Results per page(max 1000)

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": {
    }
}

Subscriptions

List subscriptions

List subscriptions

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

Page number of the results to fetch.

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

Results per page(max 1000)

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

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"
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:
basicAuthNone

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:
basicAuthNone
Request Body schema: application/json
enable
boolean
Default: false

Enable this feature

threshold
string
Default: "500ms"

The latency threshold for statistics

expire_interval
string
Default: "300s"

The eviction time of the record, which in the statistics record table

top_k_num
integer >= 1
Default: 10

The maximum number of records in the slow subscription statistics record table

stats_type
string
Default: "whole"
Enum: "whole" "internal" "response"

The method to calculate the latency

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"
}

Clear current data and re count slow topic

Clear current data and re count slow topic

Authorizations:
basicAuthNone

Responses

View slow topics statistics record data

View slow topics statistics record data

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

Page number of the results to fetch.

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

Results per page(max 1000)

Responses

Response samples

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

API Keys

Return api_key list

Return api_key list

Authorizations:
basicAuthNone

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

Create new api_key

Authorizations:
basicAuthNone
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
}

Delete the specific api_key

Delete the specific api_key

Authorizations:
basicAuthNone
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"
}

Return the specific api_key

Return the specific api_key

Authorizations:
basicAuthNone
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

Update the specific api_key

Authorizations:
basicAuthNone
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
}

Banned

List all banned client IDs

List all currently banned client IDs, usernames and IP addresses.

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

Page number of the results to fetch.

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

Results per page(max 1000)

Responses

Response samples

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

Ban client ID, username or IP address

Add a client ID, username or IP address to the blacklist.

Authorizations:
basicAuthNone
Request Body schema: application/json
as
required
string
Enum: "clientid" "username" "peerhost"

Ban method, which can be client ID, username or IP address.

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

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": [
    ]
}

Unban a client ID, username or IP address

Remove a client ID, username or IP address from the blacklist.

Authorizations:
basicAuthNone
path Parameters
as
required
string
Enum: "clientid" "username" "peerhost"
Example: username

Ban method, which can be client ID, username or IP address.

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"
}