< EMQX Enterprise v5.9 API Documentation APIの問題を報告
API docs by Redocly

EMQX Enterprise API (5.9.1)

Download OpenAPI specification:

Gateway Clients

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

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

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
nl
integer

No Local option, enum: 0, 1

qos
integer

QoS level, enum: 0, 1, 2

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

Topic Filter/Name

Responses

Request samples

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

Response samples

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

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

Responses

Response samples

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

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

Cluster

Get a cluster link metrics

Get a cluster link metrics

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_link

Responses

Response samples

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

Get cluster info

Get cluster info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Get cluster links configuration

Get cluster links configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Create a cluster link

Create a cluster link

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

Optional Base MQTT client ID for connecting to the remote EMQX cluster. If omitted, local cluster.name is used. EMQX maintains several connections between linked clusters, so distinct suffixes are automatically appended to the base client ID.

enable
boolean
Default: true

Enable or disable a cluster link. The link is enabled by default, disabling it allows stopping the link without removing its configuration. The link must be enabled on both sides to be operational. Disabling the link should also be done on both clusters in order to free up all associated resources.

max_inflight
integer >= 0
Default: 32

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

name
required
string

Linked (remote) cluster name. Must be exactly equal to the value of cluster.name configured at the remote cluster. Must not be equal to the local cluster.name. All configured cluster link names must be unique.

password
string <password>

Optional MQTT username for connecting to the remote EMQX cluster.

pool_size
integer >= 1
Default: 8

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

object (cluster.creation_opts)
retry_interval
string
Default: "15s"

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

or combination of whereof: 1h5m0s

server
required
string

MQTT host and port of the remote EMQX broker.

object (emqx.ssl_client_opts)
topics
required
Array of strings

MQTT topics to be forwarded by the linked remote EMQX broker to the local broker. Messages are only forwarded if the local EMQX broker has matching subscriber(s).
Wildcards are supported. Setting empty topics list on one side of the link can be used to establish unidirectional links: the side with the empty topics won't receive remote messages, but it can forward relevant messages to its linked counterpart (according to the topics configured on that side of the link).

username
string

Optional MQTT username for connecting to the remote EMQX cluster.

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "name": "emqxcl_b",
  • "pool_size": 10,
  • "server": "emqxcl_b.host:1883",
  • "ssl": {
    },
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "name": "emqxcl_b",
  • "node_status": [
    ],
  • "pool_size": 10,
  • "server": "emqxcl_b.host:1883",
  • "ssl": {
    },
  • "status": "connected",
  • "topics": [
    ]
}

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

Responses

Response samples

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

Force leave node from cluster

Force leave node from cluster

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

Responses

Response samples

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

Invite node to cluster

Invite node to cluster

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string
Example: emqx2@127.0.0.1
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"
}

Delete a cluster link

Delete a cluster link

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_link

Responses

Response samples

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

Get a cluster link configuration

Get a cluster link configuration

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_link

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "name": "emqxcl_b",
  • "node_status": [
    ],
  • "pool_size": 10,
  • "server": "emqxcl_b.host:1883",
  • "ssl": {
    },
  • "status": "connected",
  • "topics": [
    ]
}

Update a cluster link configuration

Update a cluster link configuration

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_link
Request Body schema: application/json
clientid
string

Optional Base MQTT client ID for connecting to the remote EMQX cluster. If omitted, local cluster.name is used. EMQX maintains several connections between linked clusters, so distinct suffixes are automatically appended to the base client ID.

enable
boolean
Default: true

Enable or disable a cluster link. The link is enabled by default, disabling it allows stopping the link without removing its configuration. The link must be enabled on both sides to be operational. Disabling the link should also be done on both clusters in order to free up all associated resources.

max_inflight
integer >= 0
Default: 32

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

password
string <password>

Optional MQTT username for connecting to the remote EMQX cluster.

pool_size
integer >= 1
Default: 8

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

object (cluster.creation_opts)
retry_interval
string
Default: "15s"

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

or combination of whereof: 1h5m0s

server
required
string

MQTT host and port of the remote EMQX broker.

object (emqx.ssl_client_opts)
topics
required
Array of strings

MQTT topics to be forwarded by the linked remote EMQX broker to the local broker. Messages are only forwarded if the local EMQX broker has matching subscriber(s).
Wildcards are supported. Setting empty topics list on one side of the link can be used to establish unidirectional links: the side with the empty topics won't receive remote messages, but it can forward relevant messages to its linked counterpart (according to the topics configured on that side of the link).

username
string

Optional MQTT username for connecting to the remote EMQX cluster.

Responses

Request samples

Content type
application/json
{
  • "clientid": "string",
  • "enable": true,
  • "max_inflight": 32,
  • "password": "R4ND0M/S∃CЯ∃T",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "retry_interval": "15s",
  • "server": "string",
  • "ssl": {
    },
  • "topics": [
    ],
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "enable": true,
  • "name": "emqxcl_b",
  • "node_status": [
    ],
  • "pool_size": 10,
  • "server": "emqxcl_b.host:1883",
  • "ssl": {
    },
  • "status": "connected",
  • "topics": [
    ]
}

Reset a cluster link's metrics

Reset a cluster link's metrics

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_link

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "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
{
  • "failed": [
    ],
  • "in_progress": [
    ],
  • "succeed": [
    ]
}

Dashboard

Delete MFA state for a dashboard user.<br/>After t

Delete MFA state for a dashboard user.
After the state is deleted, the user will have MFA explicitly disabled, to re-enabled MFA, call the POST method.

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Responses

Response samples

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

Setup MFA for a dashboard user.

Setup MFA for a dashboard user.

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Request Body schema: application/json
mechanism
required
string
Value: "totp"

Multifactor authentication mechanism.

Responses

Request samples

Content type
application/json
{
  • "mechanism": "totp"
}

Response samples

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

Dashboard authentication

Get Dashboard Auth Token.

Request Body schema: application/json
mfa_token
string <= 9 characters

Multifactor authentication token.

password
string <= 100 characters

Dashboard Password

username
string <= 100 characters

Dashboard Username

Responses

Request samples

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

Response samples

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

Change dashboard user password

Change dashboard user password

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

Request Body schema: application/json
new_pwd
string

New password

old_pwd
string

Old password

Responses

Request samples

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

Response samples

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

Delete dashboard user

Delete dashboard user

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: admin

Dashboard Username

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

Responses

Response samples

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

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" "oidc" "saml"
Example: backend=local
Request Body schema: application/json
description
string

Dashboard User Description

role
string
Default: "administrator"

User role

Responses

Request samples

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

Response samples

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

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

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 list users

Dashboard list users

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create dashboard user

Create dashboard user

Authorizations:
bearerAuth
Request Body schema: application/json
description
string

Dashboard User Description

password
string <= 100 characters

Dashboard Password

role
string
Default: "administrator"

User role

username
string <= 100 characters

Dashboard Username

Responses

Request samples

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

Response samples

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

Configs

Get the MQTT-related configuration

Get the MQTT-related configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update MQTT-related configuration

Update MQTT-related configuration

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

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *sys_topics*

Get the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *sys_topics*

Update the sub-configurations under sys_topics

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx.event_names)
string or string
Default: "30s"

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

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>

Responses

Request samples

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

Response samples

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

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" "authentication_settings" "authorization" "auto_subscribe" "banned" "bridges" "cluster" "config_backup_interval" "conn_congestion" "connectors" "crl_cache" "dashboard" "delayed" "durable_queues" "durable_sessions" "durable_storage" "exhook" "file_transfer" "flapping_detect" "force_gc" "force_shutdown" "gateway" "license" "listeners" "log" "message_transformation" "mqtt" "multi_tenancy" "node" "opentelemetry" "overload_protection" "prometheus" "psk_authentication" "retainer" "rewrite" "rpc" "rule_engine" "schema_registry" "schema_validation" "slow_subs" "sources" "sys_topics" "sysmon" "telemetry" "topic_metrics"
Example: key=sysmon
node
string

Node's name. Will deprecated in 5.2.0.

Responses

Response samples

Content type
{
  • "deprecated": true
}

Update the configurations of the specified keys.

Update the configurations of the specified keys.

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

Responses

Response samples

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

Get the sub-configurations under *log*

Get the sub-configurations under log

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *log*

Update the sub-configurations under log

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

File-based log handlers.

object (emqx.log_throttling)

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *sysmon*

Get the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *sysmon*

Update the sub-configurations under sysmon

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
broker_pool_mailbox_size_alarm_threshold
integer >= 1
Default: 500

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

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

mnesia_tm_mailbox_size_alarm_threshold
integer >= 1
Default: 500

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

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

object (emqx.sysmon_os)
object (emqx.sysmon_vm)

Responses

Request samples

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

Response samples

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

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

Get the sub-configurations under *alarm*

Get the sub-configurations under alarm

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *alarm*

Update the sub-configurations under alarm

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

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

size_limit
integer [ 1 .. 3000 ]
Default: 1000

The maximum number of historical alarms that can be stored.

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

validity_period
string
Default: "24h"

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

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

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *file_transfer*

Get the sub-configurations under file_transfer

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update the sub-configurations under *file_transfer*

Update the sub-configurations under file_transfer

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
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)

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).

object (file_transfer.storage_backend)
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).

Responses

Request samples

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

Response samples

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

Get the sub-configurations under *dashboard*

Get the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "cors": false,
  • "default_mfa": "none",
  • "default_password": "R4ND0M/S∃CЯ∃T",
  • "hwmark_expire_time": "12m",
  • "listeners": {
    },
  • "password_expired_time": "1h",
  • "sso": {
    },
  • "swagger_support": true,
  • "token_expired_time": "12m"
}

Update the sub-configurations under *dashboard*

Update the sub-configurations under dashboard

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
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.

dashboard.mfa_settings (object) or string
Default: "none"

Default Multifactor authentication settings for Dashboard.
When set as none, MFA can be enabled per user from the dashboard.
If set as {mechanism = totp}, the user will be initialized with
a random TOTP secret when logging in for the first time.

hwmark_expire_time
string
Default: "7d"

Specifies the expiration interval for high watermark metrics, such as the session history high watermark (sessions_hist_hwmark).
A high watermark remains valid for the configured duration.
When it expires, the system scans the recorded values up to now and updates the high watermark to the highest observed value.
Note: it must be no more than 7 days (7d)

object (dashboard.listeners)
password_expired_time
string
Default: 0

The expiration time for the password of users. The default value 0 means the password will never expire.

object (dashboard.sso)
swagger_support
boolean
Default: true

Enable or disable support for swagger API documentation.

token_expired_time
string
Default: "60m"

JWT token expiration time. Default is 60 minutes

Responses

Request samples

Content type
application/json
{
  • "cors": false,
  • "default_mfa": "none",
  • "hwmark_expire_time": "12m",
  • "listeners": {
    },
  • "password_expired_time": "1h",
  • "sso": {
    },
  • "swagger_support": true,
  • "token_expired_time": "12m"
}

Response samples

Content type
application/json
{
  • "cors": false,
  • "default_mfa": "none",
  • "default_password": "R4ND0M/S∃CЯ∃T",
  • "hwmark_expire_time": "12m",
  • "listeners": {
    },
  • "password_expired_time": "1h",
  • "sso": {
    },
  • "swagger_support": true,
  • "token_expired_time": "12m"
}

Banned

Clear all banned data.

Clear all banned data.

Authorizations:
basicAuthbearerAuth

Responses

List all currently banned client IDs, usernames an

List all currently banned client IDs, usernames and IP addresses.
Filters are supported. Since filters are mutually exclusive, only one filter is allowed in a query.

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

Page number of the results to fetch.

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

Results per page

clientid
string

Query the banning rules with an exact client ID.

username
string

Query the banning rules with an exact username.

peerhost
string
Example: peerhost=127.0.0.1

Query the banning rules with an exact IP address.

like_clientid
string

Fuzzy query banning rules with a regular expression for client ID.

like_username
string

Fuzzy query banning rules with a regular expression for username.

like_peerhost
string
Example: like_peerhost=127.0.0.1

Fuzzy query banning rules with a regular expression for IP address.

like_peerhost_net
string
Example: like_peerhost_net=192.1.0.0/16

Fuzzy query banning rules with a regular expression for CIDR.

Responses

Response samples

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

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.

integer or string

The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated.

by
string

Initiator of the ban.

reason
string

Ban reason, record the reason why the current object was banned.

(integer or string) or string
Default: "infinity"

The end time of the ban, the format is rfc3339, the default is the time when the operation was initiated + 1 year.

who
required
string

Ban object, specific client ID, username or IP address.

Responses

Request samples

Content type
application/json
{
  • "as": "username",
  • "at": "2021-10-25T21:48:47+08:00",
  • "by": "mgmt_api",
  • "reason": "Too many requests",
  • "until": "2030-11-11T10:24:00+08:00",
  • "who": "Banned name"
}

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

Relup

Upgrade all nodes

Upgrade all nodes to the target version with the installed package.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Upgrade a specified node

Upgrade a specified node to the target version with the installed package.

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

The node to be upgraded

Responses

Response samples

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

Get the hot upgrade status of all nodes

Get the hot upgrade status of all nodes

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the hot upgrade status of a specified node

Get the hot upgrade status of a specified node

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

The node to be upgraded

Responses

Response samples

Content type
application/json
{
  • "current_vsn": "5.8.0",
  • "live_connections": 100,
  • "node": "emqx@127.0.0.1",
  • "role": "core",
  • "status": "in-progress",
  • "upgrade_history": [
    ]
}

Upload a hot upgrade package

Upload a hot upgrade package (emqx_relup-vsn.tar.gz).
Note that only one package is alllowed to be installed at a time.

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

Responses

Response samples

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

Delete the installed hot upgrade package

Delete the installed hot upgrade package.

Authorizations:
basicAuthbearerAuth

Responses

Get the installed hot upgrade package

Get information of the installed hot upgrade package.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "applicable_vsns": [
    ],
  • "build_date": "2021-12-25",
  • "built_on_otp_release": "24",
  • "change_logs": [
    ],
  • "md5_sum": "d41d8cd98f00b204e9800998ecf8427e",
  • "name": "emqx_relup-5.8.2.tar.gz",
  • "target_vsn": "5.8.2"
}

Clients

Unsubscribe bulk

Unsubscribe bulk

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

Topic name

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Subscribe

Subscribe

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
nl
integer
Default: 0

No local

qos
integer [ 0 .. 2 ]
Default: 0

QoS

rap
integer
Default: 0

Retain as published

rh
integer
Default: 0

Retain handling

topic
required
string

Topic name

Responses

Request samples

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

Response samples

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

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

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

List clients

List clients

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

Page number of the results to fetch.

node
string
Example: node=emqx@127.0.0.1

Node name

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

Results per page

username
Array of strings

User name of client when connecting

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

Indicate whether the client is using a brand new session

proto_ver
string

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(epoch millisecond)

clientid
Array of strings

Client ID

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

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 subscriptions

Get client subscriptions

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Unsubscribe

Unsubscribe

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

Topic name

Responses

Request samples

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

Response samples

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

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.

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

Responses

Response samples

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

Subscribe bulk

Subscribe bulk

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
nl
integer
Default: 0

No local

qos
integer [ 0 .. 2 ]
Default: 0

QoS

rap
integer
Default: 0

Retain as published

rh
integer
Default: 0

Retain handling

topic
required
string

Topic name

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

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 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.

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

Responses

Response samples

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

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 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": "string",
  • "result": "allow",
  • "topic": "string",
  • "updated_time": 1687850712989
}

Gateways

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
{
  • "connection_required": false,
  • "enable": true,
  • "enable_stats": true,
  • "heartbeat": "30s",
  • "idle_timeout": "30s",
  • "listeners": [
    ],
  • "mountpoint": "coap/",
  • "name": "coap",
  • "notify_type": "qos",
  • "publish_qos": "coap",
  • "subscribe_qos": "coap"
}

Load or update the gateway confs

Update the gateway basic configurations and running status.

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

Authorizations:
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.clientinfo_override)
enable
boolean
Default: true

Whether to enable this gateway

enable_stats
boolean
Default: true

Whether to enable client process statistic

object (gateway.stomp_frame)
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.

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

Responses

Request samples

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

Response samples

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

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
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Connectors

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

Test creating connector

Test creating a new connector.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

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).

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

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.

name
required
string

The name of the connector.

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

Tags to annotate this config entry.

type
required
string
Value: "kafka_consumer"

The type of the connector.

Responses

Request samples

Content type
application/json
Example
{
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "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"
}

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

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
{
  • "actions": [
    ],
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "node_status": [
    ],
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

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).

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

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.

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

Tags to annotate this config entry.

Responses

Request samples

Content type
application/json
Example
{
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
Example
{
  • "actions": [
    ],
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "node_status": [
    ],
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

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).

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

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.

name
required
string

The name of the connector.

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

Tags to annotate this config entry.

type
required
string
Value: "kafka_consumer"

The type of the connector.

Responses

Request samples

Content type
application/json
Example
{
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
Example
{
  • "actions": [
    ],
  • "authentication": {
    },
  • "connect_timeout": "15s",
  • "description": "My example elasticsearch connector",
  • "enable": true,
  • "enable_pipelining": 100,
  • "name": "elasticsearch_connector",
  • "node_status": [
    ],
  • "pool_size": 8,
  • "pool_type": "random",
  • "server": "127.0.0.1:9200",
  • "ssl": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

ExHook

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

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
{
  • "auto_reconnect": "60s",
  • "enable": true,
  • "failed_action": "deny",
  • "hooks": [
    ],
  • "metrics": {
    },
  • "name": "default",
  • "node_metrics": [
    ],
  • "node_status": [
    ],
  • "pool_size": 8,
  • "request_timeout": "12m",
  • "socket_options": {
    },
  • "ssl": {
    },
  • "url": "http://127.0.0.1:9000"
}

Update the server

Update the server

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: default

The Exhook server name

Request Body schema: application/json
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.

enable
boolean
Default: true

Enable this Exhook 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

name
required
string

Name of the exhook server

pool_size
integer >= 1
Default: 8

The process pool size for gRPC client

request_timeout
string
Default: "5s"

The timeout of request gRPC server

object (exhook.socket_options)
object (exhook.ssl_conf)
url
required
string

URL of the gRPC server

Responses

Request samples

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

Response samples

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

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

Response samples

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

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

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
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.

enable
boolean
Default: true

Enable this Exhook 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

name
required
string

Name of the exhook server

pool_size
integer >= 1
Default: 8

The process pool size for gRPC client

request_timeout
string
Default: "5s"

The timeout of request gRPC server

object (exhook.socket_options)
object (exhook.ssl_conf)
url
required
string

URL of the gRPC server

Responses

Request samples

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

Response samples

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

Rules

List rules

List all rules

Authorizations:
basicAuthbearerAuth
query Parameters
enable
boolean

Filter enable/disable rules

from
string

Filter rules by from(topic), exact match

like_id
string

Filter rules by id, Substring matching

like_from
string

Filter rules by from(topic), Substring matching

like_description
string

Filter rules by description, Substring matching

match_from
string

Filter rules by from(topic), Mqtt topic matching

action
Array of strings

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

source
Array of strings

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

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

Page number of the results to fetch.

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

Results per page

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
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.

description
string
Default: ""

The description of the rule

enable
boolean
Default: true

Enable or disable the rule

metadata
object

Rule metadata, do not change manually

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

Responses

Request samples

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

Response samples

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

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

Get a rule by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

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

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
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.

description
string
Default: ""

The description of the rule

enable
boolean
Default: true

Enable or disable the rule

metadata
object

Rule metadata, do not change manually

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

Responses

Request samples

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

Response samples

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

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

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

List rule events

List all events can be used in rules

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Apply a rule for testing

Apply a rule with the given message and environment

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

The context of the event for testing

stop_action_after_template_rendering
boolean
Default: true

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

Responses

Request samples

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

Response samples

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

Test a rule

Test a rule

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

The context of the event for testing

sql
required
string

The SQL of the rule for testing

Responses

Request samples

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

Response samples

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

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

LwM2M Gateways

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
{
  • "action": "discover",
  • "clientid": "urn:oma:lwm2m:oma:2",
  • "codeMsg": "reply_not_received",
  • "content": [
    ],
  • "path": "/3/0/7"
}

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

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

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

Data Backup

Export a data backup file

Export a data backup file

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

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

table_sets
Array of strings

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

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

Responses

Request samples

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

Response samples

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

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

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"

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

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

Import a data backup file

Import a data backup file

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

Data backup file name

node
string

Node name

Responses

Request samples

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

Response samples

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

Authorization

Delete rules for 'all'

Delete rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Show the list of rules for 'all'

Show the list of rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

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

Get authorization settings

Get authorization settings

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update authorization settings

Update authorization settings

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (emqx.authz_cache)
deny_action
required
string
Default: "ignore"
Enum: "ignore" "disconnect"

The action when the authorization check rejects an operation.

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.

Responses

Request samples

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

Response samples

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

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

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
clientid
required
string

ClientID

Array of objects (emqx_authz_api_mnesia.rule_item)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

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

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

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

Response samples

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

Get metrics of node-wise authorization cache.

Get metrics of node-wise authorization cache.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

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

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
all_attribute
string
Default: "mqttPubSubTopic"

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

base_dn
required
string

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

enable
boolean
Default: true

Set to true or false to disable this ACL provider

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.

password
string <password>

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

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

publish_attribute
string
Default: "mqttPublishTopic"

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

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

request_timeout
string
Default: "10s"

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

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.

object (ldap.ssl)
subscribe_attribute
string
Default: "mqttSubscriptionTopic"

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

type
required
string
Value: "ldap"

Backend type.

username
required
string

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

Responses

Request samples

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

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

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
{
  • "metrics": {
    },
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ],
  • "node_status": [
    ],
  • "resource_metrics": {
    },
  • "status": "connected"
}

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

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

Reset node-wise authorization cache.

Reset node-wise authorization cache.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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
all_attribute
string
Default: "mqttPubSubTopic"

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

base_dn
required
string

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

enable
boolean
Default: true

Set to true or false to disable this ACL provider

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.

password
string <password>

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

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

publish_attribute
string
Default: "mqttPublishTopic"

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

query_timeout
string
Default: "5s"

Timeout for the LDAP query.

request_timeout
string
Default: "10s"

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

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.

object (ldap.ssl)
subscribe_attribute
string
Default: "mqttSubscriptionTopic"

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

type
required
string
Value: "ldap"

Backend type.

username
required
string

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

Responses

Request samples

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

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 settings of node-wise authorization cache.

Get settings of node-wise authorization cache.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "cache_ttl": "1m",
  • "cleanup_interval": "1m",
  • "enable": true,
  • "max_count": 100000,
  • "max_memory": "100MB",
  • "stat_update_interval": "1m"
}

Update settings of node-wise authorization cache.

Update settings of node-wise authorization cache.

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

Time after which the cached authentication/authorization result will expire.

enable
boolean
Default: false

Enable or disable the cache.

integer or string
Default: 1000000

Maximum number of cached results.

string or string
Default: "100MB"

Maximum memory usage of the cache.

Responses

Request samples

Content type
application/json
{
  • "cache_ttl": "1m",
  • "cleanup_interval": "1m",
  • "enable": true,
  • "max_count": 100000,
  • "max_memory": "100MB",
  • "stat_update_interval": "1m"
}

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 rule for 'clientid'

Get rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

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

Set rule for 'clientid'

Set rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Request Body schema: application/json
clientid
required
string

ClientID

Array of objects (emqx_authz_api_mnesia.rule_item)

Responses

Request samples

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

Response samples

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

Bridges

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
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

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).

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

health_check_topic
string

Topic name used exclusively for more accurate connector health checks.

object (bridge_kafka.consumer_kafka_opts)
key_encoding_mode
string
Default: "none"
Enum: "none" "base64"

Defines how the key from the Kafka message is encoded before being forwarded via MQTT.
none Uses the key from the Kafka message unchanged. Note: in this case, the key must be a valid UTF-8 string.
base64 Uses base-64 encoding on the received key.

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

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.

name
required
string

Action name, used as a human-readable identifier.

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

Tags to annotate this config entry.

required
Array of objects (bridge_kafka.consumer_topic_mapping)

Defines the mapping between Kafka topics and MQTT topics. Must contain at least one item.

type
required
string
Enum: "kafka" "kafka_producer" "kafka_consumer"

The Action Type

value_encoding_mode
string
Default: "none"
Enum: "none" "base64"

Defines how the value from the Kafka message is encoded before being forwarded via MQTT.
none Uses the value from the Kafka message unchanged. Note: in this case, the value must be a valid UTF-8 string.
base64 Uses base-64 encoding on the received value.

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "local_topic": "local/topic/#",
  • "name": "foo",
  • "password": "******",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "server": "127.0.0.1:1521",
  • "service_name": "ORCL",
  • "sid": "ORCL",
  • "sql": "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})",
  • "type": "oracle",
  • "username": "root"
}

Response samples

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

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

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
{
  • "enable": true,
  • "local_topic": "local/topic/#",
  • "name": "foo",
  • "password": "******",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "server": "127.0.0.1:1521",
  • "service_name": "ORCL",
  • "sid": "ORCL",
  • "sql": "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})",
  • "type": "oracle",
  • "username": "root"
}

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
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

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).

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

health_check_topic
string

Topic name used exclusively for more accurate connector health checks.

object (bridge_kafka.consumer_kafka_opts)
key_encoding_mode
string
Default: "none"
Enum: "none" "base64"

Defines how the key from the Kafka message is encoded before being forwarded via MQTT.
none Uses the key from the Kafka message unchanged. Note: in this case, the key must be a valid UTF-8 string.
base64 Uses base-64 encoding on the received key.

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

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.

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

Tags to annotate this config entry.

required
Array of objects (bridge_kafka.consumer_topic_mapping)

Defines the mapping between Kafka topics and MQTT topics. Must contain at least one item.

value_encoding_mode
string
Default: "none"
Enum: "none" "base64"

Defines how the value from the Kafka message is encoded before being forwarded via MQTT.
none Uses the value from the Kafka message unchanged. Note: in this case, the value must be a valid UTF-8 string.
base64 Uses base-64 encoding on the received value.

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "local_topic": "local/topic/#",
  • "name": "foo",
  • "password": "******",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "server": "127.0.0.1:1521",
  • "service_name": "ORCL",
  • "sid": "ORCL",
  • "sql": "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})",
  • "type": "oracle",
  • "username": "root"
}

Response samples

Content type
application/json
Example
{
  • "enable": true,
  • "local_topic": "local/topic/#",
  • "name": "foo",
  • "password": "******",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "server": "127.0.0.1:1521",
  • "service_name": "ORCL",
  • "sid": "ORCL",
  • "sql": "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})",
  • "type": "oracle",
  • "username": "root"
}

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

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
bridge_kafka.auth_gssapi_kerberos (object) or bridge_kafka.auth_username_password (object) or string
Default: "none"

Authentication configs.

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).

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

health_check_topic
string

Topic name used exclusively for more accurate connector health checks.

object (bridge_kafka.consumer_kafka_opts)
key_encoding_mode
string
Default: "none"
Enum: "none" "base64"

Defines how the key from the Kafka message is encoded before being forwarded via MQTT.
none Uses the key from the Kafka message unchanged. Note: in this case, the key must be a valid UTF-8 string.
base64 Uses base-64 encoding on the received key.

metadata_request_timeout
string
Default: "5s"

Maximum wait time when fetching topic metadata.

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.

name
required
string

Action name, used as a human-readable identifier.

object (bridge_kafka.connector_resource_opts)
object (bridge_kafka.socket_opts)
object (bridge_kafka.ssl_client_opts)
tags
Array of strings

Tags to annotate this config entry.

required
Array of objects (bridge_kafka.consumer_topic_mapping)

Defines the mapping between Kafka topics and MQTT topics. Must contain at least one item.

type
required
string
Enum: "kafka" "kafka_producer" "kafka_consumer"

The Action Type

value_encoding_mode
string
Default: "none"
Enum: "none" "base64"

Defines how the value from the Kafka message is encoded before being forwarded via MQTT.
none Uses the value from the Kafka message unchanged. Note: in this case, the value must be a valid UTF-8 string.
base64 Uses base-64 encoding on the received value.

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "local_topic": "local/topic/#",
  • "name": "foo",
  • "password": "******",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "server": "127.0.0.1:1521",
  • "service_name": "ORCL",
  • "sid": "ORCL",
  • "sql": "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})",
  • "type": "oracle",
  • "username": "root"
}

Response samples

Content type
application/json
Example
{
  • "enable": true,
  • "local_topic": "local/topic/#",
  • "name": "foo",
  • "password": "******",
  • "pool_size": 8,
  • "resource_opts": {
    },
  • "server": "127.0.0.1:1521",
  • "service_name": "ORCL",
  • "sid": "ORCL",
  • "sql": "insert into t_mqtt_msgs(msgid, topic, qos, payload) values (${id}, ${topic}, ${qos}, ${payload})",
  • "type": "oracle",
  • "username": "root"
}

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

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

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

Actions

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
connector
required
string

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

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

Array of actions_and_sources.fallback_action_republish (object) or actions_and_sources.fallback_action_reference (object)
Default: []

List of fallback actions that will be triggered if a query to this action fails.

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.

name
required
string
required
object (action_disk_log.action_parameters)
object (actions_and_sources.action_resource_opts)
tags
Array of strings

Tags to annotate this config entry.

type
required
string
Value: "disk_log"

Responses

Request samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "type": "elasticsearch"
}

Response samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

Summarize actions

Summarize actions.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available action types

Lists the available action types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

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

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

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

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
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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
connector
required
string

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

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

Array of actions_and_sources.fallback_action_republish (object) or actions_and_sources.fallback_action_reference (object)
Default: []

List of fallback actions that will be triggered if a query to this action fails.

local_topic
string

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

required
object (action_disk_log.action_parameters)
object (actions_and_sources.action_resource_opts)
tags
Array of strings

Tags to annotate this config entry.

Responses

Request samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "parameters": {
    },
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected",
  • "type": "elasticsearch"
}

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

Test creating bridge

Test creating a new bridge.

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

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

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

Array of actions_and_sources.fallback_action_republish (object) or actions_and_sources.fallback_action_reference (object)
Default: []

List of fallback actions that will be triggered if a query to this action fails.

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.

name
required
string
required
object (action_disk_log.action_parameters)
object (actions_and_sources.action_resource_opts)
tags
Array of strings

Tags to annotate this config entry.

type
required
string
Value: "disk_log"

Responses

Request samples

Content type
application/json
Example
{
  • "connector": "elasticsearch_connector",
  • "description": "My example elasticsearch action",
  • "enable": true,
  • "name": "elasticsearch_action",
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "type": "elasticsearch"
}

Response samples

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

Sources

List available source types

Lists the available source types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

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

Summarize sources

Summarize actions.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

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
connector
required
string

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

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

name
required
string
required
object (bridge_rabbitmq.source_parameters)
object (actions_and_sources.source_resource_opts)
tags
Array of strings

Tags to annotate this config entry.

type
required
string
Value: "rabbitmq"

Responses

Request samples

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

Response samples

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

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

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
{
  • "connector": "my_connector",
  • "description": "my source",
  • "enable": true,
  • "node_status": [
    ],
  • "parameters": {
    },
  • "resource_opts": {
    },
  • "status": "connected"
}

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
connector
required
string

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

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

required
object (bridge_rabbitmq.source_parameters)
object (actions_and_sources.source_resource_opts)
tags
Array of strings

Tags to annotate this config entry.

Responses

Request samples

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

Response samples

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

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

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

Test creating bridge

Test creating a new bridge.

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

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

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true

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

name
required
string
required
object (bridge_rabbitmq.source_parameters)
object (actions_and_sources.source_resource_opts)
tags
Array of strings

Tags to annotate this config entry.

type
required
string
Value: "rabbitmq"

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "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"
}

Durable storage

List sites

List sites

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get durable storage

Get durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Example: messages

Durable storage ID

Responses

Response samples

Content type
application/json
{
  • "name": "messages",
  • "shards": [
    ]
}

Get sites

Get sites

Authorizations:
basicAuthbearerAuth
path Parameters
site
required
string
Example: 23D853AD567F0973

Site ID

Responses

Response samples

Content type
application/json
{
  • "node": "'emqx@example.com'",
  • "shards": [
    ],
  • "up": true
}

Remove site as a replica for the durable storage

Remove site as a replica for the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Example: messages

Durable storage ID

site
required
string
Example: 23D853AD567F0973

Site ID

Responses

Response samples

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

Add site as a replica for the durable storage

Add site as a replica for the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Example: messages

Durable storage ID

site
required
string
Example: 23D853AD567F0973

Site ID

Responses

Response samples

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

List durable storages

List durable storages

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "string"
]

List replicas of the durable storage

List replicas of the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Example: messages

Durable storage ID

Responses

Response samples

Content type
application/json
[
  • "string"
]

Update replicas of the durable storage

Update replicas of the durable storage

Authorizations:
basicAuthbearerAuth
path Parameters
ds
required
string
Example: messages

Durable storage ID

Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • "string"
]

Topics

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

Responses

Response samples

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

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

File Transfer

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

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
{
  • "assemble_timeout": "32s",
  • "enable": false,
  • "init_timeout": "32s",
  • "storage": {
    },
  • "store_segment_timeout": "32s"
}

Update File Transfer configuration

Replace File Transfer configuration.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
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)

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).

object (file_transfer.storage_backend)
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).

Responses

Request samples

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

Response samples

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

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

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

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 authentication cache status.

Get authentication cache status.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Delete authenticator from global authentication ch

Delete authenticator from global authentication chain.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

Authenticator ID.

Responses

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
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "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
required
Array of objects (authn.cinfo_check)

A list of checks to perform on the client information.
If all checks are skipped, the default result ignore is returned.
The ignore result means to defer the authentication to the next authenticator in the chain.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

mechanism
required
string
Value: "cinfo"

Authentication mechanism.

precondition
string
Default: ""

A Variform expression to evaluate with a set of pre-bound variables derived from the client information.

Supported variables:
- username: The username of the client
- password: The password of the client
- clientid: The client ID of the client
- client_attrs.*: The client attributes of the client
- cert_common_name: The subject field from the client's TLS certificate
- cert_subject: The common name (CN) from the client's TLS certificate
- peersni: The SNI (Server Name Indication) sent by TLS client
- listener: The listener ID (e.g. tcp:default)
- zone: The associated config zone.

The expression must evaluate to a string value of 'true' for this authenticator to be invoked.
If the expression evaluates to any other value, this authenticator will be skipped.

Examples:
- Only invoke if the client is connected from listener ssl:letsencryt:
str_eq(listener, 'ssl:letsencryt')
- Skip if username is empty:
not(is_empty_val(username))
- Only invoke if password exists and zone is 'zone1':
iif(is_empty_val(password), false, str_eq(zone, 'zone1'))

Find more information about Variform expressions in EMQX doc.

Responses

Request samples

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

Response samples

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

Reset node-wise authentication cache

Reset node-wise authentication cache

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Get authentication settings.

Get authentication settings.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "node_cache": {
    }
}

Update authentication settings.

Update authentication settings.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
object (auth_cache.config)

Responses

Request samples

Content type
application/json
{
  • "node_cache": {
    }
}

Response samples

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

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

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
is_superuser
boolean
Default: false
password
required
string

Responses

Request samples

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

Response samples

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

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
required
Array of objects (authn.cinfo_check)

A list of checks to perform on the client information.
If all checks are skipped, the default result ignore is returned.
The ignore result means to defer the authentication to the next authenticator in the chain.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

mechanism
required
string
Value: "cinfo"

Authentication mechanism.

precondition
string
Default: ""

A Variform expression to evaluate with a set of pre-bound variables derived from the client information.

Supported variables:
- username: The username of the client
- password: The password of the client
- clientid: The client ID of the client
- client_attrs.*: The client attributes of the client
- cert_common_name: The subject field from the client's TLS certificate
- cert_subject: The common name (CN) from the client's TLS certificate
- peersni: The SNI (Server Name Indication) sent by TLS client
- listener: The listener ID (e.g. tcp:default)
- zone: The associated config zone.

The expression must evaluate to a string value of 'true' for this authenticator to be invoked.
If the expression evaluates to any other value, this authenticator will be skipped.

Examples:
- Only invoke if the client is connected from listener ssl:letsencryt:
str_eq(listener, 'ssl:letsencryt')
- Skip if username is empty:
not(is_empty_val(username))
- Only invoke if password exists and zone is 'zone1':
iif(is_empty_val(password), false, str_eq(zone, 'zone1'))

Find more information about Variform expressions in EMQX doc.

Responses

Request samples

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

Response samples

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

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
{
  • "metrics": {
    },
  • "node_error": [ ],
  • "node_metrics": [
    ],
  • "node_resource_metrics": [
    ],
  • "node_status": [
    ],
  • "resource_metrics": {
    },
  • "status": "connected"
}

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

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
is_superuser
boolean
Default: false
password
required
string
user_id
required
string

Responses

Request samples

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

Response samples

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

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

object

Responses

Request samples

Content type
[
  • {
    },
  • {
    }
]

Response samples

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

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

MQTT

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

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
{
  • "create_time": "2022-01-14T21:48:47+08:00",
  • "metrics": {
    },
  • "reset_time": "2022-01-14T21:48:47+08:00",
  • "topic": "testtopic/1"
}

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

Responses

Response samples

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

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

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
{
  • "delayed_interval": 1,
  • "delayed_remaining": 0,
  • "expected_at": "string",
  • "from_clientid": "string",
  • "from_username": "string",
  • "msgid": 0,
  • "node": "string",
  • "publish_at": "string",
  • "qos": 0,
  • "topic": "/sys/#"
}

List topic metrics

List topic metrics

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Reset telemetry status

Reset telemetry status

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

Action. Only support reset

topic
string

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "TOPIC_NOT_FOUND",
  • "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

dest_topic
required
string

Destination topic.

re
required
string

Regular expressions

source_topic
required
string

Source topic, specified by the client.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

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
}

Monitor

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

Get Prometheus config info

Get Prometheus config info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update Prometheus config

Update Prometheus config

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

Deprecated since 5.4.0, use prometheus.push_gateway.url instead

headers
object
Default: {}

Deprecated since 5.4.0, use prometheus.push_gateway.headers instead

interval
required
string
Default: "15s"

Deprecated since 5.4.0, use prometheus.push_gateway.interval instead

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

Deprecated since 5.4.0, use prometheus.push_gateway.job_name instead

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

Deprecated since 5.4.0, use prometheus.collectors.mnesia instead

push_gateway_server
required
string
Default: "http://127.0.0.1:9091"

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

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

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

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "headers": {
    },
  • "interval": "15s",
  • "job_name": "${name}/instance/${name}~${host}",
  • "mnesia_collector": "disabled",
  • "push_gateway_server": "http://127.0.0.1:9091",
  • "vm_dist_collector": "disabled",
  • "vm_memory_collector": "disabled",
  • "vm_msacc_collector": "disabled",
  • "vm_statistics_collector": "disabled",
  • "vm_system_info_collector": "disabled"
}

Response samples

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

Get Prometheus Metrics for Message Validation

Get Prometheus Metrics for Message Validation

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

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

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

Get Prometheus Metrics for Schema Validation

Get Prometheus Metrics for Schema Validation

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

Get opentelmetry configuration

Get opentelmetry configuration

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Update opentelmetry configuration

Update opentelmetry configuration

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

Responses

Request samples

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

Response samples

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

Message Transformation

Enable or disable transformation

Enable or disable a particular transformation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

Transformation name

enable
required
boolean

Enable or disable transformation

Responses

Response samples

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

Test an input against a configuration

Test an input against a transformation

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
object (message_transformation_http_api.dryrun_input_message)
required
object (message_transformation.transformation)

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "transformation": {
    }
}

Response samples

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

Delete a transformation

Delete a transformation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

Transformation name

Responses

Response samples

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

Lookup a transformation

Lookup a transformation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

Transformation name

Responses

Response samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

List transformations

List transformations

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Append a new transformation

Append a new transformation to the list of transformations

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

Descriptive text.

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"
object (message_transformation.log_failure)
name
required
string
Array of objects (message_transformation.operation)
Default: []
string or string or string or string or string
Default: {"type":"none"}
string or string or string or string or string
Default: {"type":"none"}
tags
Array of strings

Tags to annotate this config entry.

required
Array of strings or string

Responses

Request samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Update a transformation

Update a transformation

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

Descriptive text.

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"
object (message_transformation.log_failure)
name
required
string
Array of objects (message_transformation.operation)
Default: []
string or string or string or string or string
Default: {"type":"none"}
string or string or string or string or string
Default: {"type":"none"}
tags
Array of strings

Tags to annotate this config entry.

required
Array of strings or string

Responses

Request samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "my transformation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_transformation",
  • "operations": [
    ],
  • "payload_decoder": {
    },
  • "payload_encoder": {
    },
  • "tags": [
    ],
  • "topics": [
    ]
}

Get transformation metrics

Get metrics for a particular transformation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

Transformation name

Responses

Response samples

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

Reorder all transformations

Reorder of all transformations

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

Responses

Request samples

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

Response samples

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

Reset transformation metrics

Reset metrics for a particular transformation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_transformation

Transformation name

Responses

Response samples

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

Trace

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
{
  • "clientid": "dev-001",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "formatter": "text",
  • "ip_address": "127.0.0.1",
  • "log_size": [
    ],
  • "name": "EMQX-TRACE-1",
  • "payload_encode": "hex",
  • "payload_limit": 1024,
  • "ruleid": "my_rule",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "status": "running",
  • "topic": "/dev/#",
  • "type": "clientid"
}

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

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

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

Clear all traces

Clear all traces

Authorizations:
basicAuthbearerAuth

Responses

List all trace

List all trace

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new trace

Create new trace

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

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

integer or string

rfc3339 timestamp or epoch second

string or string

The formatter that will be used to format the trace log entries. Set this to text to format the log entries as plain text (default). Set it to json to format each log entry as a JSON object.

ip_address
string

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

name
required
string

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

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

payload_limit
integer
Default: 1024

Determine the maximum bytes of the payload will be printed in the trace file.

The truncated part will be displayed as '...' in the trace file.

It's only effective when payload_encode is hex or text

0: No limit

Default is 1024 bytes

ruleid
string
integer or string

rfc3339 timestamp or epoch second

topic
string

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

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

Filter type

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "clientid": "dev-001",
  • "end_at": "2021-11-05T18:17:38+08:00",
  • "formatter": "text",
  • "ip_address": "127.0.0.1",
  • "log_size": [
    ],
  • "name": "EMQX-TRACE-1",
  • "payload_encode": "hex",
  • "payload_limit": 1024,
  • "ruleid": "my_rule",
  • "start_at": "2021-11-04T18:17:38+08:00",
  • "status": "running",
  • "topic": "/dev/#",
  • "type": "clientid"
}

Load Rebalance

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

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

Get rebalance status

Get rebalance status of the current node

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Start evacuation on a node

Start evacuation process

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

Node name

Request Body schema: application/json
conn_evict_rate
integer >= 1

The rate of evicting connections, in connections per second

migrate_to
Array of strings

Nodes to migrate sessions to

redirect_to
string

Server reference to redirect clients to (MQTTv5 Server redirection)

sess_evict_rate
integer >= 1

The rate of evicting sessions, in sessions per second

wait_health_check
string

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

wait_takeover
string

Time to wait before starting session evacuation process, in seconds

Responses

Request samples

Content type
application/json
null

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
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.

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.

conn_evict_rate
integer >= 1

The rate of evicting connections, in connections per second

conn_evict_rpc_timeout
string
nodes
Array of strings

Nodes to participate in rebalance

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.

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

sess_evict_rate
integer >= 1

The rate of evicting sessions, in sessions per second

sess_evict_rpc_timeout
string
wait_health_check
string

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

wait_takeover
string

Time to wait before starting session evacuation process, in seconds

Responses

Request samples

Content type
application/json
null

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

Stop evacuation on a node

Stop evacuation process

Authorizations:
basicAuthbearerAuth
path Parameters
node
required
string

Node name

Responses

Response samples

Content type
application/json
{ }

Telemetry

Get telemetry data

Get telemetry data

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Get telemetry status

Get telemetry status

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Enable or disable telemetry

Enable or disable telemetry

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

Enable telemetry

Responses

Request samples

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

Response samples

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

Node Eviction

Get node eviction status

Get the node eviction status

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "status": "disabled"
}

Error Codes

API Error Codes

API Error Codes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

API Error Codes

API Error Codes

path Parameters
code
required
string
Enum: "BAD_USERNAME_OR_PWD" "BAD_API_KEY_OR_SECRET" "BAD_REQUEST" "NOT_MATCH" "ALREADY_EXISTS" "BAD_CONFIG_SCHEMA" "BAD_LISTENER_ID" "BAD_NODE_NAME" "BAD_RPC" "BAD_TOPIC" "EXCEED_LIMIT" "INVALID_PARAMETER" "CONFLICT" "NO_DEFAULT_VALUE" "DEPENDENCY_EXISTS" "MESSAGE_ID_SCHEMA_ERROR" "INVALID_ID" "MESSAGE_ID_NOT_FOUND" "NOT_FOUND" "CLIENTID_NOT_FOUND" "CLIENT_NOT_FOUND" "RESOURCE_NOT_FOUND" "TOPIC_NOT_FOUND" "USER_NOT_FOUND" "INTERNAL_ERROR" "SERVICE_UNAVAILABLE" "SOURCE_ERROR" "UPDATE_FAILED" "REST_FAILED" "CLIENT_NOT_RESPONSE" "UNSUPPORTED_MEDIA_TYPE"
Example: BAD_USERNAME_OR_PWD

API Error Codes

Responses

Response samples

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

Multi-tenancy

List Namespaces

List all namespaces
The namespaces are sorted in lexicographical order,
so this API can be used for prefix based fuzzy search.

Authorizations:
basicAuthbearerAuth
query Parameters
last_ns
string
Example: last_ns=ns1

The last namespace from the previous page.
For the first page, use empty string.

limit
integer >= 1
Example: limit=100

The number of items to return

Responses

Response samples

Content type
application/json
[
  • "ns1",
  • "ns2"
]

Count Clients in a Namespace

Count all clients in a namespace

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Upsert namespace configurations in bulk

Upsert namespace configurations in bulk

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
object (mt.config_in)
ns
string

Responses

Request samples

Content type
application/json
null

Response samples

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

Get managed namespace configuration

Get managed namespace configuration

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1

Responses

Response samples

Content type
application/json
null

Update managed namespace configuration

Update managed namespace configuration

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1
Request Body schema: application/json
object (mt.limiter_config_in)
object (mt.session_config_in)

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

List managed namespaces

List all managed namespaces
The namespaces are sorted in lexicographical order,
so this API can be used for prefix based fuzzy search.

Authorizations:
basicAuthbearerAuth
query Parameters
last_ns
string
Example: last_ns=ns1

The last namespace from the previous page.
For the first page, use empty string.

limit
integer >= 1
Example: limit=100

The number of items to return

Responses

Response samples

Content type
application/json
[
  • "ns1",
  • "ns2"
]

Kick all clients in namespace (async)

Kick all clients in namespace (async)

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1

Responses

Response samples

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

Bulk delete namespaces

Bulk delete namespaces

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

Responses

Request samples

Content type
application/json
null

Response samples

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

List Clients in a Namespace

List all clients in a namespace

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1
query Parameters
last_clientid
string
Example: last_clientid=clientid1
limit
integer >= 1
Example: limit=100

The number of items to return

Responses

Response samples

Content type
application/json
[
  • "client1",
  • "client2"
]

Delete namespace

Delete namespace. This will cause all the clients under this namespace to be kicked out asynchronously.

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1

Responses

Create managed namespace

Create managed namespace

Authorizations:
basicAuthbearerAuth
path Parameters
ns
required
string
Example: ns1

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "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

Responses

Response samples

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

Schema Validation

List validations

List validations

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

Append a new validation

Append a new validation to the list of validations

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
Array of schema_validation.check_external_http (object) or schema_validation.check_protobuf (object) or schema_validation.check_avro (object) or schema_validation.check_json (object) or schema_validation.check_sql (object)

Checks that will be performed during validation. They are evaluated in the same order as defined.

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"

How to proceed if the validation fails.

drop: The offending message is simply dropped without further processing.
disconnect: The message is not published, and the publishing client is disconnected.
ignore: Only the failure is logged and traced. No other action is taken.

object (schema_validation.log_failure)
name
required
string

Name

strategy
required
string
Enum: "any_pass" "all_pass"

Strategy

tags
Array of strings

Tags to annotate this config entry.

required
Array of strings or string

A single topic filter or list of topic filters that this validation should validate.

Responses

Request samples

Content type
application/json
Example
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Update a validation

Update a validation

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
Array of schema_validation.check_external_http (object) or schema_validation.check_protobuf (object) or schema_validation.check_avro (object) or schema_validation.check_json (object) or schema_validation.check_sql (object)

Checks that will be performed during validation. They are evaluated in the same order as defined.

description
string
Default: ""

Descriptive text.

enable
boolean
Default: true
failure_action
required
string
Enum: "drop" "disconnect" "ignore"

How to proceed if the validation fails.

drop: The offending message is simply dropped without further processing.
disconnect: The message is not published, and the publishing client is disconnected.
ignore: Only the failure is logged and traced. No other action is taken.

object (schema_validation.log_failure)
name
required
string

Name

strategy
required
string
Enum: "any_pass" "all_pass"

Strategy

tags
Array of strings

Tags to annotate this config entry.

required
Array of strings or string

A single topic filter or list of topic filters that this validation should validate.

Responses

Request samples

Content type
application/json
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Enable or disable validation

Enable or disable a particular validation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

Validation name

enable
required
boolean

Enable or disable validation

Responses

Response samples

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

Get validation metrics

Get metrics for a particular validation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

Validation name

Responses

Response samples

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

Reorder all validations

Reorder of all validations

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

Responses

Request samples

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

Response samples

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

Delete a validation

Delete a validation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

Validation name

Responses

Response samples

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

Lookup a validation

Lookup a validation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

Validation name

Responses

Response samples

Content type
application/json
Example
{
  • "checks": [
    ],
  • "description": "my validation",
  • "enable": true,
  • "failure_action": "drop",
  • "log_failure": {
    },
  • "name": "my_validation",
  • "strategy": "all_pass",
  • "tags": [
    ],
  • "topics": [
    ]
}

Reset validation metrics

Reset metrics for a particular validation

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_validation

Validation name

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "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
content_type
string
Enum: "text/plain" "application/json" "application/octet-stream"

Payload type

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

Request method type

payload
string

The content of the payload

timeout
string

Timespan for response

token
string

Message token, can be empty

Responses

Request samples

Content type
application/json
{
  • "content_type": "text/plain",
  • "method": "get",
  • "payload": "string",
  • "timeout": "32s",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "method": "string",
  • "payload": "string",
  • "token": "string"
}

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

node
string
Example: node=emqx@127.0.0.1

Node name

clientid
string

Client ID

qos
integer [ 0 .. 2 ]
Example: qos=0

QoS

topic
string

Topic, url encoding

match_topic
string

Match topic string, url encoding

share_group
string

Shared subscription group name

durable
boolean

Filter subscriptions by durability

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Slow Subscriptions

Clear current data and re count slow topic

Clear current data and re count slow topic

Authorizations:
basicAuthbearerAuth

Responses

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

Responses

Response samples

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

View slow subs settings

View slow subs settings

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "enable": false,
  • "expire_interval": "32s",
  • "stats_type": "whole",
  • "threshold": "32s",
  • "top_k_num": 10
}

Update slow subs settings

Update slow subs settings

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

Enable Slow Subscriptions

expire_interval
string
Default: "300s"

The expiration time of the slow subscription record, if the record is not updated within the expiration time, then the record will be deleted.

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

Message latency calculation method:

- whole: The time from when the message arrives at the EMQX (the EMQX gets the message from the receive-buffer) until the message completes delivery.
- internal: The time from when the message arrives at the EMQX (the EMQX gets the message from the receive-buffer) to when the message begins to be delivered (the EMQX attempts to write the message to the send-buffer).
- response: The time from the start of message delivery to the completion.

Note: The completion delivery time refers to the time when QoS 1 and 2 messages complete the MQTT message response process, i.e., the time when QoS 1 message receives the PUBACK packet and QoS 2 message receives the PUBCOMP packet.
Since there is no response packet for QoS 0 message, the completion delivery time of the QoS 0 message will be replaced by the time when the message starts to be delivered. Therefore, when using the response method to calculate the latency, the latency of a QoS 0 message will always be equal to 0.

threshold
string
Default: "500ms"

The Client ID and topic of the consumer whose message latency is greater than this threshold will be recorded in the slow subscription list.

top_k_num
integer >= 1
Default: 10

The maximum number of slow-subscription records, up to a maximum of 1000.

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "expire_interval": "32s",
  • "stats_type": "whole",
  • "threshold": "32s",
  • "top_k_num": 10
}

Response samples

Content type
application/json
{
  • "enable": false,
  • "expire_interval": "32s",
  • "stats_type": "whole",
  • "threshold": "32s",
  • "top_k_num": 10
}

Plugins

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

Get installed plugin's AVRO schema

Get plugin's config AVRO schema.

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

^[A-Za-z]+\w-[\w-.]$

Responses

Response samples

Content type
application/json
"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"
}

Sync specific version of plugin to cluster

Forces a plugin to be synced to the cluster and removes other versions of the plugin.

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

Responses

Request samples

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

Response samples

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

Download plugin config

Download plugin config

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

^[A-Za-z]+\w-[\w-.]$

Responses

Response samples

Content type
application/json
"string"

Get plugin config

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

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

^[A-Za-z]+\w-[\w-.]$

Responses

Response samples

Content type
application/json
"string"

Update plugin config

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

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

^[A-Za-z]+\w-[\w-.]$

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

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

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]+\w-[\w-.]$

Responses

Response samples

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

Get a plugin description

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

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

^[A-Za-z]+\w-[\w-.]$

Responses

Response samples

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

Move plugin within plugin hierarchy

Setting the boot order of plugins.

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

^[A-Za-z]+\w-[\w-.]$

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

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]+\w-[\w-.]$

action
required
string
Enum: "start" "stop"

Action

Responses

Response samples

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

Upload plugin config

Upload plugin config

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

^[A-Za-z]+\w-[\w-.]$

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

Responses

Response samples

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

Listeners

Restart listeners on all nodes.

Restart listeners on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

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 type.

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

Type of the listener (tcp, ssl, ws, wss, quic)

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
acceptors
integer >= 1
Default: 16

The size of the listener's receiving pool.

bind
required
string
Default: 14567

IP address and port for the listening socket.

bytes_burst
string

Number of bytes that can be sent in a burst, on top of regular bytes_rate.

For example: 100MB/60m: Once every 60 minutes, up to 100 megabytes can be sent in a short period of time.

bytes_rate
string

Limits the number of bytes a single client can send to the broker, per each node.

Once the limit is reached, EMQX will drop QoS 0 messages and reject QoS 1 and QoS 2 messages
with "Quota Exceeded" error code (0x97).

The unit of the bytes could be: B, KB, MB, GB.

For example:

- 500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be dropped/rejected.
- 500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be dropped/rejected.

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

current_connections
integer >= 0

Current number of connections.

enable
boolean
Default: true

Enable listener.

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_burst
string

Number of connections that can be accepted in a burst, on top of regular rate, per each node.

For example: 10000/60m: Once every 60 minutes, up to 10000 connections can be accepted in a short period of time.

max_conn_rate
string

Limits how quickly this listener accepts connections, per each node.

Once the limit is reached, EMQX will automatically close any new connections right after they’re accepted, effectively draining the queue of connections waiting to be accepted.

For example:

- 1000/s: Only accepts 1000 connections per second.
- 1000/10s: Only accepts 1000 connections every 10 seconds.

integer or string
Default: "infinity"

The maximum number of concurrent connections allowed by the listener.

messages_burst
string

Number of messages that can be sent in a burst, on top of regular messages_rate, per each node.

For example: 10000/60m: Once in 60 minutes, up to 10000 messages can be sent in a short period of time.

messages_rate
string

Limits the number of messages a single client can send to the broker, per each node.

Once the limit is reached, EMQX will drop QoS 0 messages and reject QoS 1 and QoS 2 messages
with "Quota Exceeded" error code (0x97).

For example:

- 500/s: Only 500 messages will be received per second, and the remaining messages will be dropped/rejected.
- 500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be dropped/rejected.

mountpoint
string
Default: ""
  • Adds a static or templated prefix (e.g., n1/ or ${username}/) to topics used by clients in SUBSCRIBE and UNSUBSCRIBE requests, PUBLISH messages, and Will Message (if supplied in the CONNECT packet).
    - Removes this prefix from topics of messages published to the respective subscriptions.

    The supported placeholders are:
    - ${username}
    - ${clientid}
    - ${zone}
    - ${client_attrs.NAME}

    For example, with mountpoint="${username}/" a client using u1 as username will have:
    - Client SUBSCRIBE sensors/# -> u1/sensors/# internally in the broker.
    - Broker PUBLISH u1/sensors/data -> sensors/data sent to the client.

    The prefix mount/unmount is applied to:
    - Will in CONNECT
    - PUBLISH
    - SUBSCRIBE
    - UNSUBSCRIBE

    Note: mounting occurs after authorization/ACL checks.
name
required
string

Name of the listener.

running
boolean

Status of the listener. 'true' for running, otherwise 'false'.

object (emqx.listener_quic_ssl_opts)
type
required
string
Value: "quic"

Type of the listener (tcp, ssl, ws, wss, quic)

zone
string
Default: "default"

The configuration zone to which the listener belongs.
Clients connected to this listener will inherit zone-settings created under this zone name.

A zone can override the configs under below root names:
- mqtt
- force_shutdown
- force_gc
- flapping_detect
- durable_sessions

Responses

Request samples

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

Response samples

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

Stop the listener on all nodes.

Stop the listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "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
[
  • {
    },
  • {
    }
]

Delete the specified listener on all nodes.

Delete the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_LISTENER_ID",
  • "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

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

Responses

Response samples

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

Update the specified listener on all nodes.

Update the specified listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

Request Body schema: application/json
One of
acceptors
integer >= 1
Default: 16

The size of the listener's receiving pool.

access_rules
Array of strings
Default: ["allow all"]

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

For example:

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

bind
string
Default: 8084

IP address and port for the listening socket.

bytes_burst
string

Number of bytes that can be sent in a burst, on top of regular bytes_rate.

For example: 100MB/60m: Once every 60 minutes, up to 100 megabytes can be sent in a short period of time.

bytes_rate
string

Limits the number of bytes a single client can send to the broker, per each node.

Once the limit is reached, EMQX will drop QoS 0 messages and reject QoS 1 and QoS 2 messages
with "Quota Exceeded" error code (0x97).

The unit of the bytes could be: B, KB, MB, GB.

For example:

- 500KB/s: Only 500 kilobytes per second will be received, and the remaining bytes will be dropped/rejected.
- 500MB/10s: Only 500 megabytes will be received every 10 seconds, and the remaining bytes will be dropped/rejected.

current_connections
integer >= 0

Current number of connections.

enable
boolean
Default: true

Enable listener.

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.

id
required
string

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

max_conn_burst
string

Number of connections that can be accepted in a burst, on top of regular rate, per each node.

For example: 10000/60m: Once every 60 minutes, up to 10000 connections can be accepted in a short period of time.

max_conn_rate
string

Limits how quickly this listener accepts connections, per each node.

Once the limit is reached, EMQX will automatically close any new connections right after they’re accepted, effectively draining the queue of connections waiting to be accepted.

For example:

- 1000/s: Only accepts 1000 connections per second.
- 1000/10s: Only accepts 1000 connections every 10 seconds.

integer or string
Default: "infinity"

The maximum number of concurrent connections allowed by the listener.

messages_burst
string

Number of messages that can be sent in a burst, on top of regular messages_rate, per each node.

For example: 10000/60m: Once in 60 minutes, up to 10000 messages can be sent in a short period of time.

messages_rate
string

Limits the number of messages a single client can send to the broker, per each node.

Once the limit is reached, EMQX will drop QoS 0 messages and reject QoS 1 and QoS 2 messages
with "Quota Exceeded" error code (0x97).

For example:

- 500/s: Only 500 messages will be received per second, and the remaining messages will be dropped/rejected.
- 500/10s: Only 500 messages will be received every 10 seconds and the remaining messages will be dropped/rejected.

mountpoint
string
Default: ""
  • Adds a static or templated prefix (e.g., n1/ or ${username}/) to topics used by clients in SUBSCRIBE and UNSUBSCRIBE requests, PUBLISH messages, and Will Message (if supplied in the CONNECT packet).
    - Removes this prefix from topics of messages published to the respective subscriptions.

    The supported placeholders are:
    - ${username}
    - ${clientid}
    - ${zone}
    - ${client_attrs.NAME}

    For example, with mountpoint="${username}/" a client using u1 as username will have:
    - Client SUBSCRIBE sensors/# -> u1/sensors/# internally in the broker.
    - Broker PUBLISH u1/sensors/data -> sensors/data sent to the client.

    The prefix mount/unmount is applied to:
    - Will in CONNECT
    - PUBLISH
    - SUBSCRIBE
    - UNSUBSCRIBE

    Note: mounting occurs after authorization/ACL checks.
proxy_protocol
boolean
Default: false

Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.

See: https://www.haproxy.com/blog/haproxy/proxy-protocol/

proxy_protocol_timeout
string
Default: "3s"

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

EMQX will automatically detect the version of the PROXY protocol and support V1 and V2.

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

running
boolean

Status of the listener. 'true' for running, otherwise 'false'.

object (emqx.listener_wss_opts)
object (emqx.tcp_opts)
type
required
string
Value: "wss"

Type of the listener (tcp, ssl, ws, wss, quic)

object (emqx.ws_opts)
zone
string
Default: "default"

The configuration zone to which the listener belongs.
Clients connected to this listener will inherit zone-settings created under this zone name.

A zone can override the configs under below root names:
- mqtt
- force_shutdown
- force_gc
- flapping_detect
- durable_sessions

Responses

Request samples

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

Response samples

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

Start the listener on all nodes.

Start the listener on all nodes.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: tcp:demo

The identifier of the listener, in the format of {type}:{name}, e.g. 'tcp:default', 'ssl:default', etc.

Responses

Response samples

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

Schema Registry

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

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
{
  • "description": "My Avro Schema",
  • "name": "my_avro_schema",
  • "source": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}",
  • "type": "avro"
}

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
description
string
Default: ""

A description for this schema.

required
object (schema_registry.external_http_params)
type
required
string
Value: "external_http"

Must be external_http for External HTTP.

Responses

Request samples

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

Response samples

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

Delete external registry

Delete external schema registry

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_registry

External registry name

Responses

Lookup external registry

Lookup external schema registry

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_registry

External registry name

Responses

Response samples

Content type
application/json
{}

Update external registry

Update external schema registry

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_registry

External registry name

Request Body schema: application/json
One of
schema_registry.confluent_schema_registry_auth_basic (object) or string
Default: "none"

Authentication options for accessing external registry.

type
string
Default: "confluent"
Value: "confluent"

External Schema Registry Type

url
required
string

URL endpoint for external registry.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

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
description
string
Default: ""

A description for this schema.

name
required
string

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

required
object (schema_registry.external_http_params)
type
required
string
Value: "external_http"

Must be external_http for External HTTP.

Responses

Request samples

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

Response samples

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

List external registries

List external schema registries

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{}

Add a new external registry

Create external schema registry

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
schema_registry.confluent_schema_registry_auth_basic (object) or string
Default: "none"

Authentication options for accessing external registry.

name
required
string
type
string
Default: "confluent"
Value: "confluent"

External Schema Registry Type

url
required
string

URL endpoint for external registry.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

API Keys

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

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
{
  • "api_key": "a4697a5c75a769f6",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "name": "EMQX-API-KEY-1",
  • "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
desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

(integer or string) or string
Default: "infinity"

No longer valid datetime

role
string
Default: "administrator"

Role for this API

Responses

Request samples

Content type
application/json
{
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "role": "administrator"
}

Response samples

Content type
application/json
{
  • "api_key": "a4697a5c75a769f6",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "name": "EMQX-API-KEY-1",
  • "role": "administrator"
}

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
{
  • "api_key": "a4697a5c75a769f6",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "name": "EMQX-API-KEY-1",
  • "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
desc
string
enable
boolean

Enable/Disable

expired
boolean

Expired

(integer or string) or string
Default: "infinity"

No longer valid datetime

name
string

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

role
string
Default: "administrator"

Role for this API

Responses

Request samples

Content type
application/json
{
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "name": "EMQX-API-KEY-1",
  • "role": "administrator"
}

Response samples

Content type
application/json
{
  • "api_key": "a4697a5c75a769f6",
  • "api_secret": "MzAyMjk3ODMwMDk0NjIzOTUxNjcwNzQ0NzQ3MTE2NDYyMDI",
  • "created_at": "2021-12-01T00:00:00.000Z",
  • "desc": "Note",
  • "enable": true,
  • "expired": true,
  • "expired_at": "2021-12-05T02:01:34.186Z",
  • "name": "EMQX-API-KEY-1",
  • "role": "administrator"
}

License

Get license info

Get license info

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "customer": "Foo",
  • "customer_type": 10,
  • "deployment": "bar-deployment",
  • "email": "contact@foo.com",
  • "expiry": false,
  • "expiry_at": "2295-10-27",
  • "max_sessions": 10,
  • "start_at": "2022-01-11",
  • "type": "trial"
}

Update license key

Update a license key

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
required
string or 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 single-node community license.
- "evaluation": Use string value evaluation to apply the 25-connection limit evaluation 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
{
  • "customer": "Foo",
  • "customer_type": 10,
  • "deployment": "bar-deployment",
  • "email": "contact@foo.com",
  • "expiry": false,
  • "expiry_at": "2295-10-27",
  • "max_sessions": 10,
  • "start_at": "2022-01-11",
  • "type": "trial"
}

Get license setting

Update license setting

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "connection_high_watermark": "80%",
  • "connection_low_watermark": "75%"
}

Update license setting

Update license setting

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
connection_high_watermark
string
Default: "80%"

High watermark limit above which license connection quota usage alarms are activated

connection_low_watermark
string
Default: "75%"

Low watermark limit below which license connection quota usage alarms are deactivated

Responses

Request samples

Content type
application/json
{
  • "connection_high_watermark": "80%",
  • "connection_low_watermark": "75%"
}

Response samples

Content type
application/json
{
  • "connection_high_watermark": "80%",
  • "connection_low_watermark": "75%"
}

Durable Queues

Delete a declared durable queue

Delete a durable queue.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

The ID of the durable queue.

Responses

Response samples

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

Get a declared durable queue

Get the information of a durable queue.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string

The ID of the durable queue.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2024-01-01T12:34:56.789+02:00",
  • "group": "mygrp",
  • "id": "mygrp:1234EF",
  • "start_time": "2024-01-01T00:00:00.000+02:00",
  • "topic": "t/devices/#"
}

List declared durable queues

Get the list of durable queues.

Authorizations:
basicAuthbearerAuth
query Parameters
cursor
string

Opaque value representing the current iteration state.

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

Results per page

Responses

Response samples

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

Declare a durable queue

Declare new durable queue.

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

Responses

Request samples

Content type
application/json
{
  • "group": "string",
  • "start_time": 1640995200000,
  • "topic": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2024-01-01T12:34:56.789+02:00",
  • "group": "mygrp",
  • "id": "mygrp:1234EF",
  • "start_time": "2024-01-01T00:00:00.000+02:00",
  • "topic": "t/devices/#"
}

Dashboard Single Sign-On

/sso/saml/acs

Responses

Response samples

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

Get Dashboard Auth Token.

Get Dashboard Auth Token.

path Parameters
backend
required
string
Enum: "ldap" "oidc" "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
{
  • "license": {
    },
  • "role": "administrator",
  • "token": "string",
  • "version": "5.0.0"
}

The callback path for the OIDC authorization serve

The callback path for the OIDC authorization server.

Responses

Response samples

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

List all running SSO backends

List all running SSO backends

Responses

Response samples

Content type
application/json
[
  • "ldap"
]

/sso/saml/metadata

Authorizations:
basicAuthbearerAuth

Responses

Response samples

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

List all SSO backends

List all SSO backends

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a backend

Delete a backend

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

Responses

Response samples

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

Get details of a backend

Get details of a backend

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

Responses

Response samples

Content type
application/json
Example
{}

Update a backend

Update a backend

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

Backend type.

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

The address of the EMQX Dashboard.

enable
boolean
Default: false

Whether to enable this backend.

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

The URL of the IdP metadata.

sp_private_key
string <password>

The private key of the SP.

sp_public_key
string
Default: "Pub Key"

The public key of the SP.

sp_sign_request
boolean
Default: false

Whether to sign the SAML request.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{}

Retainer

View config

View config

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "allow_never_expire": true,
  • "backend": {
    },
  • "delivery_rate": "1000/s",
  • "enable": true,
  • "max_payload_size": "32MB",
  • "max_publish_rate": "1000/s",
  • "msg_clear_interval": "32s",
  • "msg_expiry_interval": "32s",
  • "msg_expiry_interval_override": "disabled",
  • "stop_publish_clear_msg": false
}

Update retainer config.

Update retainer config.

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

If true, retained messages set to never expire (i.e., whose Message-Expiry-Interval = 0) are not affected by the expiry time override. This configuration only takes effect when msg_expiry_interval_override is set.

object (retainer.mnesia_config)
delivery_rate
string
Default: "1000/s"

The maximum rate of delivering retained messages

enable
boolean
Deprecated
Default: true

Enable retainer feature

max_payload_size
string
Default: "1MB"

The maximum size of retained messages allowed to be stored. EMQX will refuse to store retained messages larger than this size and output an Error log with the keyword 'retain_failed_for_payload_size_exceeded_limit'.

0 means unlimited retained message size.

max_publish_rate
string
Default: "1000/s"

The maximum rate of publishing retained messages. Messages that are published over the limit are delivered but not stored as retained.

msg_clear_interval
string
Default: "0s"

The time interval for checking and clearing expired retained messages. This can prevent expired retained messages from being stored for a long time.

If msg_clear_interval is set to 0, that is, expired retained messages are not actively checked regularly, EMQX will only check and delete expired retained messages when preparing for delivery.

msg_expiry_interval
string
Default: "0s"

Expired retained messages will not be delivered again, and a setting of 0 means that retained messages will never expire.

However, if the Message-Expiry-Interval property is specified in the MQTT message, the value of that property prevails.

string or string
Default: "disabled"

If set, this value will take precedence over any Message-Expiry-Interval property specified in retained MQTT messages, allowing messages to expire earlier if necessary. This override only applies to the garbage collection process: it does not affect the expiry time of messages being written nor that of already written messages while iterating over them. Therefore, messages that are candidate for garbage collection when overridden may still be visible when subscribing to retained topics.

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

Responses

Request samples

Content type
application/json
{
  • "allow_never_expire": true,
  • "backend": {
    },
  • "delivery_rate": "1000/s",
  • "enable": true,
  • "max_payload_size": "32MB",
  • "max_publish_rate": "1000/s",
  • "msg_clear_interval": "32s",
  • "msg_expiry_interval": "32s",
  • "msg_expiry_interval_override": "disabled",
  • "stop_publish_clear_msg": false
}

Response samples

Content type
application/json
{
  • "allow_never_expire": true,
  • "backend": {
    },
  • "delivery_rate": "1000/s",
  • "enable": true,
  • "max_payload_size": "32MB",
  • "max_publish_rate": "1000/s",
  • "msg_clear_interval": "32s",
  • "msg_expiry_interval": "32s",
  • "msg_expiry_interval_override": "disabled",
  • "stop_publish_clear_msg": false
}

Delete all retained messages

Delete all retained messages

Authorizations:
basicAuthbearerAuth

Responses

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

Responses

Response samples

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

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

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
{
  • "from_clientid": "string",
  • "from_username": "string",
  • "msgid": "string",
  • "payload": "string",
  • "publish_at": "string",
  • "qos": 0,
  • "topic": "string"
}

Metrics

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

Node name

Responses

Response samples

Content type
application/json
{
  • "cluster_sessions": 0,
  • "connections": 0,
  • "disconnected_durable_sessions": 0,
  • "dropped_msg_rate": 0,
  • "license_quota": 0,
  • "live_connections": 0,
  • "node_uptime": 0,
  • "persisted_rate": 0,
  • "received_msg_rate": 0,
  • "retained_msg_count": 0,
  • "sent_msg_rate": 0,
  • "sessions_hist_hwmark": {
    },
  • "shared_subscriptions": 0,
  • "subscriptions": 0,
  • "subscriptions_durable": 0,
  • "topics": 0,
  • "transformation_failed_rate": 0,
  • "transformation_succeeded_rate": 0,
  • "validation_failed_rate": 0,
  • "validation_succeeded_rate": 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

Node name

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

The latest N seconds data. For example 300 for 5 minutes.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

EMQX stats

EMQX stats

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

Calculation aggregate for all nodes

Responses

Response samples

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

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
{
  • "cluster_sessions": 0,
  • "connections": 0,
  • "disconnected_durable_sessions": 0,
  • "dropped_msg_rate": 0,
  • "license_quota": 0,
  • "live_connections": 0,
  • "persisted_rate": 0,
  • "received_msg_rate": 0,
  • "retained_msg_count": 0,
  • "sent_msg_rate": 0,
  • "sessions_hist_hwmark": {
    },
  • "shared_subscriptions": 0,
  • "subscriptions": 0,
  • "subscriptions_durable": 0,
  • "topics": 0,
  • "transformation_failed_rate": 0,
  • "transformation_succeeded_rate": 0,
  • "validation_failed_rate": 0,
  • "validation_succeeded_rate": 0
}

EMQX metrics

EMQX metrics

Authorizations:
basicAuthbearerAuth
query Parameters
aggregate
boolean

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

node
string

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

Responses

Response samples

Content type
application/json
Example
[ ]

Clear monitor (statistics) data for the whole clus

Clear monitor (statistics) data for the whole cluster.

Authorizations:
basicAuthbearerAuth

Responses

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. For example 300 for 5 minutes.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
clientid
string
Deprecated
payload
required
string

The MQTT message payload.

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.

object (emqx_mgmt_api_publish.message_properties)
qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

retain
boolean
Default: false

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

topic
required
string

Topic Name

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
clientid
string
Deprecated
payload
required
string

The MQTT message payload.

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.

object (emqx_mgmt_api_publish.message_properties)
qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

retain
boolean
Default: false

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

topic
required
string

Topic Name

Responses

Request samples

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

Response samples

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

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
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.

qos
integer [ 0 .. 2 ]
Default: 0

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

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).

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.

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

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

GCP Devices

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

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
{
  • "config": "bXktY29uZmln",
  • "created_at": 1690484400,
  • "deviceid": "c2-ec-x509",
  • "keys": [ ],
  • "location": "europe-west1",
  • "project": "iot-export",
  • "registry": "my-registry"
}

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
config
required
string

Configuration

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

Public keys associated to GCP device

location
string
Default: ""

Cloud region

project
string
Default: ""

Cloud project identifier

registry
string
Default: ""

Device registry identifier

Responses

Request samples

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

Response samples

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

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

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

config
required
string

Configuration

deviceid
required
string

Device identifier

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

Public keys associated to GCP device

location
string
Default: ""

Cloud region

project
string
Default: ""

Cloud project identifier

registry
string
Default: ""

Device registry identifier

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Gateway Authentication

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
{
  • "failed": 0,
  • "override": 0,
  • "skipped": 0,
  • "success": 0,
  • "total": 0
}

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

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
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Create authenticator for gateway

Enables the authenticator for client authentication for the specified gateway.

When the authenticator is not configured or turned off, all client connections are assumed to be allowed.

Note: Only one authenticator is allowed to be enabled at a time in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT.

Authorizations:
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
required
Array of objects (authn.cinfo_check)

A list of checks to perform on the client information.
If all checks are skipped, the default result ignore is returned.
The ignore result means to defer the authentication to the next authenticator in the chain.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

mechanism
required
string
Value: "cinfo"

Authentication mechanism.

precondition
string
Default: ""

A Variform expression to evaluate with a set of pre-bound variables derived from the client information.

Supported variables:
- username: The username of the client
- password: The password of the client
- clientid: The client ID of the client
- client_attrs.*: The client attributes of the client
- cert_common_name: The subject field from the client's TLS certificate
- cert_subject: The common name (CN) from the client's TLS certificate
- peersni: The SNI (Server Name Indication) sent by TLS client
- listener: The listener ID (e.g. tcp:default)
- zone: The associated config zone.

The expression must evaluate to a string value of 'true' for this authenticator to be invoked.
If the expression evaluates to any other value, this authenticator will be skipped.

Examples:
- Only invoke if the client is connected from listener ssl:letsencryt:
str_eq(listener, 'ssl:letsencryt')
- Skip if username is empty:
not(is_empty_val(username))
- Only invoke if password exists and zone is 'zone1':
iif(is_empty_val(password), false, str_eq(zone, 'zone1'))

Find more information about Variform expressions in EMQX doc.

Responses

Request samples

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

Response samples

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

Update authenticator configuration

Update the configuration of the specified gateway authenticator, or disable the authenticator.

Authorizations:
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
required
Array of objects (authn.cinfo_check)

A list of checks to perform on the client information.
If all checks are skipped, the default result ignore is returned.
The ignore result means to defer the authentication to the next authenticator in the chain.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

mechanism
required
string
Value: "cinfo"

Authentication mechanism.

precondition
string
Default: ""

A Variform expression to evaluate with a set of pre-bound variables derived from the client information.

Supported variables:
- username: The username of the client
- password: The password of the client
- clientid: The client ID of the client
- client_attrs.*: The client attributes of the client
- cert_common_name: The subject field from the client's TLS certificate
- cert_subject: The common name (CN) from the client's TLS certificate
- peersni: The SNI (Server Name Indication) sent by TLS client
- listener: The listener ID (e.g. tcp:default)
- zone: The associated config zone.

The expression must evaluate to a string value of 'true' for this authenticator to be invoked.
If the expression evaluates to any other value, this authenticator will be skipped.

Examples:
- Only invoke if the client is connected from listener ssl:letsencryt:
str_eq(listener, 'ssl:letsencryt')
- Skip if username is empty:
not(is_empty_val(username))
- Only invoke if password exists and zone is 'zone1':
iif(is_empty_val(password), false, str_eq(zone, 'zone1'))

Find more information about Variform expressions in EMQX doc.

Responses

Request samples

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

Response samples

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

Import users

Import users into the gateway authenticator (only supports built_in_database)

Authorizations:
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
{
  • "failed": 0,
  • "override": 0,
  • "skipped": 0,
  • "success": 0,
  • "total": 0
}

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

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
is_superuser
boolean
Default: false
password
required
string

Responses

Request samples

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

Response samples

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

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

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
is_superuser
boolean
Default: false
password
required
string
user_id
required
string

Responses

Request samples

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

Response samples

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

Gateway Listeners

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
acceptors
integer
Default: 16

Size of the acceptor pool.

access_rules
Array of strings
Default: []

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

For example:

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

bind
string

The IP address and port that the listener will bind.

enable
boolean
Default: true

Enable the listener.

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.

id
string

Listener ID

max_conn_rate
integer
Default: 1000

Maximum connections per second.

string or integer
Default: 1024

The maximum number of concurrent connections allowed by the listener.

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

name
string

Listener Name

proxy_protocol
boolean
Default: false

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

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

proxy_protocol_timeout
string
Default: "3s"

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

running
boolean

Listener Running status

object (emqx.listener_wss_opts)
object (emqx.tcp_opts)
type
string
Value: "wss"

Listener Type

object (gateway.websocket)

Responses

Request samples

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

Response samples

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

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

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
is_superuser
boolean
Default: false
password
required
string
user_id
required
string

Responses

Request samples

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

Response samples

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

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 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
{
  • "acceptors": 16,
  • "access_rules": [
    ],
  • "bind": "22213",
  • "dtls_options": {
    },
  • "max_conn_rate": 1000,
  • "max_connections": 1024000,
  • "name": "dtls-def",
  • "type": "dtls",
  • "udp_options": {
    }
}

Update listener config

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

Authorizations:
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
acceptors
integer
Default: 16

Size of the acceptor pool.

access_rules
Array of strings
Default: []

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

For example:

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

bind
string

The IP address and port that the listener will bind.

enable
boolean
Default: true

Enable the listener.

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.

id
string

Listener ID

max_conn_rate
integer
Default: 1000

Maximum connections per second.

string or integer
Default: 1024

The maximum number of concurrent connections allowed by the listener.

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

name
string

Listener Name

proxy_protocol
boolean
Default: false

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

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

proxy_protocol_timeout
string
Default: "3s"

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

running
boolean

Listener Running status

object (emqx.listener_wss_opts)
object (emqx.tcp_opts)
type
string
Value: "wss"

Listener Type

object (gateway.websocket)

Responses

Request samples

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

Response samples

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

Delete user

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

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

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
is_superuser
boolean
Default: false
password
required
string

Responses

Request samples

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

Response samples

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

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

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
{
  • "algorithm": "hmac-based",
  • "mechanism": "jwt",
  • "secret": "mysecret",
  • "secret_base64_encoded": false,
  • "use_jwks": false,
  • "verify_claims": {
    }
}

Create authenticator for listener

Enable authenticator for specified listener for client authentication.

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

Authorizations:
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
required
Array of objects (authn.cinfo_check)

A list of checks to perform on the client information.
If all checks are skipped, the default result ignore is returned.
The ignore result means to defer the authentication to the next authenticator in the chain.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

mechanism
required
string
Value: "cinfo"

Authentication mechanism.

precondition
string
Default: ""

A Variform expression to evaluate with a set of pre-bound variables derived from the client information.

Supported variables:
- username: The username of the client
- password: The password of the client
- clientid: The client ID of the client
- client_attrs.*: The client attributes of the client
- cert_common_name: The subject field from the client's TLS certificate
- cert_subject: The common name (CN) from the client's TLS certificate
- peersni: The SNI (Server Name Indication) sent by TLS client
- listener: The listener ID (e.g. tcp:default)
- zone: The associated config zone.

The expression must evaluate to a string value of 'true' for this authenticator to be invoked.
If the expression evaluates to any other value, this authenticator will be skipped.

Examples:
- Only invoke if the client is connected from listener ssl:letsencryt:
str_eq(listener, 'ssl:letsencryt')
- Skip if username is empty:
not(is_empty_val(username))
- Only invoke if password exists and zone is 'zone1':
iif(is_empty_val(password), false, str_eq(zone, 'zone1'))

Find more information about Variform expressions in EMQX doc.

Responses

Request samples

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

Response samples

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

Update config of authenticator for listener

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

Authorizations:
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
required
Array of objects (authn.cinfo_check)

A list of checks to perform on the client information.
If all checks are skipped, the default result ignore is returned.
The ignore result means to defer the authentication to the next authenticator in the chain.

enable
boolean
Default: true

Set to true or false to disable this auth provider.

mechanism
required
string
Value: "cinfo"

Authentication mechanism.

precondition
string
Default: ""

A Variform expression to evaluate with a set of pre-bound variables derived from the client information.

Supported variables:
- username: The username of the client
- password: The password of the client
- clientid: The client ID of the client
- client_attrs.*: The client attributes of the client
- cert_common_name: The subject field from the client's TLS certificate
- cert_subject: The common name (CN) from the client's TLS certificate
- peersni: The SNI (Server Name Indication) sent by TLS client
- listener: The listener ID (e.g. tcp:default)
- zone: The associated config zone.

The expression must evaluate to a string value of 'true' for this authenticator to be invoked.
If the expression evaluates to any other value, this authenticator will be skipped.

Examples:
- Only invoke if the client is connected from listener ssl:letsencryt:
str_eq(listener, 'ssl:letsencryt')
- Skip if username is empty:
not(is_empty_val(username))
- Only invoke if password exists and zone is 'zone1':
iif(is_empty_val(password), false, str_eq(zone, 'zone1'))

Find more information about Variform expressions in EMQX doc.

Responses

Request samples

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

Response samples

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

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

Opentelemetry

Purge white list for specific type

Purge white list for specific type

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "clientid" "topic"
Example: clientid

Type of white list. Can be clientid, topic

Responses

Response samples

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

Show the list of sampler white list for specific t

Show the list of sampler white list for specific type

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "clientid" "topic"
Example: clientid

Type of white list. Can be clientid, topic

Responses

Response samples

Content type
application/json
Example
[
  • "clientid",
  • "clientid2"
]

Update white list for specific type

Update white list for specific type

Authorizations:
basicAuthbearerAuth
path Parameters
type
required
string
Enum: "clientid" "topic"
Example: clientid

Type of white list. Can be clientid, topic

Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
Example
[
  • "clientid",
  • "clientid2"
]

Response samples

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

Nodes

List EMQX nodes

List EMQX nodes

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
{
  • "messages.transformation_failed": 0,
  • "session.created": 0,
  • "packets.connack.sent": 0,
  • "overload_protection.delay.ok": 0,
  • "client.unsubscribe": 0,
  • "messages.dropped.receive_maximum": 0,
  • "session.discarded": 0,
  • "authorization.cache_hit": 0,
  • "packets.pubcomp.sent": 0,
  • "messages.persisted": 0,
  • "messages.qos0.received": 0,
  • "packets.puback.sent": 0,
  • "packets.publish.sent": 0,
  • "packets.pubrel.missed": 0,
  • "client.connected": 0,
  • "packets.suback.sent": 0,
  • "messages.validation_failed": 0,
  • "messages.dropped.quota_exceeded": 0,
  • "client.authenticate": 0,
  • "messages.dropped": 0,
  • "delivery.dropped.qos0_msg": 0,
  • "packets.received": 0,
  • "packets.auth.sent": 0,
  • "packets.subscribe.error": 0,
  • "messages.publish": 0,
  • "overload_protection.new_conn": 0,
  • "packets.pubrel.received": 0,
  • "authentication.success.anonymous": 0,
  • "authentication.success": 0,
  • "packets.pubrec.received": 0,
  • "delivery.dropped": 0,
  • "client.disconnected": 0,
  • "messages.delivered": 0,
  • "client.authorize": 0,
  • "messages.transformation_succeeded": 0,
  • "messages.qos1.received": 0,
  • "packets.unsubscribe.error": 0,
  • "authorization.allow": 0,
  • "overload_protection.gc": 0,
  • "packets.publish.auth_error": 0,
  • "delivery.dropped.no_local": 0,
  • "session.takenover": 0,
  • "packets.unsuback.sent": 0,
  • "packets.publish.received": 0,
  • "packets.puback.missed": 0,
  • "packets.pubrec.missed": 0,
  • "packets.publish.inuse": 0,
  • "bytes.received": 0,
  • "messages.qos2.sent": 0,
  • "client.connack": 0,
  • "packets.puback.received": 0,
  • "packets.pubcomp.inuse": 0,
  • "messages.qos2.received": 0,
  • "packets.sent": 0,
  • "packets.disconnect.sent": 0,
  • "packets.pubrel.sent": 0,
  • "packets.disconnect.received": 0,
  • "packets.pingresp.sent": 0,
  • "packets.connect.received": 0,
  • "messages.sent": 0,
  • "packets.publish.quota_exceeded": 0,
  • "packets.auth.received": 0,
  • "messages.received": 0,
  • "packets.pubrec.sent": 0,
  • "authorization.cache_miss": 0,
  • "messages.dropped.await_pubrel_timeout": 0,
  • "packets.subscribe.received": 0,
  • "delivery.dropped.expired": 0,
  • "session.terminated": 0,
  • "overload_protection.hibernation": 0,
  • "client.connect": 0,
  • "messages.delayed": 0,
  • "packets.pubcomp.received": 0,
  • "authentication.failure": 0,
  • "client.auth.anonymous": 0,
  • "messages.qos1.sent": 0,
  • "packets.pingreq.received": 0,
  • "delivery.dropped.too_large": 0,
  • "bytes.sent": 0,
  • "overload_protection.delay.timeout": 0,
  • "authorization.deny": 0,
  • "packets.subscribe.auth_error": 0,
  • "packets.connack.error": 0,
  • "messages.dropped.no_subscribers": 0,
  • "messages.forward": 0,
  • "messages.acked": 0,
  • "packets.puback.inuse": 0,
  • "delivery.dropped.queue_full": 0,
  • "packets.publish.error": 0,
  • "messages.validation_succeeded": 0,
  • "session.resumed": 0,
  • "node": "string",
  • "packets.pubrec.inuse": 0,
  • "messages.qos0.sent": 0,
  • "packets.unsubscribe.received": 0,
  • "client.subscribe": 0,
  • "packets.pubcomp.missed": 0,
  • "packets.connack.auth_error": 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
{
  • "cluster_sessions": 0,
  • "connections": 0,
  • "edition": "Opensource",
  • "live_connections": 0,
  • "load1": 2.66,
  • "load15": 2.66,
  • "load5": 2.66,
  • "log_path": "path/to/log | The log path is not yet set",
  • "max_fds": 1024,
  • "memory_total": "512.00M",
  • "memory_used": "256.00M",
  • "node": "emqx@127.0.0.1",
  • "node_status": "running",
  • "otp_release": "24.2/12.2",
  • "process_available": 2097152,
  • "process_used": 1024,
  • "role": "core",
  • "sys_path": "path/to/emqx",
  • "uptime": 5120000,
  • "version": "5.0.0"
}

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,
  • "cluster_sessions.count": 0,
  • "cluster_sessions.max": 0,
  • "connections.count": 0,
  • "connections.max": 0,
  • "delayed.count": 0,
  • "delayed.max": 0,
  • "live_connections.count": 0,
  • "live_connections.max": 0,
  • "retained.count": 0,
  • "retained.max": 0,
  • "sessions.count": 0,
  • "sessions.max": 0,
  • "suboptions.count": 0,
  • "suboptions.max": 0,
  • "subscribers.count": 0,
  • "subscribers.max": 0,
  • "subscriptions.count": 0,
  • "subscriptions.max": 0,
  • "subscriptions.shared.count": 0,
  • "subscriptions.shared.max": 0,
  • "topics.count": 0,
  • "topics.max": 0
}

Alarms

Remove all historical alarms.

Remove all historical alarms.

Authorizations:
basicAuthbearerAuth

Responses

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

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