< Submit API issue
API docs by Redocly

EMQX Enterprise API (5.6.1)

Download OpenAPI specification:Download

Authentication

Move authenticator in global authentication chain.

Move authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

position
required
string
Example: before:password_based:built_in_database

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

Responses

Response samples

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

Get user from authenticator in global authenticati

Get user from authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

user_id
required
string

User ID.

Responses

Response samples

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

Update user in authenticator in global authenticat

Update user in authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

user_id
required
string

User ID.

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

Responses

Request samples

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

Response samples

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

Delete user in authenticator in global authenticat

Delete user in authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

user_id
required
string

User ID.

Responses

Response samples

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

Import users into authenticator in global authenti

Import users into authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

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

The import file template type, enum with plain,hash

Request Body schema:

Import body

filename
string <binary>

Responses

Request samples

Content type
No sample

Response samples

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

List users in authenticator in global authenticati

List users in authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

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

Page number of the results to fetch.

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

Results per page(max 10000)

like_user_id
string

Fuzzy search user_id (username or clientid).

is_superuser
boolean

Is superuser

Responses

Response samples

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

Create users for authenticator in global authentic

Create users for authenticator in global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

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

Responses

Request samples

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

Response samples

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

Get authenticator status from global authenticatio

Get authenticator status from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

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

Get authenticator from global authentication chain

Get authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

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

Update authenticator from global authentication ch

Update authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

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

Authentication mechanism.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Delete authenticator from global authentication ch

Delete authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

Response samples

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

List authenticators for global authentication.

List authenticators for global authentication.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create authenticator for global authentication.

Create authenticator for global authentication.

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

Authentication mechanism.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Reorder all authenticators in global authenticatio

Reorder all authenticators in global authentication chain.

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

Authenticator ID.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Actions

Reset action metrics

Reset a bridge metrics by id.

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

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

Responses

Response samples

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

Manually start a bridge

Start bridge on all nodes in the cluster.

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

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

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

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

Enable or disable bridge

Enable or Disable bridge on all nodes in the cluster.

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

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

enable
required
boolean
Example: true

Whether to enable this bridge.

Responses

Response samples

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

List bridges

List all created bridges.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create bridge

Create a new bridge by type and name.

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

The Bridge Type

name
required
string

Bridge name.

local_topic
string

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

enable
boolean
Default: true

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

connector
required
string

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

required
object (bridge_pgsql.action_parameters)
object (actions_and_sources.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_azure_event_hub_producer_action",
  • "type": "azure_event_hub_producer",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_azure_event_hub_producer_connector",
  • "local_topic": "mqtt/local/topic"
}

Response samples

Content type
application/json
Example
{
  • "name": "my_azure_event_hub_producer_action",
  • "status": "connected",
  • "type": "azure_event_hub_producer",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_azure_event_hub_producer_connector",
  • "node_status": [
    ],
  • "local_topic": "mqtt/local/topic"
}

Test creating bridge

Test creating a new bridge.

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

The Bridge Type

name
required
string

Bridge name.

local_topic
string

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

enable
boolean
Default: true

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

connector
required
string

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

required
object (bridge_pgsql.action_parameters)
object (actions_and_sources.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_azure_event_hub_producer_action",
  • "type": "azure_event_hub_producer",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_azure_event_hub_producer_connector",
  • "local_topic": "mqtt/local/topic"
}

Response samples

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

List available action types

Lists the available action types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "http",
  • "rocketmq",
  • "cassandra",
  • "rabbitmq",
  • "pulsar",
  • "greptimedb",
  • "hstreamdb",
  • "influxdb",
  • "mongodb",
  • "azure_event_hub_producer",
  • "confluent_producer",
  • "gcp_pubsub_producer",
  • "iotdb",
  • "kafka_producer",
  • "sqlserver",
  • "syskeeper_forwarder",
  • "kinesis",
  • "opents",
  • "redis",
  • "s3",
  • "mqtt",
  • "clickhouse",
  • "tdengine",
  • "oracle",
  • "timescale",
  • "elasticsearch",
  • "matrix",
  • "mysql",
  • "pgsql",
  • "dynamo"
]

Get bridge

Get a bridge by id.

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

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

Responses

Response samples

Content type
application/json
Example
{
  • "name": "my_azure_event_hub_producer_action",
  • "status": "connected",
  • "type": "azure_event_hub_producer",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_azure_event_hub_producer_connector",
  • "node_status": [
    ],
  • "local_topic": "mqtt/local/topic"
}

Update bridge

Update a bridge by id.

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

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

Request Body schema: application/json
One of
local_topic
string

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

enable
boolean
Default: true

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

connector
required
string

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

required
object (bridge_pgsql.action_parameters)
object (actions_and_sources.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_azure_event_hub_producer_connector",
  • "local_topic": "mqtt/local/topic"
}

Response samples

Content type
application/json
Example
{
  • "name": "my_azure_event_hub_producer_action",
  • "status": "connected",
  • "type": "azure_event_hub_producer",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_azure_event_hub_producer_connector",
  • "node_status": [
    ],
  • "local_topic": "mqtt/local/topic"
}

Delete bridge

Delete a bridge by id.

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

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

query Parameters
also_delete_dep_actions
boolean
Default: false

Whether to cascade delete dependent actions.

Responses

Response samples

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

Get action metrics

Get bridge metrics by id.

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

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

Responses

Response samples

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

Manually start a bridge on a given node

Start bridge on a specific node.

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

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

id
required
string
Example: http:my_http_action

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

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

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

Metrics

EMQX metrics

EMQX metrics

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Whether to aggregate all nodes Metrics

Responses

Response samples

Content type
application/json
Example
[ ]

EMQX stats

EMQX stats

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Calculation aggregate for all nodes

Responses

Response samples

Content type
application/json
Example
[ ]

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

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

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

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

EMQX node name.

Responses

Response samples

Content type
application/json
{
  • "dropped_msg_rate": 0,
  • "sent_msg_rate": 0,
  • "received_msg_rate": 0,
  • "subscriptions": 0,
  • "topics": 0,
  • "connections": 0,
  • "live_connections": 0,
  • "node_uptime": 0,
  • "retained_msg_count": 0,
  • "shared_subscriptions": 0,
  • "license_quota": 0
}

List the monitor (statistics) data on the specifie

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

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

EMQX node name.

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List monitor (statistics) data for the whole clust

List monitor (statistics) data for the whole cluster.

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

MQTT

Get delayed status

Get delayed status

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Enable or disable delayed, set max delayed message

Enable or disable delayed, set max delayed messages

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

Enable this feature

max_delayed_messages
integer
Default: 0

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

Responses

Request samples

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

Response samples

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

View delayed message

View delayed message

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

The node where message from

msgid
required
string

Delayed Message ID

Responses

Response samples

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

Delete delayed message

Delete delayed message

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

The node where message from

msgid
required
string

Delayed Message ID

Responses

Response samples

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

List all rewrite rules

List all rewrite rules

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update all rewrite rules

Update all rewrite rules

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

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

source_topic
required
string

Source topic, specified by the client.

dest_topic
required
string

Destination topic.

re
required
string

Regular expressions

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Get topic metrics

Get topic metrics

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

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

Responses

Response samples

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

Delete topic metrics

Delete topic metrics

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

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

Responses

Response samples

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

Delete delayed message

Delete delayed message

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic

Responses

Response samples

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

List topic metrics

List topic metrics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reset telemetry status

Reset telemetry status

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

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

action
required
string

Action. Only support reset

Responses

Request samples

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

Response samples

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

Create topic metrics

Create topic metrics

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

Raw topic string

Responses

Request samples

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

Response samples

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

List delayed messages

List delayed messages

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

LwM2M Gateways

Observe a Resource

Observe or Cancel observe a resource

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

Responses

Response samples

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

List Client's Resources

Look up a resource

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

Responses

Response samples

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

Read Value from a Resource Path

Send a read command to a resource

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

Responses

Response samples

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

Write a Value to Resource Path

Send a write command to a resource

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

Responses

Response samples

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

Plugins

Get a plugin description

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

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

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

Responses

Response samples

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

Delete a plugin

Uninstalls a previously uploaded plugin package.

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

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

Responses

Response samples

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

Trigger action on an installed plugin

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

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

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

action
required
string
Enum: "start" "stop"

Action

Responses

Response samples

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

List all installed plugins

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Move plugin within plugin hiearchy

Setting the boot order of plugins.

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

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

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


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

Responses

Request samples

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

Response samples

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

Install a new plugin

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

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

Responses

Response samples

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

Bridges

Reset bridge metrics

Reset a bridge metrics by Id

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

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

Responses

Response samples

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

Stop/restart bridge

Stop/Restart bridges on a specific node.

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

The node name, e.g. emqx@127.0.0.1

id
required
string
Example: http:http_example

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

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

Operations can be one of: stop, restart

Responses

Response samples

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

Test creating bridge

Test creating a new bridge by given ID

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

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Enum: "kafka" "kafka_producer" "kafka_consumer"

The Action Type

name
required
string

Action name, used as a human-readable identifier.

enable
boolean
Default: true

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

bootstrap_hosts
required
string

A comma separated list of Kafka host:port endpoints to bootstrap the client.

connect_timeout
string
Default: "5s"

Maximum wait time for TCP connection establishment (including authentication time if enabled).

min_metadata_refresh_interval
string
Default: "3s"

Minimum time interval the client has to wait before refreshing Kafka broker and topic metadata. Setting too small value may add extra load on Kafka.

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
object (bridge_kafka.connector_resource_opts)
local_topic
string

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

required
object (bridge_kafka.producer_kafka_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "demo",
  • "type": "influxdb_api_v2",
  • "ssl": {
    },
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "precision": "ms",
  • "org": "examlpe_org",
  • "token": "example_token",
  • "bucket": "example_bucket",
  • "resource_opts": {
    },
  • "local_topic": "local/topic/#",
  • "write_syntax": "${topic},clientid=${clientid} payload=${payload},${clientid}_int_value=${payload.int_key}i,uint_value=${payload.uint_key}u,bool=${payload.bool}",
  • "influxdb_type": "influxdb_api_v2"
}

Response samples

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

Enable or disable bridge

Enable or Disable bridges on all nodes in the cluster.

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

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

enable
required
boolean
Example: true

Whether to enable this bridge

Responses

Response samples

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

Get bridge metrics

Get bridge metrics by Id

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

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

Responses

Response samples

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

Get bridge

Get a bridge by Id

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

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

Responses

Response samples

Content type
application/json
Example
{
  • "name": "demo",
  • "type": "influxdb_api_v2",
  • "ssl": {
    },
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "precision": "ms",
  • "org": "examlpe_org",
  • "token": "example_token",
  • "bucket": "example_bucket",
  • "resource_opts": {
    },
  • "local_topic": "local/topic/#",
  • "write_syntax": "${topic},clientid=${clientid} payload=${payload},${clientid}_int_value=${payload.int_key}i,uint_value=${payload.uint_key}u,bool=${payload.bool}",
  • "influxdb_type": "influxdb_api_v2"
}

Update bridge

Update a bridge by Id

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

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

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

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

bootstrap_hosts
required
string

A comma separated list of Kafka host:port endpoints to bootstrap the client.

connect_timeout
string
Default: "5s"

Maximum wait time for TCP connection establishment (including authentication time if enabled).

min_metadata_refresh_interval
string
Default: "3s"

Minimum time interval the client has to wait before refreshing Kafka broker and topic metadata. Setting too small value may add extra load on Kafka.

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
object (bridge_kafka.connector_resource_opts)
local_topic
string

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

required
object (bridge_kafka.producer_kafka_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "demo",
  • "type": "influxdb_api_v2",
  • "ssl": {
    },
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "precision": "ms",
  • "org": "examlpe_org",
  • "token": "example_token",
  • "bucket": "example_bucket",
  • "resource_opts": {
    },
  • "local_topic": "local/topic/#",
  • "write_syntax": "${topic},clientid=${clientid} payload=${payload},${clientid}_int_value=${payload.int_key}i,uint_value=${payload.uint_key}u,bool=${payload.bool}",
  • "influxdb_type": "influxdb_api_v2"
}

Response samples

Content type
application/json
Example
{
  • "name": "demo",
  • "type": "influxdb_api_v2",
  • "ssl": {
    },
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "precision": "ms",
  • "org": "examlpe_org",
  • "token": "example_token",
  • "bucket": "example_bucket",
  • "resource_opts": {
    },
  • "local_topic": "local/topic/#",
  • "write_syntax": "${topic},clientid=${clientid} payload=${payload},${clientid}_int_value=${payload.int_key}i,uint_value=${payload.uint_key}u,bool=${payload.bool}",
  • "influxdb_type": "influxdb_api_v2"
}

Delete bridge

Delete a bridge by Id

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

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

Responses

Response samples

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

Stop or restart bridge

Stop/Restart bridges on all nodes in the cluster.

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

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

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

Operations can be one of: stop, restart

Responses

Response samples

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

List bridges

List all created bridges

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create bridge

Create a new bridge by type and name

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Enum: "kafka" "kafka_producer" "kafka_consumer"

The Action Type

name
required
string

Action name, used as a human-readable identifier.

enable
boolean
Default: true

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

bootstrap_hosts
required
string

A comma separated list of Kafka host:port endpoints to bootstrap the client.

connect_timeout
string
Default: "5s"

Maximum wait time for TCP connection establishment (including authentication time if enabled).

min_metadata_refresh_interval
string
Default: "3s"

Minimum time interval the client has to wait before refreshing Kafka broker and topic metadata. Setting too small value may add extra load on Kafka.

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
object (bridge_kafka.connector_resource_opts)
local_topic
string

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

required
object (bridge_kafka.producer_kafka_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "demo",
  • "type": "influxdb_api_v2",
  • "ssl": {
    },
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "precision": "ms",
  • "org": "examlpe_org",
  • "token": "example_token",
  • "bucket": "example_bucket",
  • "resource_opts": {
    },
  • "local_topic": "local/topic/#",
  • "write_syntax": "${topic},clientid=${clientid} payload=${payload},${clientid}_int_value=${payload.int_key}i,uint_value=${payload.uint_key}u,bool=${payload.bool}",
  • "influxdb_type": "influxdb_api_v2"
}

Response samples

Content type
application/json
Example
{
  • "name": "demo",
  • "type": "influxdb_api_v2",
  • "ssl": {
    },
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "precision": "ms",
  • "org": "examlpe_org",
  • "token": "example_token",
  • "bucket": "example_bucket",
  • "resource_opts": {
    },
  • "local_topic": "local/topic/#",
  • "write_syntax": "${topic},clientid=${clientid} payload=${payload},${clientid}_int_value=${payload.int_key}i,uint_value=${payload.uint_key}u,bool=${payload.bool}",
  • "influxdb_type": "influxdb_api_v2"
}

Status

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

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

This endpoint requires no authentication.

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

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

query Parameters
format
string
Default: "text"

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

Responses

Topics

Lookup topic info by name

Lookup topic info by name

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic Name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Topics list

Topics list

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

Topic Name

node
string
Example: node=emqx@127.0.0.1

Node Name

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

File Transfer

Download a particular file

Get a file by its id.

Authorizations:
basicAuthbearerAuth
query Parameters
node
required
string
Example: node=emqx@127.0.0.1

Node under which the file is located

fileref
required
string
Example: fileref=file1

File reference

Responses

Response samples

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

List all uploaded files

List all uploaded files.

Authorizations:
basicAuthbearerAuth
query Parameters
following
string

Cursor to start listing files from

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

Results per page(max 10000)

Responses

Response samples

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

Get current File Transfer configuration

Show current File Transfer configuration.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false,
  • "init_timeout": "32s",
  • "store_segment_timeout": "32s",
  • "assemble_timeout": "32s",
  • "storage": {
    }
}

Update File Transfer configuration

Replace File Transfer configuration.

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

Enable the File Transfer feature.

Enabling File Transfer implies reserving special MQTT topics in order to serve the protocol.

This toggle also affects the availability of the File Transfer REST API and
storage-dependent background activities (e.g. garbage collection).

init_timeout
string
Default: "10s"

Timeout for EMQX to initialize the file transfer.

After reaching the timeout (e.g. due to system is overloaded), the PUBACK message for init will contain error code (0x80).

store_segment_timeout
string
Default: "5m"

Timeout for storing a file segment.

After reaching the timeout (e.g. due to system overloaded), the PUBACK message will contain error code (0x80).

assemble_timeout
string
Default: "5m"

Timeout for assembling and exporting file segments into a final file.

After reaching the timeout (e.g. due to system is overloaded), the PUBACK message for fin will contain error code (0x80)

object (file_transfer.storage_backend)

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "init_timeout": "32s",
  • "store_segment_timeout": "32s",
  • "assemble_timeout": "32s",
  • "storage": {
    }
}

Response samples

Content type
application/json
{
  • "enable": false,
  • "init_timeout": "32s",
  • "store_segment_timeout": "32s",
  • "assemble_timeout": "32s",
  • "storage": {
    }
}

List files uploaded in a specific transfer

List a file uploaded during specified transfer, identified by client id and file id.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

MQTT Client ID

fileid
required
string

File ID

Responses

Response samples

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

Authorization

Show the list of rules for users

Show the list of rules for users

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

Page number of the results to fetch.

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

Results per page(max 10000)

like_username
string

Fuzzy search username as substring

Responses

Response samples

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

Add new rule for 'username'

Add new rule for 'username'

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

Username

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Show the list of rules for clients

Show the list of rules for clients

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

Page number of the results to fetch.

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

Results per page(max 10000)

like_clientid
string

Fuzzy search clientid as substring

Responses

Response samples

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

Add new rule for 'clientid'

Add new rule for 'clientid'

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

ClientID

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Get rule for 'clientid'

Get rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

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

Set rule for 'clientid'

Set rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

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

ClientID

Responses

Request samples

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

Response samples

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

Delete rule for 'clientid'

Delete rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

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

Get a authorization source

Get a authorization source

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

Authorization type

Responses

Response samples

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

List all authorization sources

List all authorization sources

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Add a new source

Add a new source

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

Backend type.

enable
boolean
Default: true

Set to true or false to disable this ACL provider

publish_attribute
string
Default: "mqttPublishTopic"

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

subscribe_attribute
string
Default: "mqttSubscriptionTopic"

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

all_attribute
string
Default: "mqttPubSubTopic"

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

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

server
required
string

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

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

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

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

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

password
string <password>

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

base_dn
required
string

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

filter
string
Default: "(objectClass=mqttUser)"

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

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

request_timeout
string
Default: "10s"

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

object (ldap.ssl)

Responses

Request samples

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

Response samples

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

Get rule for 'username'

Get rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

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

Set rule for 'username'

Set rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

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

Username

Responses

Request samples

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

Response samples

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

Delete rule for 'username'

Delete rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

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

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

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Change the exection order of sources

Change the exection order of sources

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

Authorization type

Request Body schema: application/json
position
required
string

Responses

Request samples

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

Response samples

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

Get a authorization source

Get a authorization source

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

Authorization type

Responses

Response samples

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

Update source

Update source

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

Authorization type

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

Backend type.

enable
boolean
Default: true

Set to true or false to disable this ACL provider

publish_attribute
string
Default: "mqttPublishTopic"

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

subscribe_attribute
string
Default: "mqttSubscriptionTopic"

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

all_attribute
string
Default: "mqttPubSubTopic"

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

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

server
required
string

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

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

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

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

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

password
string <password>

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

base_dn
required
string

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

filter
string
Default: "(objectClass=mqttUser)"

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

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

request_timeout
string
Default: "10s"

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

object (ldap.ssl)

Responses

Request samples

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

Response samples

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

Delete source

Delete source

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

Authorization type

Responses

Response samples

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

Reorder all authorization sources.

Reorder all authorization sources.

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

Authorization type

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Clean all authorization cache in the cluster.

Clean all authorization cache in the cluster.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Get authorization settings

Get authorization settings

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update authorization settings

Update authorization settings

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

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

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

The action when the authorization check rejects an operation.

object (emqx.authz_cache)

Responses

Request samples

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

Response samples

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

Show the list of rules for 'all'

Show the list of rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Delete rules for 'all'

Delete rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

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

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

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

Responses

Request samples

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

Response samples

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

Nodes

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

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

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

Node name

Responses

Response samples

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

Get node run-time counter metrics. Such as receive

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

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

Node name

Responses

Response samples

Content type
application/json
{
  • "node": "string",
  • "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.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:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx@127.0.0.1

Node name

Responses

Response samples

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

List EMQX nodes

List EMQX nodes

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ExHook

Get the detail information of Exhook server

Get the detail information of Exhook server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

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

Update the server

Update the server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Request Body schema: application/json
name
required
string

Name of the exhook server

enable
boolean
Default: true

Enable this Exhook server

url
required
string

URL of the gRPC server

request_timeout
string
Default: "5s"

The timeout of request gRPC server

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

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

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

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

pool_size
integer >= 1
Default: 8

The process pool size for gRPC client

Responses

Request samples

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

Response samples

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

Delete the server

Delete the server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

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

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Request Body schema: application/json
position
required
string

The target position to be moved

Responses

Request samples

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

Response samples

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

List all servers

List all servers

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a server

Add a server

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

Name of the exhook server

enable
boolean
Default: true

Enable this Exhook server

url
required
string

URL of the gRPC server

request_timeout
string
Default: "5s"

The timeout of request gRPC server

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

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

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

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

pool_size
integer >= 1
Default: 8

The process pool size for gRPC client

Responses

Request samples

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

Response samples

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

Get the hooks information of server

Get the hooks information of server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Monitor

Get Prometheus config info

Get Prometheus config info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update Prometheus config

Update Prometheus config

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

Deprecated since 5.4.0, use prometheus.push_gateway.url instead

interval
required
string
Default: "15s"

Deprecated since 5.4.0, use prometheus.push_gateway.interval instead

headers
object
Default: {}

Deprecated since 5.4.0, use prometheus.push_gateway.headers instead

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

Deprecated since 5.4.0, use prometheus.push_gateway.job_name instead

enable
required
boolean
Default: false

Deprecated since 5.4.0, use prometheus.push_gateway.url instead

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

Deprecated since 5.4.0, use prometheus.collectors.vm_dist instead

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

Deprecated since 5.4.0, use prometheus.collectors.mnesia instead

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

Deprecated since 5.4.0, use prometheus.collectors.vm_statistics instead

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

Deprecated, use prometheus.collectors.vm_system_info instead

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

Deprecated since 5.4.0, use prometheus.collectors.vm_memory instead

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

Deprecated since 5.4.0, use prometheus.collectors.vm_msacc instead

Responses

Request samples

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

Response samples

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

Get Prometheus Metrics for Data Integration

Get Prometheus Metrics for Data Integration

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


Metrics format mode.

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

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

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

Responses

Response samples

Content type
No sample

Get Prometheus Metrics

Get Prometheus Metrics

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


Metrics format mode.

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

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

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

Responses

Response samples

Content type
No sample

Get Prometheus Metrics for AuthN, AuthZ and Banned

Get Prometheus Metrics for AuthN, AuthZ and Banned

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


Metrics format mode.

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

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

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

Responses

Response samples

Content type
No sample

Get opentelmetry configuration

Get opentelmetry configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "traces": {
    },
  • "logs": {
    },
  • "exporter": {}
}

Update opentelmetry configuration

Update opentelmetry configuration

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (opentelemetry.otel_metrics)
object (opentelemetry.otel_logs)
object (opentelemetry.otel_traces)
object (opentelemetry.otel_exporter)

Responses

Request samples

Content type
application/json
{
  • "metrics": {
    },
  • "traces": {
    },
  • "logs": {
    },
  • "exporter": {}
}

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "traces": {
    },
  • "logs": {
    },
  • "exporter": {}
}

Auto Subscribe

Get auto subscribe topic list

Get auto subscribe topic list

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update auto subscribe topic list

Update auto subscribe topic list

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

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

qos
integer [ 0 .. 2 ]
Default: 0

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

rh
integer [ 0 .. 2 ]
Default: 0

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

rap
integer [ 0 .. 1 ]
Default: 0

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

nl
integer [ 0 .. 1 ]
Default: 0

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

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Load Rebalance

Start evacuation on a node

Start evacuation process

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

Node name

Request Body schema: application/json
wait_health_check
string

Time to wait before starting the rebalance/evacuation process, in seconds

conn_evict_rate
integer >= 1

The rate of evicting connections, in connections per second

sess_evict_rate
integer >= 1

The rate of evicting sessions, in sessions per second

redirect_to
string

Server reference to redirect clients to (MQTTv5 Server redirection)

wait_takeover
string

Time to wait before starting session evacuation process, in seconds

migrate_to
Array of strings

Nodes to migrate sessions to

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{ }

Get rebalance status

Get rebalance status of the current node

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "status": "enabled",
  • "process": "rebalance",
  • "state": "string",
  • "coordinator_node": "string",
  • "connection_eviction_rate": 1,
  • "session_eviction_rate": 1,
  • "connection_goal": 0,
  • "session_goal": 0,
  • "disconnected_session_goal": 0,
  • "session_recipients": [
    ],
  • "recipients": [
    ],
  • "stats": {
    }
}

Stop evacuation on a node

Stop evacuation process

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

Node name

Responses

Response samples

Content type
application/json
{ }

Start rebalancing with the node as coordinator

Start rebalance process

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

Node name

Request Body schema: application/json
wait_health_check
string

Time to wait before starting the rebalance/evacuation process, in seconds

conn_evict_rate
integer >= 1

The rate of evicting connections, in connections per second

sess_evict_rate
integer >= 1

The rate of evicting sessions, in sessions per second

abs_conn_threshold
integer >= 1

Maximum desired difference between the number of connections on the node and the average number of connections on the recipient nodes. Difference lower than this is the goal of the rebalance process.

rel_conn_threshold
number

Maximum desired fraction between the number of connections on the node and the average number of connections on the recipient nodes. Fraction lower than this is the goal of the rebalance process.

abs_sess_threshold
integer >= 1

Maximum desired difference between the number of sessions on the node and the average number of sessions on the recipient nodes. Difference lower than this is the goal of the evacuation process.

rel_sess_threshold
number

Maximum desired fraction between the number of sessions on the node and the average number of sessions on the recipient nodes. Fraction lower than this is the goal of the evacuation process

wait_takeover
string

Time to wait before starting session evacuation process, in seconds

nodes
Array of strings

Nodes to participate in rebalance

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{ }

Stop rebalancing coordinated by the node

Stop rebalance process

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

Node name

Responses

Response samples

Content type
application/json
{ }

Node rebalance availability check

Check if the node is being evacuated or rebalanced

Responses

Response samples

Content type
application/json
{ }

Get global rebalance status

Get status of all rebalance/evacuation processes across the cluster

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "evacuations": [
    ],
  • "purges": [
    ],
  • "rebalances": [
    ]
}

Gateway Listeners

Get the listener's authenticator

Get the listener's authenticator configs.

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

Gateway Name

id
required
string

Listener ID

Responses

Response samples

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

Update config of authenticator for listener

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

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

Gateway Name

id
required
string

Listener ID

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

Authentication mechanism.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Delete the listener's authenticator

Remove authenticator for the listener.

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

Gateway Name

id
required
string

Listener ID

Responses

Response samples

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

Create authenticator for listener

Enable authenticator for specified listener for client authentication.

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

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

Gateway Name

id
required
string

Listener ID

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

Authentication mechanism.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

List all listeners

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

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

Gateway Name

Responses

Response samples

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

Add listener

Create the gateway listener.

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

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

Gateway Name

Request Body schema: application/json
One of
id
string

Listener ID

type
string
Value: "wss"

Listener Type

name
string

Listener Name

running
boolean

Listener Running status

acceptors
integer
Default: 16

Size of the acceptor pool.

object (emqx.tcp_opts)
proxy_protocol
boolean
Default: false

Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

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

enable
boolean
Default: true

Enable the listener.

bind
string

The IP address and port that the listener will bind.

string or integer
Default: 1024

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

- ${clientid}: clientid

- ${username}: username

- ${endpoint_name}: endpoint name

access_rules
Array of strings
Default: []

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

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

Responses

Request samples

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

Response samples

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

Get listener config

Get the gateway listener configs

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

Gateway Name

id
required
string

Listener ID

Responses

Response samples

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

Update listener config

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

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

Gateway Name

id
required
string

Listener ID

Request Body schema: application/json
One of
id
string

Listener ID

type
string
Value: "wss"

Listener Type

name
string

Listener Name

running
boolean

Listener Running status

acceptors
integer
Default: 16

Size of the acceptor pool.

object (emqx.tcp_opts)
proxy_protocol
boolean
Default: false

Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

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

enable
boolean
Default: true

Enable the listener.

bind
string

The IP address and port that the listener will bind.

string or integer
Default: 1024

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

- ${clientid}: clientid

- ${username}: username

- ${endpoint_name}: endpoint name

access_rules
Array of strings
Default: []

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

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

Responses

Request samples

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

Response samples

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

Delete listener

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

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

Gateway Name

id
required
string

Listener ID

Responses

Response samples

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

Get user info

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

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

Gateway Name

id
required
string

Listener ID

uid
required
string

User ID

Responses

Response samples

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

Update user info

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

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

Gateway Name

id
required
string

Listener ID

uid
required
string

User ID

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

Responses

Request samples

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

Response samples

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

Delete user

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

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

Gateway Name

id
required
string

Listener ID

uid
required
string

User ID

Responses

Response samples

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

List authenticator's users

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

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

Gateway Name

id
required
string

Listener ID

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Add user for an authenticator

Add user for the authenticator (only supports built_in_database)

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

Gateway Name

id
required
string

Listener ID

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

Responses

Request samples

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

Response samples

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

Configs

Get the sub-configurations under *sys_topics*

Get the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *sys_topics*

Update the sub-configurations under sys_topics

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

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

string or string
Default: "30s"

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

object (emqx.event_names)

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *sysmon*

Get the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *sysmon*

Update the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx.sysmon_vm)
object (emqx.sysmon_os)

Responses

Request samples

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

Response samples

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

Get the MQTT-related configuration

Get the MQTT-related configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update MQTT-related configuration

Update MQTT-related configuration

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

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *alarm*

Get the sub-configurations under alarm

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *alarm*

Update the sub-configurations under alarm

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

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

Get the sub-configurations under file_transfer

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false,
  • "init_timeout": "32s",
  • "store_segment_timeout": "32s",
  • "assemble_timeout": "32s",
  • "storage": {
    }
}

Update the sub-configurations under *file_transfer*

Update the sub-configurations under file_transfer

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

Enable the File Transfer feature.

Enabling File Transfer implies reserving special MQTT topics in order to serve the protocol.

This toggle also affects the availability of the File Transfer REST API and
storage-dependent background activities (e.g. garbage collection).

init_timeout
string
Default: "10s"

Timeout for EMQX to initialize the file transfer.

After reaching the timeout (e.g. due to system is overloaded), the PUBACK message for init will contain error code (0x80).

store_segment_timeout
string
Default: "5m"

Timeout for storing a file segment.

After reaching the timeout (e.g. due to system overloaded), the PUBACK message will contain error code (0x80).

assemble_timeout
string
Default: "5m"

Timeout for assembling and exporting file segments into a final file.

After reaching the timeout (e.g. due to system is overloaded), the PUBACK message for fin will contain error code (0x80)

object (file_transfer.storage_backend)

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "init_timeout": "32s",
  • "store_segment_timeout": "32s",
  • "assemble_timeout": "32s",
  • "storage": {
    }
}

Response samples

Content type
application/json
{
  • "enable": false,
  • "init_timeout": "32s",
  • "store_segment_timeout": "32s",
  • "assemble_timeout": "32s",
  • "storage": {
    }
}

Get the sub-configurations under *dashboard*

Get the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *dashboard*

Update the sub-configurations under dashboard

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

JWT token expiration time. Default is 60 minutes

cors
boolean
Default: false

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

swagger_support
boolean
Default: true

Enable or disable support for swagger API documentation.

object (dashboard.sso)

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *broker*

Get the sub-configurations under broker

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *broker*

Update the sub-configurations under broker

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

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

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

Advantages of Disabling

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

session_history_retain
string
Default: "0s"

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

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

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

Responses

Request samples

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

Response samples

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

Reset the config entry specified by the query stri

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

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

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

The config path separated by '.' character

Responses

Response samples

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

Get all the configurations of the specified keys,

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

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

Node's name. Will deprecated in 5.2.0.

Responses

Response samples

Content type
No sample

Update the configurations of the specified keys.

Update the configurations of the specified keys.

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

Responses

Response samples

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

Get the sub-configurations under *log*

Get the sub-configurations under log

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *log*

Update the sub-configurations under log

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

File-based log handlers.

object (emqx.log_throttling)
object (emqx.log_audit_handler)

Responses

Request samples

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

Response samples

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

Clients

Kick out a batch of client by client IDs

Kick out a batch of client by client IDs

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

Responses

Request samples

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

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

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

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

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

Responses

Response samples

Content type
application/json
"string"

Get client authz cache in the cluster.

Get client authz cache in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

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

Clean client authz cache in the cluster.

Clean client authz cache in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

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

Get clients info by client ID

Get clients info by client ID

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

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

Kick out client by client ID

Kick out client by client ID

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

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

Unsubscribe bulk

Unsubscribe bulk

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

Topic

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Subscribe bulk

Subscribe bulk

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

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Subscribe

Subscribe

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

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

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

Response samples

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

Get client mqueue messages

Get client mqueue messages

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

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

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

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

string or string or string
Example: position=none

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

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

Results per page(max 10000)

Responses

Response samples

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

Get client in-flight messages

Get client in-flight messages

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

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

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

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

string or string or string
Example: position=none

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

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

Results per page(max 10000)

Responses

Response samples

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

Unsubscribe

Unsubscribe

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

Topic

Responses

Request samples

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

Response samples

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

Get client subscriptions

Get client subscriptions

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List clients

List clients

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

Page number of the results to fetch.

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

Results per page(max 10000)

node
string
Example: node=emqx@127.0.0.1

Node name

username
Array of strings

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

ip_address
string
Example: ip_address=127.0.0.1

Client's IP address

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

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

clean_start
boolean

Whether the client uses a new session

proto_ver
string

Client protocol version

like_clientid
string

Fuzzy search clientid as substring

like_username
string

Fuzzy search username as substring

integer or string

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

integer or string

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

integer or string

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

integer or string

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

clientid
Array of strings

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

Array of strings or string
Default: "all"

Comma separated list of client fields to return in the response

Responses

Response samples

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

Connectors

Test creating connector

Test creating a new connector.

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

The type of the connector.

name
required
string

The name of the connector.

enable
boolean
Default: true

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

server
required
string

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

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

The PostgreSQL default port 5432 is used if [:Port] is not specified.

database
required
string

Database name.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

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

password
string <password>

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

auto_reconnect
boolean
Deprecated
Default: true

Deprecated. Enable automatic reconnect to the database.

object (emqx.ssl_client_opts)
object (connector_postgres.resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    }
}

Response samples

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

Get connector

Get a connector by id.

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

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

Responses

Response samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "status": "connected",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    },
  • "node_status": [
    ],
  • "actions": [
    ]
}

Update connector

Update a connector by id.

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

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

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

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

server
required
string

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

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

The PostgreSQL default port 5432 is used if [:Port] is not specified.

database
required
string

Database name.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

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

password
string <password>

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

auto_reconnect
boolean
Deprecated
Default: true

Deprecated. Enable automatic reconnect to the database.

object (emqx.ssl_client_opts)
object (connector_postgres.resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "status": "connected",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    },
  • "node_status": [
    ],
  • "actions": [
    ]
}

Delete connector

Delete a connector by id.

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

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

Responses

Response samples

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

Manually start a connector

Start connector on all nodes in the cluster.

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

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

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

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

Manually start a connector on a given node

Start connector on a specific node.

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

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

id
required
string
Example: http:my_http_connector

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

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

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

Enable or disable connector

Enable or Disable connector on all nodes in the cluster.

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

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

enable
required
boolean
Example: true

Whether to enable this connector.

Responses

Response samples

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

List connectors

List all created connectors.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create connector

Create a new connector by type and name.

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

The type of the connector.

name
required
string

The name of the connector.

enable
boolean
Default: true

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

server
required
string

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

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

The PostgreSQL default port 5432 is used if [:Port] is not specified.

database
required
string

Database name.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

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

password
string <password>

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

auto_reconnect
boolean
Deprecated
Default: true

Deprecated. Enable automatic reconnect to the database.

object (emqx.ssl_client_opts)
object (connector_postgres.resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "status": "connected",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    },
  • "node_status": [
    ],
  • "actions": [
    ]
}

Sources

Manually start a bridge on a given node

Start bridge on a specific node.

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

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

id
required
string
Example: http:my_http_action

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

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

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

List sources

List all created bridges.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create source

Create a new bridge by type and name.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "rabbitmq"
name
required
string
enable
boolean
Default: true

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

connector
required
string

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

required
object (bridge_rabbitmq.source_parameters)
object (actions_and_sources.source_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_action",
  • "type": "gcp_pubsub_consumer",
  • "description": "my source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "connected",
  • "description": "my source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Get source

Get a bridge by id.

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

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

Responses

Response samples

Content type
application/json
Example
{
  • "status": "connected",
  • "description": "my source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Update source

Update a bridge by id.

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

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

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

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

connector
required
string

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

required
object (bridge_rabbitmq.source_parameters)
object (actions_and_sources.source_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "description": "my source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "connected",
  • "description": "my source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Delete source

Delete a bridge by id.

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

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

query Parameters
also_delete_dep_actions
boolean
Default: false

Whether to cascade delete dependent actions.

Responses

Response samples

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

List available source types

Lists the available source types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "rabbitmq",
  • "gcp_pubsub_consumer",
  • "kafka_consumer",
  • "mqtt"
]

Reset source metrics

Reset a bridge metrics by id.

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

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

Responses

Response samples

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

Enable or disable bridge

Enable or Disable bridge on all nodes in the cluster.

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

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

enable
required
boolean
Example: true

Whether to enable this bridge.

Responses

Response samples

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

Test creating bridge

Test creating a new bridge.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "rabbitmq"
name
required
string
enable
boolean
Default: true

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

connector
required
string

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

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

required
object (bridge_rabbitmq.source_parameters)
object (actions_and_sources.source_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_action",
  • "type": "gcp_pubsub_consumer",
  • "description": "my source",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_connector",
  • "resource_opts": {
    }
}

Response samples

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

Get source metrics

Get bridge metrics by id.

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

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

Responses

Response samples

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

Manually start a bridge

Start bridge on all nodes in the cluster.

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

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

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

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

Schema Registry

List registered schemas

List all registered schemas

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register a new schema

Register a new schema

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

A name for the schema that will serve as its identifier.

type
required
string
Value: "json"

Must be json for JSON schema.

source
required
string

Source text for the schema.

description
string
Default: ""

A description for this schema.

Responses

Request samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Response samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Get registered schema

Get a schema by its name

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

The schema name

Responses

Response samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Update a schema

Update an existing schema

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

The schema name

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

Must be json for JSON schema.

source
required
string

Source text for the schema.

description
string
Default: ""

A description for this schema.

Responses

Request samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Response samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Delete registered schema

Delete a schema

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

The schema name

Responses

Response samples

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

Dashboard Single Sign-On

/sso

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/sso/saml/acs

Responses

Response samples

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

/sso/saml/metadata

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "version": "5.0.0",
  • "license": {
    }
}

/sso/login/{backend}

path Parameters
backend
required
string
Enum: "ldap" "saml"
Example: ldap
Request Body schema: application/json
One of
backend
required
string
Value: "saml"

Backend type.

Responses

Request samples

Content type
application/json
Example
{
  • "backend": "saml"
}

Response samples

Content type
application/json
{
  • "role": "administrator",
  • "token": "string",
  • "version": "5.0.0",
  • "license": {
    }
}

/sso/running

Responses

Response samples

Content type
application/json
[
  • "ldap"
]

/sso/{backend}

Authorizations:
basicAuthbearerAuth
path Parameters
backend
required
string
Enum: "ldap" "saml"
Example: ldap

Responses

Response samples

Content type
application/json
Example
{}

/sso/{backend}

Authorizations:
basicAuthbearerAuth
path Parameters
backend
required
string
Enum: "ldap" "saml"
Example: ldap
Request Body schema: application/json
One of
enable
boolean
Default: false

Whether to enable this backend.

backend
required
string
Value: "saml"

Backend type.

dashboard_addr
string
Default: "https://127.0.0.1:18083"

The address of the EMQX Dashboard.

idp_metadata_url
string
Default: "https://idp.example.com"

The URL of the IdP metadata.

sp_sign_request
boolean
Default: false

Whether to sign the SAML request.

sp_public_key
string
Default: "Pub Key"

The public key of the SP.

sp_private_key
string <password>

The private key of the SP.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{}

/sso/{backend}

Authorizations:
basicAuthbearerAuth
path Parameters
backend
required
string
Enum: "ldap" "saml"
Example: ldap

Responses

Response samples

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

Data Backup

Download a data backup file

Download a data backup file

Authorizations:
basicAuthbearerAuth
path Parameters
filename
required
string

Data backup file name

query Parameters
node
string

Node name

Responses

Response samples

Content type
application/json
"binary"

Delete a data backup file

Delete a data backup file

Authorizations:
basicAuthbearerAuth
path Parameters
filename
required
string

Data backup file name

query Parameters
node
string

Node name

Responses

Response samples

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

Export a data backup file

Export a data backup file

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Import a data backup file

Import a data backup file

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

Node name

filename
required
string

Data backup file name

Responses

Request samples

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

Response samples

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

List backup files

List backup files

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Upload a data backup file

Upload a data backup file

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

Responses

Response samples

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

Cluster

Get cluster info

Get cluster info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Force leave node from cluster

Force leave node from cluster

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

node name

Responses

Response samples

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

Send a join invitation to a node to join the clust

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

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

node name

Responses

Response samples

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

Invite node to cluster

Invite node to cluster

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

node name

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

Timeout in milliseconds

Responses

Request samples

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

Response samples

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

Get RLOG cluster topology: connections between cor

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the execution status of all asynchronous invit

Get the execution status of all asynchronous invite status per node

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

GCP Devices

List all devices imported from GCP IoT Core

List all devices imported from GCP IoT Core

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Import authentication and config data for devices

Import authentication and config data for devices from GCP IoT Core

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
blocked
required
boolean

Blocked

deviceid
required
string

Device identifier

registry
string
Default: ""

Device registry identifier

project
string
Default: ""

Cloud project identifier

location
string
Default: ""

Cloud region

Array of objects (emqx_gcp_device_api.key)
Default: []

Public keys associated to GCP device

config
required
string

Configuration

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "errors": 0,
  • "imported": 14
}

Get a device imported from GCP IoT Core

Get a device imported from GCP IoT Core

Authorizations:
basicAuthbearerAuth
path Parameters
deviceid
required
string
Example: c2-ec-x509

Device identifier

Responses

Response samples

Content type
application/json
{
  • "created_at": 1690484400,
  • "deviceid": "c2-ec-x509",
  • "registry": "my-registry",
  • "project": "iot-export",
  • "location": "europe-west1",
  • "keys": [ ],
  • "config": "bXktY29uZmln"
}

Update a device imported from GCP IoT Core

Update a device imported from GCP IoT Core

Authorizations:
basicAuthbearerAuth
path Parameters
deviceid
required
string
Example: c2-ec-x509

Device identifier

Request Body schema: application/json
registry
string
Default: ""

Device registry identifier

project
string
Default: ""

Cloud project identifier

location
string
Default: ""

Cloud region

Array of objects (emqx_gcp_device_api.key)
Default: []

Public keys associated to GCP device

config
required
string

Configuration

Responses

Request samples

Content type
application/json
{
  • "registry": "my-registry",
  • "project": "iot-export",
  • "location": "europe-west1",
  • "keys": [ ],
  • "config": "bXktY29uZmln"
}

Response samples

Content type
application/json
{
  • "deviceid": "c2-ec-x509",
  • "registry": "my-registry",
  • "project": "iot-export",
  • "location": "europe-west1",
  • "keys": [ ],
  • "config": "bXktY29uZmln"
}

Remove a device imported from GCP IoT Core

Remove a device imported from GCP IoT Core

Authorizations:
basicAuthbearerAuth
path Parameters
deviceid
required
string
Example: c2-ec-x509

Device identifier

Responses

Gateway Clients

Get client info

Get the gateway client information

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "gbt32960" "jt808" "lwm2m" "mqttsn" "ocpp" "stomp"

Gateway Name

Responses

Response samples

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

Kick out client

Kick out the gateway client

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "gbt32960" "jt808" "lwm2m" "mqttsn" "ocpp" "stomp"

Gateway Name

Responses

Response samples

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

List client's subscription

Get the gateway client subscriptions

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "gbt32960" "jt808" "lwm2m" "mqttsn" "ocpp" "stomp"

Gateway Name

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Add subscription for client

Create a subscription membership

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "gbt32960" "jt808" "lwm2m" "mqttsn" "ocpp" "stomp"

Gateway Name

Request Body schema: application/json
topic
string

Topic Filter/Name

qos
integer

QoS level, enum: 0, 1, 2

nl
integer

No Local option, enum: 0, 1

rap
integer

Retain as Published option, enum: 0, 1

rh
integer

Retain Handling option, enum: 0, 1, 2

object (emqx_gateway_api_clients.extra_sub_props)

Responses

Request samples

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

Response samples

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

Delete client's subscription

Delete a subscriptions membership

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic Filter/Name

clientid
required
string

Client ID

name
required
string
Enum: "coap" "exproto" "gbt32960" "jt808" "lwm2m" "mqttsn" "ocpp" "stomp"

Gateway Name

Responses

Response samples

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

List gateway's clients

Get the gateway client list

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

Gateway Name

query Parameters
node
string

Match the client's node name

clientid
string

Match the client's ID

username
string

Match the client's Username

ip_address
string

Match the client's ip address

conn_state
string

Match the client's connection state

proto_ver
string

Match the client's protocol version

clean_start
boolean

Match the client's clean start flag

like_clientid
string

Use sub-string to match client's ID

like_username
string

Use sub-string to match client's username

integer or string

Match the session created datetime greater than a certain value

integer or string

Match the session created datetime less than a certain value

integer or string

Match the client socket connected datetime greater than a certain value

integer or string

Match the client socket connected datatime less than a certain value

endpoint_name
string

Match the lwm2m client's endpoint name

like_endpoint_name
string

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

gte_lifetime
string

Match the lwm2m client registered lifetime greater than a certain value

lte_lifetime
string

Match the lwm2m client registered lifetime less than a certain value

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Publish

Publish a batch of messages

Possible HTTP response status code are:

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

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

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

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


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

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

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

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

topic
required
string

Topic Name

qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

clientid
string
Deprecated
payload
required
string

The MQTT message payload.

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

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

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Publish a message

Possible HTTP status response codes are:

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

202: No matched subscribers;

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

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

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

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

topic
required
string

Topic Name

qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

clientid
string
Deprecated
payload
required
string

The MQTT message payload.

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

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

Responses

Request samples

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

Response samples

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

Rules

Test a rule

Test a rule

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

List all rules

Authorizations:
basicAuthbearerAuth
query Parameters
enable
boolean

Filter enable/disable rules

from
string

Filter rules by from(topic), exact match

like_id
string

Filter rules by id, Substring matching

like_from
string

Filter rules by from(topic), Substring matching

like_description
string

Filter rules by description, Substring matching

match_from
string

Filter rules by from(topic), Mqtt topic matching

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Create a rule

Create a new rule using given Id

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

The name of the rule

sql
required
string

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

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

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

enable
boolean
Default: true

Enable or disable the rule

description
string
Default: ""

The description of the rule

metadata
object

Rule metadata, do not change manually

Responses

Request samples

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

Response samples

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

Get rule metrics

Get a rule's metrics by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

List rule events

List all events can be used in rules

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Reset rule metrics

Reset a rule metrics

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

Get rule

Get a rule by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

Update rule

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

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

The name of the rule

sql
required
string

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

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

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

enable
boolean
Default: true

Enable or disable the rule

description
string
Default: ""

The description of the rule

metadata
object

Rule metadata, do not change manually

Responses

Request samples

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

Response samples

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

Delete rule

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

Get rule engine configuration.

Get rule engine configuration.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update rule engine configuration.

Update rule engine configuration.

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

When set to 'true' (default), rule-engine will ignore messages published to $SYS topics.

jq_function_default_timeout
string
Default: "10s"

Default timeout for the jq rule engine function

Responses

Request samples

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

Response samples

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

Gateways

Enable or disable gateway

Update the gateway basic configurations and running status.

Note: The Authentication and Listener configurations should be updated by other special APIs.

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

Gateway Name

enable
required
boolean
Example: true

Whether to enable this gateway

Responses

Response samples

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

List all gateways

This API returns an overview info for the specified or all gateways.
including current running status, number of connections, listener status, etc.

Authorizations:
basicAuthbearerAuth
query Parameters
status
string
Enum: "running" "stopped" "unloaded"
Example: status=running

Filter gateways by status.

It is enum with running, stopped, unloaded

Responses

Response samples

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

Get gateway

Get the gateway configurations

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

Gateway Name

Responses

Response samples

Content type
application/json
Example
{
  • "name": "coap",
  • "enable": true,
  • "heartbeat": "30s",
  • "listeners": [
    ],
  • "idle_timeout": "30s",
  • "mountpoint": "coap/",
  • "enable_stats": true,
  • "connection_required": false,
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Load or update the gateway confs

Update the gateway basic configurations and running status.

Note: The Authentication and Listener configurations should be updated by other special APIs.

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

Gateway Name

Request Body schema: application/json
One of
object (gateway.stomp_frame)
mountpoint
string
Default: ""

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

- ${clientid}: clientid

- ${username}: username

- ${endpoint_name}: endpoint name

enable
boolean
Default: true

Whether to enable this gateway

enable_stats
boolean
Default: true

Whether to enable client process statistic

idle_timeout
string
Default: "30s"

The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.

object (gateway.clientinfo_override)

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "mountpoint": "coap2/",
  • "enable_stats": true,
  • "connection_required": false,
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Response samples

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

Trace

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

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

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download trace log by name

Download trace log by name

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

query Parameters
node
string
Example: node=emqx@127.0.0.1

Node name

Responses

Response samples

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

List all trace

List all trace

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear all traces

Clear all traces

Authorizations:
basicAuthbearerAuth

Responses

Create new trace

Create new trace

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

Unique name of the trace. Only ascii letters in a-z, A-Z, 0-9 and underscore '_' are allowed.

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

Filter type

topic
string

Specify the topic or topic filter if the trace 'type' is 'topic'.

clientid
string

Specify the MQTT clientid if the trace 'type' is 'clientid'.

ip_address
string

Specify the client's IP address if the trace type is 'ip_address'.

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:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

query Parameters
bytes
integer [ 0 .. 2147483647 ]
Default: 1000

Maximum number of bytes to send in response

position
integer
Default: 0

Offset from the current trace position.

node
string
Example: node=emqx@127.0.0.1

Node name

Responses

Response samples

Content type
application/json
{
  • "items": "TEXT-LOG-ITEMS",
  • "meta": {
    }
}

Delete specified trace

Delete specified trace

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

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

Stop trace by name

Stop trace by name

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-TRACE-1

[a-zA-Z0-9-_]

Responses

Response samples

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create dashboard user

Create dashboard user

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
username
string <= 100 characters

Dashboard Username

password
string <= 100 characters

Dashboard Password

role
string
Default: "administrator"

User role

description
string

Dashboard User Description

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "public",
  • "role": "administrator",
  • "description": "administrator"
}

Response samples

Content type
application/json
{
  • "username": "admin",
  • "role": "administrator",
  • "description": "administrator",
  • "backend": "local"
}

Dashboard authentication

Get Dashboard Auth Token.

Request Body schema: application/json
username
string <= 100 characters

Dashboard Username

password
string <= 100 characters

Dashboard Password

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "public"
}

Response samples

Content type
application/json
{
  • "role": "administrator",
  • "token": "string",
  • "version": "5.0.0",
  • "license": {
    }
}

Update dashboard user description

Update dashboard user description

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

query Parameters
backend
string
Enum: "local" "ldap" "saml"
Example: backend=local
Request Body schema: application/json
role
string
Default: "administrator"

User role

description
string

Dashboard User Description

Responses

Request samples

Content type
application/json
{
  • "role": "administrator",
  • "description": "administrator"
}

Response samples

Content type
application/json
{
  • "username": "admin",
  • "role": "administrator",
  • "description": "administrator",
  • "backend": "local"
}

Delete dashboard user

Delete dashboard user

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

query Parameters
backend
string
Enum: "local" "ldap" "saml"
Example: backend=local

Responses

Response samples

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

Change dashboard user password

Change dashboard user password

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Request Body schema: application/json
old_pwd
string

Old password

new_pwd
string

New password

Responses

Request samples

Content type
application/json
{
  • "old_pwd": "string",
  • "new_pwd": "string"
}

Response samples

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

Get the schema JSON of the specified name. NOTE: o

Get the schema JSON of the specified name. NOTE: only intended for EMQX Dashboard.

path Parameters
name
required
string
Enum: "hotconf" "bridges" "actions" "connectors"

Responses

Response samples

Content type
application/json
"string"

Dashboard user logout.<br/>This endpoint is only f

Dashboard user logout.
This endpoint is only for the Dashboard, not the API Key.
The token from the /login endpoint must be a bearer authorization in the headers.

Authorizations:
bearerAuth
query Parameters
backend
string
Enum: "local" "ldap" "saml"
Example: backend=local
Request Body schema: application/json
username
string <= 100 characters

Dashboard Username

Responses

Request samples

Content type
application/json
{
  • "username": "admin"
}

Response samples

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

Listeners

List all running node's listeners for the specifie

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

Authorizations:
basicAuthbearerAuth
query Parameters
type
string
Enum: "tcp" "ssl" "ws" "wss" "quic"
Example: type=tcp

Listener type

Responses

Response samples

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

Create the specified listener on all nodes.

Create the specified listener on all nodes.

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

Listener type

running
boolean

Listener status

name
required
string

Listener name

current_connections
integer >= 0

Current connections

ciphers
Array of strings
Default: ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256","TLS_CHACHA20_POLY1305_SHA256"]

This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" or
["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"].


Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.

The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.


NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.



NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config

If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.

PSK cipher suites: "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA"


NOTE: QUIC listener supports only 'tlsv1.3' ciphers

object (emqx.listener_quic_ssl_opts)
enable
boolean
Default: true

Enable listener.

bind
required
string
Default: 14567

IP address and port for the listening socket.

acceptors
integer >= 1
Default: 16

The size of the listener's receiving pool.

integer or string
Default: "infinity"

The maximum number of concurrent connections allowed by the listener.

mountpoint
string
Default: ""

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_authn
string
Default: true
Enum: true false "quick_deny_anonymous"

Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false, any client (with or without username/password) is allowed to connect.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.

max_conn_rate
string

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.

For example:

- 1000/s :: Only accepts 1000 connections per second

- 1000/10s :: Only accepts 1000 connections every 10 seconds.

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.

For example:

- 500/s :: Only the first 500 messages are sent per second and other messages are buffered.

- 500/10s :: Only the first 500 messages are sent even 10 second and other messages are buffered.

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.

The unit of the bytes could be:KB MB GB.

For example:

- 500KB/s :: Only the first 500 kilobytes are sent per second and other messages are buffered.

- 500MB/10s :: Only the first 500 megabytes are sent even 10 second and other messages are buffered.

Responses

Request samples

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

Response samples

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

Stop the listener on all nodes.

Stop the listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

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

Start the listener on all nodes.

Start the listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

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

Restart listeners on all nodes.

Restart listeners on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

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

List all running node's listeners for the specifie

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

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

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

Update the specified listener on all nodes.

Update the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

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

Listener type

running
boolean

Listener status

id
required
string

Listener id

current_connections
integer >= 0

Current connections

bind
string
Default: 8084

IP address and port for the listening socket.

enable
boolean
Default: true

Enable listener.

acceptors
integer >= 1
Default: 16

The size of the listener's receiving pool.

integer or string
Default: "infinity"

The maximum number of concurrent connections allowed by the listener.

mountpoint
string
Default: ""

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_authn
string
Default: true
Enum: true false "quick_deny_anonymous"

Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false, any client (with or without username/password) is allowed to connect.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.

max_conn_rate
string

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.

For example:

- 1000/s :: Only accepts 1000 connections per second

- 1000/10s :: Only accepts 1000 connections every 10 seconds.

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.

For example:

- 500/s :: Only the first 500 messages are sent per second and other messages are buffered.

- 500/10s :: Only the first 500 messages are sent even 10 second and other messages are buffered.

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.

The unit of the bytes could be:KB MB GB.

For example:

- 500KB/s :: Only the first 500 kilobytes are sent per second and other messages are buffered.

- 500MB/10s :: Only the first 500 megabytes are sent even 10 second and other messages are buffered.

access_rules
Array of strings
Default: ["allow all"]

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

proxy_protocol
boolean
Default: false

Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.

See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

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

object (emqx.tcp_opts)
object (emqx.listener_wss_opts)
object (emqx.ws_opts)

Responses

Request samples

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

Response samples

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

Delete the specified listener on all nodes.

Delete the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

Listener id

Responses

Response samples

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

List all running node's listeners live status. gro

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

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Gateway Authentication

Get authenticator configuration

Gets the configuration of the specified gateway authenticator.

Returns 404 when gateway or authentication is not enabled.

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

Gateway Name

Responses

Response samples

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

Update authenticator configuration

Update the configuration of the specified gateway authenticator, or disable the authenticator.

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

Gateway Name

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

Authentication mechanism.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Delete gateway authenticator

Delete the authenticator of the specified gateway.

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

Gateway Name

Responses

Response samples

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

Create authenticator for gateway

Enables the authenticator for client authentication for the specified gateway.

When the authenticator is not configured or turned off, all client connections are assumed to be allowed.

Note: Only one authenticator is allowed to be enabled at a time in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT.

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

Gateway Name

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

Authentication mechanism.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

Responses

Request samples

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

Response samples

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

Import users

Import users into the gateway authenticator (only supports built_in_database)

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

Gateway Name

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:
basicAuthbearerAuth
path Parameters
name
required
string
Enum: "coap" "exproto" "gbt32960" "jt808" "lwm2m" "mqttsn" "ocpp" "stomp"
Example: stomp

Gateway Name

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

Page number of the results to fetch.

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

Results per page(max 10000)

like_user_id
string
Example: like_user_id=test_

Fuzzy search using user ID (username or clientid), only supports search by substring.

is_superuser
boolean

Is superuser

Responses

Response samples

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

Add user for gateway authenticator

Add user for the authenticator (only supports built_in_database).

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

Gateway Name

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

Responses

Request samples

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

Response samples

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

Get user info for gateway authenticator

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

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

Gateway Name

uid
required
string
Example: test_username

User ID

Responses

Response samples

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

Update user info for gateway authenticator

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

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

Gateway Name

uid
required
string
Example: test_username

User ID

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

Responses

Request samples

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

Response samples

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

Delete user for gateway authenticator

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

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

Gateway Name

uid
required
string
Example: test_username

User ID

Responses

Response samples

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

Import users

Import users into the gateway authenticator (only supports built_in_database)

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

Gateway Name

id
required
string
Example: stomp:tcp:def

Listener ID

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

Responses

Response samples

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

CoAP Gateways

Send a Request to a Client

Send a CoAP request message to the client

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

Message token, can be empty

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

Request method type

timeout
string

Timespan for response

content_type
string
Enum: "text/plain" "application/json" "application/octet-stream"

Payload type

payload
string

The content of the payload

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "method": "get",
  • "timeout": "32s",
  • "content_type": "text/plain",
  • "payload": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "token": "string",
  • "method": "string",
  • "payload": "string"
}

Retainer

List retained messages.

List retained messages.

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

Topic filter, supports wildcards, omit this to match all messages.

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Delete all retained messages

Delete all retained messages

Authorizations:
basicAuthbearerAuth

Responses

Lookup a message by a topic without wildcards.

Lookup a message by a topic without wildcards.

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic.

Responses

Response samples

Content type
application/json
{
  • "payload": "string",
  • "msgid": "string",
  • "topic": "string",
  • "qos": 0,
  • "publish_at": "string",
  • "from_clientid": "string",
  • "from_username": "string"
}

Delete matching messages.

Delete matching messages.

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic.

Responses

Response samples

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

View config

View config

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update retainer config.

Update retainer config.

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

Enable retainer feature

msg_expiry_interval
string
Default: "0s"

Message retention time. This config is only applicable for messages without the Message Expiry Interval message property.
0 means message will never expire.

msg_clear_interval
string
Default: "0s"

Interval for EMQX to scan expired messages and delete them. Never scan 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

delivery_rate
string
Default: "1000/s"

The maximum rate of delivering retained messages

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,
  • "delivery_rate": "1000/s",
  • "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,
  • "delivery_rate": "1000/s",
  • "backend": {
    }
}

Alarms

List currently activated alarms or historical alar

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

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

Page number of the results to fetch.

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

Results per page(max 10000)

activated
boolean

It is used to specify the alarm type of the query.
When true, it returns the currently activated alarm,
and when it is false, it returns the historical alarm.
The default is false.

Responses

Response samples

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

Remove all historical alarms.

Remove all historical alarms.

Authorizations:
basicAuthbearerAuth

Responses

Subscriptions

List subscriptions

List subscriptions

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

Page number of the results to fetch.

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

Results per page(max 10000)

node
string
Example: node=emqx@127.0.0.1

Node name

clientid
string

Client ID

qos
integer [ 0 .. 2 ]
Example: qos=0

QoS

topic
string

Topic, url encoding

match_topic
string

Match topic string, url encoding

share_group
string

Shared subscription group name

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:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false,
  • "threshold": "32s",
  • "expire_interval": "32s",
  • "top_k_num": 10,
  • "stats_type": "whole"
}

Update slow subs settings

Update slow subs settings

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

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

View slow topics statistics record data

View slow topics statistics record data

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Clear current data and re count slow topic

Clear current data and re count slow topic

Authorizations:
basicAuthbearerAuth

Responses

License

Get license setting

Update license setting

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "connection_low_watermark": "75%",
  • "connection_high_watermark": "80%"
}

Update license setting

Update license setting

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
connection_low_watermark
string
Default: "75%"

Low watermark limit below which license connection quota usage alarms are deactivated

connection_high_watermark
string
Default: "80%"

High watermark limit above which license connection quota usage alarms are activated

Responses

Request samples

Content type
application/json
{
  • "connection_low_watermark": "75%",
  • "connection_high_watermark": "80%"
}

Response samples

Content type
application/json
{
  • "connection_low_watermark": "75%",
  • "connection_high_watermark": "80%"
}

Get license info

Get license info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "type": "trial",
  • "max_connections": 10,
  • "email": "contact@foo.com",
  • "start_at": "2022-01-11",
  • "expiry": false,
  • "customer": "Foo",
  • "customer_type": 10,
  • "deployment": "bar-deployment",
  • "expiry_at": "2295-10-27"
}

Update license key

Update a license key

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
string or string
Default: "default"

This configuration parameter is designated for the license key and supports below input formats:

- Direct Key: Enter the secret key directly as a string value.
- File Path: Specify the path to a file that contains the secret key. Ensure the path starts with file://.
- "default": Use string value "default" to apply the default trial license.

Note: An invalid license key or an incorrect file path may prevent EMQX from starting successfully.
If a file path is used, EMQX attempts to reload the license key from the file every 2 minutes.
Any failure in reloading the license file will be recorded as an error level log message,
and EMQX continues to apply the license loaded previously.

Responses

Request samples

Content type
application/json
{
  • "key": "xxx"
}

Response samples

Content type
application/json
{
  • "type": "trial",
  • "max_connections": 10,
  • "email": "contact@foo.com",
  • "start_at": "2022-01-11",
  • "expiry": false,
  • "customer": "Foo",
  • "customer_type": 10,
  • "deployment": "bar-deployment",
  • "expiry_at": "2295-10-27"
}

API Keys

Return api_key list. This API can only be requeste

Return api_key list. This API can only be requested using a bearer token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "role": "administrator"
}

Create new api_key. This API can only be requested

Create new api_key. This API can only be requested using a bearer token.

Authorizations:
bearerAuth
Request Body schema: application/json
name
string

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

(integer or string) or string
Default: "infinity"

No longer valid datetime

desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

role
string
Default: "administrator"

Role for this API

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,
  • "role": "administrator"
}

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,
  • "role": "administrator"
}

Return the specific api_key. This API can only be

Return the specific api_key. This API can only be requested using a bearer token.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

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

Responses

Response samples

Content type
application/json
{
  • "name": "EMQX-API-KEY-1",
  • "api_key": "a4697a5c75a769f6",
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "role": "administrator"
}

Update the specific api_key. This API can only be

Update the specific api_key. This API can only be requested using a bearer token.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

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

Request Body schema: application/json
(integer or string) or string
Default: "infinity"

No longer valid datetime

desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

role
string
Default: "administrator"

Role for this API

Responses

Request samples

Content type
application/json
{
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "role": "administrator"
}

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,
  • "role": "administrator"
}

Delete the specific api_key. This API can only be

Delete the specific api_key. This API can only be requested using a bearer token.

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: EMQX-API-KEY-1

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

Responses

Response samples

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

Banned

List all currently banned client IDs, usernames an

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

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Clear all banned data.

Clear all banned data.

Authorizations:
basicAuthbearerAuth

Responses

Add a client ID, username or IP address to the bla

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

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"

Ban method, which can be exact client ID, client ID regular expression, exact username, username regular expression,
IP address or an IP address range.

who
required
string

Ban object, specific client ID, username or IP address.

by
string

Initiator of the ban.

reason
string

Ban reason, record the reason why the current object was banned.

integer or string

The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated.

integer or string

The end time of the ban, the format is rfc3339, the default is the time when the operation was initiated + 1 year.

Responses

Request samples

Content type
application/json
{
  • "as": "username",
  • "who": "Banned name",
  • "by": "mgmt_api",
  • "reason": "Too many requests",
  • "at": "2021-10-25T21:48:47+08:00",
  • "until": "2021-10-25T21:53:47+08:00"
}

Response samples

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

Remove a client ID, username or IP address from th

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

Authorizations:
basicAuthbearerAuth
path Parameters
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"
Example: username

Ban method, which can be exact client ID, client ID regular expression, exact username, username regular expression,
IP address or an IP address range.

who
required
string
Example: Badass

Ban object, specific client ID, username or IP address.

Responses

Response samples

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

Audit

List audit logs

Get audit logs with filtering parameters. This feature enables users to efficiently
access the desired audit trail data and facilitates auditing, compliance,
troubleshooting, and security analysis.

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

Filter logs by the node name where the logs were generated.

from
string
Enum: "dashboard" "rest_api" "cli" "erlang_console"
Example: from=dashboard

Filter logs by source type. Possible values are:

- dashboard: Dashboard request logs.
- rest_api: API KEY request logs.
- cli: The emqx command line logs.
- erlang_console: The emqx remote_console run function logs.

source
string
Example: source=admin

Filter logs by source. Possible values are:

- The login username to filter logs generated from Dashboard for this specific user.
- The API Key to filter logs generated from the REST API for this specific API key.
- An empty string to filter logs generated from CLI or Erlang console.

source_ip
string
Example: source_ip=127.0.0.1

Filter logs by source IP when logs, applicable for logs generated from Dashboard or REST API operations.

operation_id
string
Example: operation_id=/rules/{id}

Filter logs by swagger's operation_id, applicable for logs generated from Dashboard or REST API operations.

operation_type
string
Example: operation_type=rules

Filter logs by operation type.

operation_result
string
Enum: "success" "failure"
Example: operation_result=failure

Filter logs by operation result.

http_status_code
integer
Example: http_status_code=200

Filter The HTTP API logs by response code, applicable for logs generated from Dashboard or REST API operations.

http_method
string
Enum: "post" "put" "delete"
Example: http_method=post

Filter The HTTP API logs by method, applicable for logs generated from Dashboard or REST API operations.

gte_duration_ms
integer

Filter logs by age duration, selecting those created no earlier than then given duration time ago.

lte_duration_ms
integer
Example: lte_duration_ms=1000

Filter logs by age duration, selecting those created no later than then given duration time ago.

integer or string
Example: gte_created_at=2023-10-15T00:00:00.820384+08:00

Filter logs by creation time, selecting logs created no earlier than the given timestamp.
The timestamp can be provided either in rfc3339 string format or as a millisecond epoch timestamp.

integer or string
Example: lte_created_at=2023-10-16T00:00:00.820384+08:00

Filter logs by creation time, selecting logs created no later than the given timestamp.
The timestamp can be provided either in rfc3339 string format or as a millisecond epoch timestamp.

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

Page number of the results to fetch.

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

Results per page(max 10000)

Responses

Response samples

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

Node Eviction

Get node eviction status

Get the node eviction status

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "status": "disabled"
}