# REST API

EMQ X Cloud API follows the REST architecture, and you can access the functions of EMQ X programmatically.

# API address

You can get the API access address through the deployment details page.

api-access

If we want to get the information of all nodes, we can call it like this:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/brokers"

# Interface security

HTTP API uses the method of Basic authentication (opens new window). The id and password must be filled in AppID and AppSecret respectively. You can modify and add AppID/AppSecret by creating an application access in the API access under the deployment details page.

api-app

# Response code

# HTTP status codes

The EMQ X Broker interface always returns 200 OK when the call is successful, and the response content is returned in JSON format.

The possible status codes are as follows:

Status CodeDescription
200Succeed, and the returned JSON data will provide more information
400Invalid client request, such as wrong request body or parameters
401Client authentication failed , maybe because of invalid authentication credentials
404The requested path cannot be found or the requested object does not exist
500An internal error occurred while the server was processing the request

# Result codes

The response message body of the EMQ X Broker interface is in JSON format, which always contains the returned code.

The possible result codes are as follows:

Return CodeDescription
0Succeed
101RPC error
102unknown mistake
103wrong user name or password
104Empty username or password
105User does not exist
106Administrator account cannot be deleted
107Missing key request parameters
108Request parameter error
109Request parameters are not in legal JSON format
110Plug-in is enabled
111Plugin is closed
112Client is offline
113User already exists
114Old password is wrong
115Illegal subject

# API Endpoints

# Broker basic Information

# Return basic information of all nodes in the cluster.

GET /brokers/{node}

URL Path Parameters:

NameTypeRequiredDescription
nodeStringFalseNode name, such as "emqx@127.0.0.1". If not specified, returns all node information

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of ObjectsReturns the information of the specified node when the parameter exists, otherwise, returns the information of all nodes
data.datetimeStringCurrent time, in the format of "YYYY-MM-DD HH: mm: ss"
data.nodeStringNode name
data.node_statusStringNode status
data.otp_releaseStringErlang/OTP version used by EMQ X Broker
data.sysdescrStringSoftware description
data.uptimeStringEMQ X Broker runtime, in the format of "H hours, m minutes, s seconds"
data.versionStringEMQ X Broker version

Examples:

Get the basic information of all nodes:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/brokers"

{"data":[{"version":"develop","uptime":"4 hours, 21 minutes, 19 seconds","sysdescr":"EMQ X Broker","otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","datetime":"2020-02-19 15:27:24"}],"code":0}

Get the basic information of node emqx@127.0.0.1 :

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/brokers/emqx@127.0.0.1"

{"data":{"version":"develop","uptime":"1 minutes, 51 seconds","sysdescr":"EMQ X Broker","otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","datetime":"2020-02-20 14:11:31"},"code":0}

# Node

# Get the status of the node

GET /nodes/{node}

URL Path Parameters:

NameTypeRequiredDescription
nodeStringFalseNode name, such as "emqx@127.0.0.1". If not specified, returns all node information

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of ObjectsReturns node information when node parameter exists, otherwise, returns information about all nodes in an Array
data.connectionsIntegerNumber of clients currently connected to this node
data.load1StringCPU average load in 1 minute
data.load5StringCPU average load in 5 minute
data.load15StringCPU average load in 15 minute
data.max_fdsIntegerMaximum file descriptor limit for the operating system
data.memory_totalStringVM allocated system memory
data.memory_usedStringVM occupied system memory
data.nodeStringNode name
data.node_statusStringNode status
data.otp_releaseStringErlang/OTP version used by EMQ X Broker
data.process_availableIntegerNumber of available processes
data.process_usedIntegerNumber of used processes
data.uptimeStringEMQ X Broker runtime
data.versionStringEMQ X Broker version

Examples:

Get the status of all nodes:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes"

{"data":[{"version":"develop","uptime":"7 seconds","process_used":315,"process_available":2097152,"otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","memory_used":"96.75M","memory_total":"118.27M","max_fds":10240,"load5":"2.60","load15":"2.65","load1":"2.31","connections":0}],"code":0}

Get the status of the specified node:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1"

{"data":{"version":"develop","uptime":"2 minutes, 21 seconds","process_used":310,"process_available":2097152,"otp_release":"R21/10.3.5","node_status":"Running","node":"emqx@127.0.0.1","memory_used":101379168,"memory_total":123342848,"max_fds":10240,"load5":"2.50","load15":"2.61","load1":"1.99","connections":0},"code":0}

# Manage authentication data

# View the authentication data that has been added

GET /auth_user

URL Query parameter:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1Page
_limitIntegerFalse10000The number of data items displayed on each page. If not specified, it is determined by the configuration item max_row_limit of the emqx-management plugin

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll authentication data
data[0].loginStringLogin Username
data[0].passwordStringLogin Password
data[0].is_superuserBooleanIs super user or not
metaObject分页信息
meta.pageIntegerPage number
meta.limitIntegerNumber of data items displayed per page
meta.countIntegerTotal number of data

Example:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user"

{"meta":{"page":1,"limit":10,"count":3},"data":[{"password":"efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7","login":"test1","is_superuser":false},{"password":"efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7","login":"test2","is_superuser":false},{"password":"efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7","login":"test3","is_superuser":false}],"code":0}

# Add authentication data in batch

POST /auth_user

Request message element (json):

NameTypeRequiredDescription
[0].loginStringTrueLogin Username
[0].passwordStringTrueLogin Password
[0]is_superuserBooleanTrueIs super user or not

Success response message element (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAuthentication data addition status, ok means the corresponding authentication data is added successfully

Example:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user" -d '[{"login":"test5","password":"public", "is_superuser": false}]'

{"data":{"test5":"ok"},"code":0}

# Update the added authentication data

PUT /auth_user/${login}

Request message element (json):

NameTypeRequiredDescription
passwordStringTrueLogin Password
is_superuserBooleanTrueIs super user or not

Success response message element (JSON):

NameTypeDescription
codeInteger0

Example:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X PUT "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user/test5" -d '{"password":"public1", "is_superuser": false}'

{"code":0}

# Delete authentication data

DELETE /auth_user/${login}

Success response message element(JSON):

NameTypeDescription
codeInteger0

Example:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/auth_user/test5"

{"code":0}

# Client

# Get information of all clients in the cluster

GET /clients

URL Query Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1Page
_limitIntegerFalse10000The number of data displayed per page. If not specified, it is determined by the configuration item max_row_limit of theemqx-management plugin

After version 4.1, multiple conditions and fuzzy queries are supported. The query parameters included are shown below.

NameTypeRequiredDescription
clientidStringFalseClient identifier
usernameStringFalseClient username
zoneStringFalseClient configuration group name
ip_addressStringFalseClient IP address
conn_stateEnumFalseThe current connection status of the client, the possible values areconnected,idle,disconnected
clean_startBoolFalseWhether the client uses a new session
proto_nameEnumFalseClient protocol name, the possible values areMQTT,CoAP,LwM2M,MQTT-SN
proto_verIntegerFalseClient protocol version
_like_clientidStringFalseFuzzy search of client identifier by substring method
_like_usernameStringFalseClient user name, fuzzy search by substring
_gte_created_atIntegerFalseSearch client session creation time by less than or equal method
_lte_created_atIntegerFalseSearch client session creation time by greater than or equal method
_gte_connected_atIntegerFalseSearch client connection creation time by less than or equal method
_lte_connected_atIntegerFalseSearch client connection creation time by greater than or equal method

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsInformation for all clients
data[0].nodeStringName of the node to which the client is connected
data[0].clientidStringClient identifier
data[0].usernameStringUser name of client when connecting
data[0].proto_nameStringClient protocol name
data[0].proto_verIntegerProtocol version used by the client
data[0].ip_addressStringClient's IP address
data[0].portIntegerClient port
data[0].is_bridgeBooleanIndicates whether the client is connected via bridge
data[0].connected_atStringClient connection time, in the format of "YYYY-MM-DD HH:mm:ss"
data[0].disconnected_atStringClient offline time, in the format of "YYYY-MM-DD HH:mm:ss", This field is only valid and returned when connected isfalse
data[0].connectedBooleanWhether the client is connected
data[0].zoneStringIndicate the configuration group used by the client
data[0].keepaliveIntegerkeepalive time, with the unit of second
data[0].clean_startBooleanIndicate whether the client is using a brand new session
data[0].expiry_intervalIntegerSession expiration interval, with the unit of second
data[0].created_atStringSession creation time, in the format "YYYY-MM-DD HH:mm:ss"
data[0].subscriptions_cntIntegerNumber of subscriptions established by this client
data[0].max_subscriptionsIntegerMaximum number of subscriptions allowed by this client
data[0].inflightIntegerCurrent length of inflight
data[0].max_inflightIntegerMaximum length of inflight
data[0].mqueue_lenIntegerCurrent length of message queue
data[0].max_mqueueIntegerMaximum length of message queue
data[0].mqueue_droppedIntegerNumber of messages dropped by the message queue due to exceeding the length
data[0].awaiting_relIntegerNumber of awaiting PUBREC packet
data[0].max_awaiting_relIntegerMaximum allowed number of awaiting PUBREC packet
data[0].recv_octIntegerNumber of bytes received by EMQ X Broker (the same below)
data[0].recv_cntIntegerNumber of TCP packets received
data[0].recv_pktIntegerNumber of MQTT packets received
data[0].recv_msgIntegerNumber of PUBLISH packets received
data[0].send_octIntegerNumber of bytes sent
data[0].send_cntIntegerNumber of TCP packets sent
data[0].send_pktIntegerNumber of MQTT packets sent
data[0].send_msgIntegerNumber of PUBLISH packets sent
data[0].mailbox_lenIntegerProcess mailbox size
data[0].heap_sizeIntegerProcess heap size with the unit of byte
data[0].reductionsIntegerErlang reduction
metaObjectPaging information
meta.pageIntegerPage number
meta.limitIntegerNumber of data displayed per page
meta.countIntegerTotal number of data

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients?_page=1&_limit=10"

{"meta":{"page":1,"limit":10,"count":1},"data":[{"zone":"external","recv_cnt":2,"max_mqueue":1000,"node":"emqx@127.0.0.1","username":"test","mqueue_len":0,"max_inflight":32,"is_bridge":false,"mqueue_dropped":0,"inflight":0,"heap_size":2586,"max_subscriptions":0,"proto_name":"MQTT","created_at":"2020-02-19 17:01:26","proto_ver":4,"reductions":3997,"send_msg":0,"ip_address":"127.0.0.1","send_cnt":0,"mailbox_len":1,"awaiting_rel":0,"keepalive":60,"recv_msg":0,"send_pkt":0,"recv_oct":29,"clientid":"example","clean_start":true,"expiry_interval":0,"connected":true,"port":64491,"send_oct":0,"recv_pkt":1,"connected_at":"2020-02-19 17:01:26","max_awaiting_rel":100,"subscriptions_cnt":0}],"code":0}

Tip

After version 4.1, the contents of the returned meta were modified:

  • count:It still represents the total number. However, in multi-condition/fuzzy query, it is fixed at -1.
  • hasnext:It is a newly added field indicating whether there is a next page.

# Get the information of the specified client

GET /clients/{clientid}

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsClient information, for details, see GET /api/clients (opens new window)

Examples:

Query the specified client

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example"

{"data":[{"recv_cnt":2,"max_subscriptions":0,"node":"emqx@127.0.0.1","proto_ver":4,"recv_pkt":1,"inflight":0,"max_mqueue":1000,"heap_size":2586,"username":"test","proto_name":"MQTT","subscriptions_cnt":0,"send_pkt":0,"created_at":"2020-02-20 13:38:51","reductions":3978,"ip_address":"127.0.0.1","send_msg":0,"send_cnt":0,"expiry_interval":0,"keepalive":60,"mqueue_dropped":0,"is_bridge":false,"max_inflight":32,"recv_msg":0,"max_awaiting_rel":100,"awaiting_rel":0,"mailbox_len":1,"mqueue_len":0,"recv_oct":29,"connected_at":"2020-02-20 13:38:51","clean_start":true,"clientid":"example","connected":true,"port":54889,"send_oct":0,"zone":"external"}],"code":0}

# Delete the specified client

DELETE /clients/{clientid}

Tip

this operation will terminate the connection with the session.

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Delete the specified client

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example"

{"code":0}

# Get the information of all clients under the specified node

GET /nodes/{node}/clients

URL Path Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1page number
_limitIntegerFalse10000The number of data displayed per page, if not specified, it is determined by the configuration item max_row_limit of the emqx-management plugin

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsInformation about all clients, see GET /api/clients (opens new window) for details

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/clients?_page=1&_limit=10"

{"meta":{"page":1,"limit":10,"count":1},"data":[{"recv_cnt":2,"max_subscriptions":0,"node":"emqx@127.0.0.1","proto_ver":4,"recv_pkt":1,"inflight":0,"max_mqueue":1000,"heap_size":2586,"username":"test","proto_name":"MQTT","subscriptions_cnt":0,"send_pkt":0,"created_at":"2020-02-19 18:25:18","reductions":4137,"ip_address":"127.0.0.1","send_msg":0,"send_cnt":0,"expiry_interval":0,"keepalive":60,"mqueue_dropped":0,"is_bridge":false,"max_inflight":32,"recv_msg":0,"max_awaiting_rel":100,"awaiting_rel":0,"mailbox_len":1,"mqueue_len":0,"recv_oct":29,"connected_at":"2020-02-19 18:25:18","clean_start":true,"clientid":"example","connected":true,"port":49509,"send_oct":0,"zone":"external"}],"code":0}

# Get the information of the specified client under the specified node

GET /nodes/{node}/clients/{clientid}

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectClient information, for details, see GET /api/clients (opens new window)

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/clients/example"

{"data":[{"recv_cnt":4,"max_subscriptions":0,"node":"emqx@127.0.0.1","proto_ver":4,"recv_pkt":1,"inflight":0,"max_mqueue":1000,"heap_size":2586,"username":"test","proto_name":"MQTT","subscriptions_cnt":0,"send_pkt":3,"created_at":"2020-02-20 13:38:51","reductions":5994,"ip_address":"127.0.0.1","send_msg":0,"send_cnt":3,"expiry_interval":0,"keepalive":60,"mqueue_dropped":0,"is_bridge":false,"max_inflight":32,"recv_msg":0,"max_awaiting_rel":100,"awaiting_rel":0,"mailbox_len":0,"mqueue_len":0,"recv_oct":33,"connected_at":"2020-02-20 13:38:51","clean_start":true,"clientid":"example","connected":true,"port":54889,"send_oct":8,"zone":"external"}],"code":0}

# Query client information through Username

GET /clients/username/{username}

Since multiple clients may use the same user name, multiple client information may be returned at the same time.

URL Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsClient information, for details, see GET /api/clients (opens new window)

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/username/steve"

{"data":[{"clean_start":true,"awaiting_rel":0,"recv_msg":0,"proto_name":"MQTT","recv_cnt":2,"mailbox_len":0,"node":"emqx@127.0.0.1","mqueue_len":0,"max_subscriptions":0,"created_at":"2020-02-20 13:50:11","is_bridge":false,"heap_size":2586,"proto_ver":4,"subscriptions_cnt":0,"clientid":"example","expiry_interval":0,"send_msg":0,"inflight":0,"reductions":4673,"send_pkt":1,"zone":"external","send_cnt":1,"ip_address":"127.0.0.1","keepalive":60,"max_inflight":32,"recv_oct":29,"recv_pkt":1,"max_awaiting_rel":100,"username":"steve","connected_at":"2020-02-20 13:50:11","connected":true,"port":56429,"send_oct":4,"mqueue_dropped":0,"max_mqueue":1000}],"code":0}

# Under the specified node, query the information of the specified client through Username

GET /nodes/{node}/clients/username/{username}

URL Path Parameters

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsClient information, for details, see GET /api/clients (opens new window)

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/clients/username/test"

{"data":[{"clean_start":true,"awaiting_rel":0,"recv_msg":0,"proto_name":"MQTT","recv_cnt":6,"mailbox_len":0,"node":"emqx@127.0.0.1","mqueue_len":0,"max_subscriptions":0,"created_at":"2020-02-20 13:50:11","is_bridge":false,"heap_size":1598,"proto_ver":4,"subscriptions_cnt":0,"clientid":"example","expiry_interval":0,"send_msg":0,"inflight":0,"reductions":7615,"send_pkt":5,"zone":"external","send_cnt":5,"ip_address":"127.0.0.1","keepalive":60,"max_inflight":32,"recv_oct":37,"recv_pkt":1,"max_awaiting_rel":100,"username":"test","connected_at":"2020-02-20 13:50:11","connected":true,"port":56429,"send_oct":12,"mqueue_dropped":0,"max_mqueue":1000}],"code":0}

# Query the ACL cache of the specified client

GET /clients/{clientid}/acl_cache

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsACL Details
data[0].accessStringPublish/Scribe
data[0].topicStringMQTT Topic
data[0].resultStringAllow/Deny
data[0].updated_timeIntegerACL Cache settling time

Examples:

Querying the ACL cache

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example/acl_cache"

{"data":[{"updated_time":1582180824571,"topic":"test","result":"allow","access":"publish"}],"code":0}

# Delete the ACL cache of the specified client

DELETE /clients/{clientid}/acl_cache

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Delete the ACL cache

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/clients/example/acl_cache"

{"code":0}

# Subscription Information

# Get all subscription information under the cluster

GET /subscriptions

URL Query Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1Page number
_limitIntegerFalse10000The number of data displayed per page, if not specified, it is determined by the configuration item max_row_limit of the emqx-management plugin

After version 4.1, multiple conditions and fuzzy queries are supported:

NameTypeDescription
clientidStringClient identifier
topicStringcongruent query
qosEnumPossible values are 0,1,2`
shareStringShared subscription group name
_match_topicStringTopic Match query

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll subscription information
data[0].nodeStringNode name
data[0].clientidStringClient identifier
data[0].topicStringSubscribe to topic
data[0].qosIntegerQoS level
metaObjectsame as /api/v4/clients

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/subscriptions?_page=1&_limit=10"

{"meta":{"page":1,"limit":10000,"count":2},"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"78082755-e8eb-4a87-bab7-8277541513f0"},{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"7a1dfceb-89c0-4f7e-992b-dfeb09329f01"}],"code":0}

Tip

After 4.1, the contents of the returned meta were modified:

  • count:It still represents the total number, but in multi-condition/fuzzy query, it is fixed at -1.
  • hasnext:It is a newly added field indicating whether there is a next page.

# Get the subscription information of the specified client in the cluster

GET /subscriptions/{clientid}

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectAll subscription information
data.nodeStringNode name
data.clientidStringClient identifier
data.topicStringSubscribe to topic
data.qosIntegerQoS level

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/subscriptions/123"

{"data":[{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"123"}],"code":0}

# Get all subscription information under the specified node

GET /nodes/{node}/subscriptions

URL Query Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1Page number
_limitIntegerFalse10000The number of data displayed per page, if not specified, it is determined by the configuration item max_row_limit of the emqx-management plugin

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll subscription information
data[0].nodeStringNode name
data[0].clientidStringClient identifier
data[0].topicStringSubscribe to topic
data[0].qosIntegerQoS level
metaObjectSame as /api/v4/clients

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/subscriptions?_page=1&limit=10"

{"meta":{"page":1,"limit":10000,"count":2},"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"78082755-e8eb-4a87-bab7-8277541513f0"},{"topic":"a/b/c","qos":1,"node":"emqx@127.0.0.1","clientid":"7a1dfceb-89c0-4f7e-992b-dfeb09329f01"}],"code":0}

# Query all subscription information of a clientid under the specified node,

GET /nodes/{node}/subscriptions/{clientid}

URL Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectAll subscription information
data.nodeStringNode name
data.clientidStringClient identifier
data.topicStringSubscribe to topic
data.qosIntegerQoS level

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/subscriptions/sample"

{"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"sample"}],"code":0}

# Routes

# Get all routes information under the cluster

GET /routes

URL Query Parameters:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1Page number
_limitIntegerFalse10000The number of data displayed per page, if not specified, it is determined by the configuration item max_row_limit of the emqx-management plugin

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll routes
data[0].topicStringMQTT Topic
data[0].nodeStringNode name
metaObjectsee /api/v4/clients

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/routes"

{"meta":{"page":1,"limit":10000,"count":2},"data":[{"topic":"a/+/c","node":"emqx@127.0.0.1"},{"topic":"a/b/c","node":"emqx@127.0.0.1"}],"code":0}

# Get the routes information of the specified topic under the cluster

GET /routes/{topic}

URL Path Parameters:

NameTypeRequiredDescription
topicIntegerTrueTopic

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectAll routes information
data.topicStringMQTT Topic
data.nodeStringNode name

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/routes/a%2fb%2fc"

{"data":[{"topic":"a/b/c","node":"emqx@127.0.0.1"}],"code":0}

# Publish /Subscribe ACL

# View ACL rules that have been added

GET /emqx_acl

URL Query parameter:

NameTypeRequiredDefaultDescription
_pageIntegerFalse1Page number
_limitIntegerFalse10000The number of data displayed per page, if not specified, it is determined by the configuration item max_row_limit of the emqx-management plugin

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll authentication data
data[0].topicStringSpecified topic
data[0].loginStringSpecified login user name
data[0].allowBooleanWhether allowed
data[0].actionStringACL rule action
metaObjectPaging information
meta.pageIntegerPage number
meta.limitIntegerThe number of data displayed per page
meta.countIntegerTotal number of data

Examples:

curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/emqx_acl"

{"meta":{"page":1,"limit":10,"count":2},"data":[{"topic":"/test1","login":"test1","allow":true,"action":"pubsub"},{"topic":"/test","login":"test2","allow":true,"action":"pubsub"}],"code":0}

# Add ACL rules in batch

POST /emqx_acl

Request message element (json):

NameTypeRequiredDescription
data[0].topicStringTrueSpecified topic
data[0].loginStringTrueSpecified login user name
data[0].allowBooleanTrueWhether allowed
data[0].actionStringTrueACL rule action

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsACL rule addition status, ok means the corresponding ACL rule is added successfully

Examples:

curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/emqx_acl" -d
'[{"topic":"test","login":"test3","allow":false,"action":"pubsub"}]'

{"data":{"test3":"ok"},"code":0}

# Delete ACL rules

DELETE /emqx_acl/${login}/${topic}

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X DELETE "https://lacd0b7b.test-cn.emqx.cloud:8443/api/emqx_acl/emqx_acl/test3/test"

{"code":0}

# Publish message

# Publish MQTT message

POST /mqtt/publish

Request message element (json):

NameTypeRequiredDefaultDescription
topicStringOptionalFor topic and topics, with at least one of them specified
topicsStringOptionalMultiple topics separated by ,. This field is used to publish messages to multiple topics at the same time
clientidStringRequiredClient identifier
payloadStringRequiredMessage body
encodingStringOptionalplainThe encoding used in the message body. Currently only plain and base64 are supported.
qosIntegerOptional0QoS level
retainBooleanOptionalfalseWhether it is a retained message

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/publish" -d '{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example"}'

{"code":0}

# Publish MQTT message in batch

POST /mqtt/publish_batch

Request message element (json):

NameTypeRequiredDefaultDescription
topicStringOptionalFor topic and topics, with at least one of them specified
topicsStringOptionalMultiple topics separated by ,. This field is used to publish messages to multiple topics at the same time
clientidStringRequiredClient identifier
payloadStringRequiredMessage body
encodingStringOptionalplainThe encoding used in the message body. Currently only plain and base64 are supported.
qosIntegerOptional0QoS level
retainBooleanOptionalfalseWhether it is a retained message

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/publish_batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example"},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example"}]'

{"code":0}

# Subscribe to topic

# Subscribe to MQTT topic

POST /mqtt/subscribe

Request message element (json):

NameTypeRequiredDefaultDescription
topicStringOptionalFor topic and topics, with at least one of them specified
topicsStringOptionalMultiple topics separated by ,. This field is used to subscribe to multiple topics at the same time
clientidStringRequiredClient identifier
qosIntegerOptional0QoS level

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Subscribe to the three topics of a, b, c at the same time

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/subscribe" -d '{"topics":"a,b,c","qos":1,"clientid":"example"}'

{"code":0}

# Unsubscribe

POST /mqtt/unsubscribe

Request message element (json):

NameTypeRequiredDefaultDescription
topicStringRequiredTopic
clientidStringRequiredClient identifier

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Unsubscribe to topic a

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'

{"code":0}

# Subscribe to MQTT topic in batch

POST /mqtt/subscribe_batch

Request message element (json):

NameTypeRequiredDefaultDescription
[0].topicStringOptionalFor topic and topics, with at least one of them specified
[0].topicsStringOptionalMultiple topics separated by ,. This field is used to subscribe to multiple topics at the same time
[0].clientidStringRequiredClient identifier
[0].qosIntegerOptional0QoS level

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Subscribe to the three topics of a, b, c at the same time

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/subscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"},{"topic":"c","qos":1,"clientid":"example"}]'

{"code":0}

# Unsubscribe in batch

POST /mqtt/unsubscribe_batch

Request message element (json):

NameTypeRequiredDefaultDescription
[0].topicStringRequiredTopic
[0].clientidStringRequiredClient identifier

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Unsubscribe to the three topics of a, b, c at the same time

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X POST "https://lacd0b7b.test-cn.emqx.cloud:8443/api/mqtt/unsubscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"}]'

{"code":0}

# Listener

# Get information about all listeners in the cluster

GET /listeners

URL Path Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsList of listeners for each node
data[0].nodeStringNode name
data[0].listenersArray of ObjectsListener list
data[0].listeners[0].acceptorsIntegerNumber of Acceptor process
data[0].listeners[0].listen_onStringListening port
data[0].listeners[0].protocolStringPlugin description
data[0].listeners[0].current_connsIntegerWhether plugin is enabled
data[0].listeners[0].max_connsIntegerMaximum number of allowed connections
data[0].listeners[0].shutdown_countArray of ObjectsReasons and counts for connection shutdown

Normal shutdown_count

NameTypeDescription
normalIntegerNumber of normally closed connections, only returned when the count is greater than 0
kickedIntegerNumber of manually dropped connections, only returned if the count is greater than 0
discardedIntegerNumber of connections dropped because Clean Session or Clean Start is true
takeoveredIntegerNumber of connections takeovered because Clean Session or Clean Start is false

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/listeners"

{"data":[{"node":"emqx@127.0.0.1","listeners":[{"shutdown_count":[],"protocol":"mqtt:ssl","max_conns":102400,"listen_on":"8883","current_conns":0,"acceptors":16},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"0.0.0.0:1883","current_conns":13,"acceptors":8},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"127.0.0.1:11883","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:dashboard","max_conns":512,"listen_on":"18083","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:management","max_conns":512,"listen_on":"8081","current_conns":1,"acceptors":2},{"shutdown_count":[],"protocol":"https:dashboard","max_conns":512,"listen_on":"18084","current_conns":0,"acceptors":2},{"shutdown_count":[],"protocol":"mqtt:ws:8083","max_conns":102400,"listen_on":"8083","current_conns":1,"acceptors":4},{"shutdown_count":[],"protocol":"mqtt:wss:8084","max_conns":16,"listen_on":"8084","current_conns":0,"acceptors":4}]}],"code":0}

# Get the listener information for the specified node

GET /nodes/{node}/listeners

URL Path Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsList of listeners for each node
data[0].acceptorsIntegerNumber of Acceptor process
data[0].listen_onStringListening port
data[0].protocolStringPlugin description
data[0].current_connsIntegerWhether the plugin is enabled
data[0].max_connsIntegerMaximum number of allowed connections
data[0].shutdown_countArray of ObjectsReasons and counts for connection shutdown

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/listeners"

{"data":[{"shutdown_count":[],"protocol":"mqtt:ssl","max_conns":102400,"listen_on":"8883","current_conns":0,"acceptors":16},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"0.0.0.0:1883","current_conns":13,"acceptors":8},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"127.0.0.1:11883","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:dashboard","max_conns":512,"listen_on":"18083","current_conns":0,"acceptors":4},{"shutdown_count":[],"protocol":"http:management","max_conns":512,"listen_on":"8081","current_conns":1,"acceptors":2},{"shutdown_count":[],"protocol":"https:dashboard","max_conns":512,"listen_on":"18084","current_conns":0,"acceptors":2},{"shutdown_count":[],"protocol":"mqtt:ws:8083","max_conns":102400,"listen_on":"8083","current_conns":1,"acceptors":4},{"shutdown_count":[],"protocol":"mqtt:wss:8084","max_conns":16,"listen_on":"8084","current_conns":0,"acceptors":4}],"code":0}

# Metrics

# Get all statistical metrics under the cluster

GET /metrics

URL Path Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsList of statistical metrics on each node
data[0].nodeStringNode name
data[0].metricsObjectMonitoring metrics data, see metrics below

metrics:

NameTypeDescription
actions.failureIntegerNumber of failure executions of the rule engine action
actions.successIntegerNumber of successful executions of the rule engine action
bytes.receivedIntegerNumber of bytes received by EMQ X Broker
bytes.sentIntegerNumber of bytes sent by EMQ X Broker on this connection
client.authenticateIntegerNumber of client authentications
client.auth.anonymousIntegerNumber of clients who log in anonymously
client.connectIntegerNumber of client connections
client.connackIntegerNumber of CONNACK packet sent
client.connectedIntegerNumber of successful client connections
client.disconnectedIntegerNumber of client disconnects
client.check_aclIntegerNumber of ACL rule checks
client.subscribeIntegerNumber of client subscriptions
client.unsubscribeIntegerNumber of client unsubscriptions
delivery.dropped.too_largeIntegerThe number of messages that were dropped because the length exceeded the limit when sending
delivery.dropped.queue_fullIntegerNumber of messages with a non-zero QoS that were dropped because the message queue was full when sending
delivery.dropped.qos0_msgIntegerNumber of messages with QoS 0 that were dropped because the message queue was full when sending
delivery.dropped.expiredIntegerNumber of messages dropped due to message expiration on sending
delivery.dropped.no_localIntegerNumber of messages that were dropped due to the No Local subscription option when sending
delivery.droppedIntegerTotal number of discarded messages when sending
messages.delayedIntegerNumber of delay- published messages stored by EMQ X Broker
messages.deliveredIntegerNumber of messages forwarded to the subscription process internally by EMQ X Broker
messages.droppedIntegerTotal number of messages dropped by EMQ X Broker before forwarding to the subscription process
messages.dropped.expiredIntegerNumber of messages dropped due to message expiration when receiving
messages.dropped.no_subscribersIntegerNumber of messages dropped due to no subscribers
messages.forwardIntegerNumber of messages forwarded to other nodes
messages.publishIntegerNumber of messages published in addition to system messages
messages.qos0.receivedIntegerNumber of QoS 0 messages received from clients
messages.qos2.receivedIntegerNumber of QoS 1 messages received from clients
messages.qos1.receivedIntegerNumber of QoS 2 messages received from clients
messages.qos0.sentIntegerNumber of QoS 0 messages sent to clients
messages.qos1.sentIntegerNumber of QoS 1 messages sent to clients
messages.qos2.sentIntegerNumber of QoS 2 messages sent to clients
messages.receivedIntegerNumber of messages received from the client, equal to the sum of messages.qos0.receivedmessages.qos1.received and messages.qos2.received
messages.sentIntegerNumber of messages sent to the client, equal to the sum of messages.qos0.sentmessages.qos1.sent and messages.qos2.sent
messages.retainedIntegerNumber of retained messages stored by EMQ X Broker
messages.ackedIntegerNumber of received PUBACK and PUBREC packet
packets.receivedIntegerNumber of received packet
packets.sentIntegerNumber of sent packet
packets.connect.receivedIntegerNumber of received CONNECT packet
packets.connack.auth_errorIntegerNumber of received CONNECT packet with failed authentication
packets.connack.errorIntegerNumber of received CONNECT packet with unsuccessful connections
packets.connack.sentIntegerNumber of sent CONNACK packet
packets.publish.receivedIntegerNumber of received PUBLISH packet
packets.publish.sentIntegerNumber of sent PUBLISH packet
packets.publish.inuseIntegerNumber of received PUBLISH packet with occupied identifiers
packets.publish.auth_errorIntegerNumber of received PUBLISH packets with failed the ACL check
packets.publish.errorIntegerNumber of received PUBLISH packet that cannot be published
packets.publish.droppedIntegerNumber of messages discarded due to the receiving limit
packets.puback.receivedIntegerNumber of received PUBACK packet
packets.puback.sentIntegerNumber of sent PUBACK packet
packets.puback.inuseIntegerNumber of received PUBACK packet with occupied identifiers
packets.puback.missedIntegerNumber of received packet with identifiers.
packets.pubrec.receivedIntegerNumber of received PUBREC packet
packets.pubrec.sentIntegerNumber of sent PUBREC packet
packets.pubrec.inuseIntegerNumber of received PUBREC packet with occupied identifiers
packets.pubrec.missedIntegerNumber of received PUBREC packet with unknown identifiers
packets.pubrel.receivedIntegerNumber of received PUBREL packet
packets.pubrel.sentIntegerNumber of sent PUBREL packet
packets.pubrel.missedIntegerNumber of received PUBREC packet with unknown identifiers
packets.pubcomp.receivedIntegerNumber of received PUBCOMP packet
packets.pubcomp.sentIntegerNumber of sent PUBCOMP packet
packets.pubcomp.inuseIntegerNumber of received PUBCOMP packet with occupied identifiers
packets.pubcomp.missedIntegerNumber of missed PUBCOMP packet
packets.subscribe.receivedIntegerNumber of received SUBSCRIBE packet
packets.subscribe.errorIntegerNumber of received SUBSCRIBE packet with failed subscriptions
packets.subscribe.auth_errorIntegerNumber of received SUBACK packet with failed ACL check
packets.suback.sentIntegerNumber of sent SUBACK packet
packets.unsubscribe.receivedIntegerNumber of received UNSUBSCRIBE packet
packets.unsubscribe.errorIntegerNumber of received UNSUBSCRIBE packet with failed unsubscriptions
packets.unsuback.sentIntegerNumber of sent UNSUBACK packet
packets.pingreq.receivedIntegerNumber of received PINGREQ packet
packets.pingresp.sentIntegerNumber of sent PUBRESP packet
packets.disconnect.receivedIntegerNumber of received DISCONNECT packet
packets.disconnect.sentIntegerNumber of sent DISCONNECT packet
packets.auth.receivedIntegerNumber of received AUTH packet
packets.auth.sentIntegerNumber of sent AUTH packet
rules.matchedIntegerNumber of rule matched
session.createdIntegerNumber of sessions created
session.discardedIntegerNumber of sessions dropped because Clean Session or Clean Start is true
session.resumedIntegerNumber of sessions resumed because Clean Session or Clean Start is false
session.takeoveredIntegerNumber of sessions takeovered because Clean Session or Clean Start is false
session.terminatedIntegerNumber of terminated sessions

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/metrics"

{"data":[{"node":"emqx@127.0.0.1","metrics":{"messages.dropped.no_subscribers":0,"packets.connack.sent":13,"bytes.received":805,"messages.received":0,"packets.unsuback.sent":0,"messages.delivered":0,"client.disconnected":0,"packets.puback.sent":0,"packets.subscribe.auth_error":0,"delivery.dropped.queue_full":0,"messages.forward":0,"delivery.dropped.qos0_msg":0,"delivery.dropped.expired":0,"bytes.sent":52,"messages.sent":0,"delivery.dropped.no_local":0,"packets.pubrec.received":0,"packets.pubcomp.received":0,"client.check_acl":0,"packets.puback.received":0,"session.takeovered":0,"messages.dropped.expired":0,"actions.success":0,"messages.qos1.sent":0,"messages.retained":0,"packets.pubcomp.inuse":0,"packets.pubrec.sent":0,"packets.received":13,"messages.acked":0,"session.terminated":0,"packets.sent":13,"packets.unsubscribe.error":0,"client.connect":13,"packets.pubrec.missed":0,"packets.auth.sent":0,"packets.disconnect.received":0,"messages.qos2.sent":0,"client.auth.anonymous":13,"packets.auth.received":0,"packets.unsubscribe.received":0,"packets.publish.auth_error":0,"client.connected":13,"rules.matched":0,"packets.disconnect.sent":0,"session.created":13,"packets.pingreq.received":0,"messages.dropped":0,"actions.failure":0,"packets.publish.sent":0,"session.resumed":0,"packets.connack.auth_error":0,"packets.pubrel.sent":0,"delivery.dropped":0,"packets.pubcomp.sent":0,"messages.qos2.received":0,"messages.qos0.received":0,"packets.publish.inuse":0,"client.unsubscribe":0,"packets.pubrel.received":0,"client.connack":13,"packets.connack.error":0,"packets.publish.dropped":0,"packets.publish.received":0,"client.subscribe":0,"packets.subscribe.error":0,"packets.suback.sent":0,"packets.pubcomp.missed":0,"messages.qos1.received":0,"delivery.dropped.too_large":0,"packets.pingresp.sent":0,"packets.pubrel.missed":0,"messages.qos0.sent":0,"packets.connect.received":13,"packets.puback.missed":0,"packets.subscribe.received":0,"packets.puback.inuse":0,"client.authenticate":13,"messages.publish":0,"packets.pubrec.inuse":0,"packets.publish.error":0,"messages.delayed":0,"session.discarded":0}}],"code":0}

# Get all monitoring indicator data under the specified node

GET /nodes/{node}/metrics

URL Path Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectList of statistical metrics on each node, see GET /api/metrics (opens new window) for details

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/metrics"

{"data":{"bytes.received":0,"client.connected":0,"packets.pingreq.received":0,"messages.delayed":0,"rules.matched":0,"actions.failure":0,"packets.puback.sent":0,"packets.pingresp.sent":0,"packets.publish.auth_error":0,"client.check_acl":0,"delivery.dropped.queue_full":0,"actions.success":0,"packets.publish.error":0,"packets.pubcomp.received":0,"bytes.sent":0,"packets.pubrec.inuse":0,"packets.pubrec.missed":0,"packets.pubrel.sent":0,"delivery.dropped.too_large":0,"packets.pubcomp.missed":0,"packets.subscribe.error":0,"packets.suback.sent":0,"messages.qos2.sent":0,"messages.qos1.sent":0,"packets.pubrel.missed":0,"messages.publish":0,"messages.forward":0,"packets.auth.received":0,"delivery.dropped":0,"packets.sent":0,"packets.puback.inuse":0,"delivery.dropped.qos0_msg":0,"packets.publish.dropped":0,"packets.disconnect.sent":0,"packets.auth.sent":0,"packets.unsubscribe.received":0,"session.takeovered":0,"messages.delivered":0,"client.auth.anonymous":0,"packets.connack.error":0,"packets.connack.sent":0,"packets.subscribe.auth_error":0,"packets.unsuback.sent":0,"packets.pubcomp.sent":0,"packets.publish.sent":0,"client.connack":0,"packets.publish.received":0,"client.subscribe":0,"session.created":0,"delivery.dropped.expired":0,"client.unsubscribe":0,"packets.received":0,"packets.pubrel.received":0,"packets.unsubscribe.error":0,"messages.qos0.sent":0,"packets.connack.auth_error":0,"session.resumed":0,"delivery.dropped.no_local":0,"packets.puback.missed":0,"packets.pubcomp.inuse":0,"packets.pubrec.sent":0,"messages.dropped.expired":0,"messages.dropped.no_subscribers":0,"session.discarded":0,"messages.sent":0,"messages.received":0,"packets.puback.received":0,"messages.qos0.received":0,"messages.acked":0,"client.connect":0,"packets.disconnect.received":0,"client.disconnected":0,"messages.retained":3,"session.terminated":0,"packets.publish.inuse":0,"packets.pubrec.received":0,"messages.qos2.received":0,"messages.dropped":0,"packets.connect.received":0,"client.authenticate":0,"packets.subscribe.received":0,"messages.qos1.received":0},"code":0}

# Status

# Get all status data in the cluster

GET /stats

URL Path Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsList of status data on each node
data[0].nodeStringNode name
data[0].statsArrayStatus data, see stats below

stats:

NameTypeDescription
connections.countIntegerNumber of current connections
connections.maxIntegerHistorical maximum number of connections
channels.countIntegersessions.count
channels.maxIntegersession.max
sessions.countIntegerNumber of current sessions
sessions.maxIntegerHistorical maximum number of sessions
topics.countIntegerNumber of current topics
topics.maxIntegerHistorical maximum number of topics
suboptions.countIntegersubscriptions.count
suboptions.maxIntegersubscriptions.max
subscribers.countIntegerNumber of current subscribers
subscribers.maxIntegerHistorical maximum number of subscribers
subscriptions.countIntegerNumber of current subscriptions, including shared subscriptions
subscriptions.maxIntegerHistorical maximum number of subscriptions
subscriptions.shared.countIntegerNumber of current shared subscriptions
subscriptions.shared.maxIntegerHistorical maximum number of shared subscriptions
routes.countIntegerNumber of current routes
routes.maxIntegerHistorical maximum number of routes
retained.countIntegerNumber of currently retained messages
retained.maxIntegerHistorical maximum number of retained messages

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/stats"

{"data":[{"stats":{"topics.max":0,"topics.count":0,"subscriptions.shared.max":0,"subscriptions.shared.count":0,"subscriptions.max":0,"subscriptions.count":0,"subscribers.max":0,"subscribers.count":0,"suboptions.max":0,"suboptions.count":0,"sessions.max":0,"sessions.count":0,"rules.max":0,"rules.count":0,"routes.max":0,"routes.count":0,"retained.max":3,"retained.count":3,"resources.max":0,"resources.count":0,"connections.max":0,"connections.count":0,"channels.max":0,"channels.count":0,"actions.max":5,"actions.count":5},"node":"emqx@127.0.0.1"}],"code":0}

# Get the status data on the specified node

GET /nodes/{node}/stats

URL Path Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsList of status data on each node, see GET /api/stats (opens new window) for details.

Examples:

$ curl -i --basic -u j11c5ff1:qc47fd11fccf1644 -X GET "https://lacd0b7b.test-cn.emqx.cloud:8443/api/nodes/emqx@127.0.0.1/stats"

{"data":{"topics.max":0,"topics.count":0,"subscriptions.shared.max":0,"subscriptions.shared.count":0,"subscriptions.max":0,"subscriptions.count":0,"subscribers.max":0,"subscribers.count":0,"suboptions.max":0,"suboptions.count":0,"sessions.max":0,"sessions.count":0,"rules.max":0,"rules.count":0,"routes.max":0,"routes.count":0,"retained.max":3,"retained.count":3,"resources.max":0,"resources.count":0,"connections.max":0,"connections.count":0,"channels.max":0,"channels.count":0,"actions.max":5,"actions.count":5},"code":0}

# Rule

Query rule engine actions.

# Get the details of a rule

GET /rules/{rule_id}

URL Path Parameters:

NameTypeRequiredDescription
rule_idStringFalseOptional, Rule ID. If rule_id is not specified then returns all created rules in an array

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectRule object
- data.idStringRule ID
- data.rawsqlStringSQL statement, consistent with rawsql in the request
- data.forStringTopic list, indicates which topics can be matched by this rule
- data.metricsArrayMetrics, see Rule Metrics on Dashboard for details
- data.descriptionStringThe description of the rule, consistent with the description in the request
- data.actionsArrayAction list
- data.actions[0].idStringAction ID
- data.actions[0].paramsObjectAction parameters, consistent with actions.params in the request
- data.actions[0].nameStringAction name, consistent with actions.name in the request
- data.actions[0].metricsArrayMetrics, see Rule Metrics on Dashboard for details

# Create a rule

POST /rules

Request message element (json):

NameTypeRequiredDescription
rawsqlStringTrueSQL statements of rules
actionsArrayTrueAction list
- actions[0].nameStringTrueAction name
- actions[0].paramsObjectTrueAction parameters, that is expressed in key-value form. For details, please refer to the example of adding rules
descriptionStringFalseOptional, rule description

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectSuccessfully created rule object with Rule ID
- data.idStringRule ID
- data.rawsqlStringSQL statement, consistent with rawsql in the request
- data.forStringTopic list, indicates which topics can be matched by this rule
- data.metricsArrayMetrics, see Rule Metrics on Dashboard for details
- data.descriptionStringThe description of the rule, consistent with the description in the request
- data.actionsArrayAction list, and each action is an Object
- data.actions[0].idStringAction ID
- data.actions[0].paramsObjectAction parameters, consistent with actions.params in the request
- data.actions[0].nameStringAction name, consistent with actions.name in the request
- data.actions[0].metricsArrayMetrics, see Rule Metrics on Dashboard for details

# Update the rule

PUT /rules/{rule_id}

Request message element (json):

NameTypeRequiredDescription
rawsqlStringTrueOptional, SQL statement of the rule
actionsArrayTrueOptional, action list
- actions[0].nameStringTrueOptional, action name
- actions[0].paramsObjectTrueOptional, action parameters, that is expressed in key-value form. For details, please refer to the example of adding rules
descriptionStringFalseOptional, rule description

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectSuccessfully created rule object with Rule ID
- data.idStringRule ID
- data.rawsqlStringSQL statement, consistent with rawsql in the request
- data.forStringTopic list, indicates which topics can be matched by this rule
- data.metricsArrayMetrics, see Rule Metrics on Dashboard for details
- data.descriptionStringThe description of the rule, consistent with the description in the request
- data.actionsArrayAction list, and each action is an Object
- data.actions[0].idStringAction ID
- data.actions[0].paramsObjectAction parameters, consistent with actions.params in the request
- data.actions[0].nameStringAction name, consistent with actions.name in the request
- data.actions[0].metricsArrayMetrics, see Rule Metrics on Dashboard for details

# Delete the rule

DELETE /rules/{rule_id}

Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Add a rule to print the rule running parameters for all messages matching the topic "t/a".。

$ curl -XPOST -d '{
  "rawsql": "select * from \"t/a\"",
  "actions": [{
      "name": "inspect",
      "params": {
          "a": 1
      }
  }],
  "description": "test-rule"
}' --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules'

{"data":{"rawsql":"select * from \"t/a\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}

Use the rule ID to get the details of the rule just created:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e'

{"data":{"rawsql":"select * from \"t/a\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}

Get all the rules. Note that the data in the returned value is an array of rule objects:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules'

{"data":[{"rawsql":"select * from \"t/a\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]}],"code":0}

Update the SQL statement of the rule to select * from "t/b":

$ curl -XPUT --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e' -d '{"rawsql":"select * from \"t/b\""}'

{"data":{"rawsql":"select * from \"t/b\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":true,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}

Disable the rule:

$ curl -XPUT --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e' -d '{"enabled": false}'

{"data":{"rawsql":"select * from \"t/b\"","metrics":[{"speed_max":0,"speed_last5m":0.0,"speed":0.0,"node":"emqx@127.0.0.1","matched":0}],"id":"rule:7fdb2c9e","for":["t/a"],"enabled":false,"description":"test-rule","actions":[{"params":{"a":1},"name":"inspect","metrics":[{"success":0,"node":"emqx@127.0.0.1","failed":0}],"id":"inspect_1582434715354188116"}]},"code":0}

Delete the rule:

$ curl -XDELETE --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/rules/rule:7fdb2c9e'

{"code":0}

# Action

Query the actions of the rule engine. Note that actions can only be provided by emqx and cannot be added.

# Get the details of an action

GET /actions/{action_name}

URL Path Parameters:

NameTypeRequiredDescription
action_nameStringFalseOptional, the action name. If you do not specify action_name then return all currently supported actions in an array.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectRule object
- data.typesStringIndicate which resource types the current action belongs to
- data.titleObjectA brief description of the action, in both English and Chinese.
- data.paramsObjectA list of parameters for the action that are expressed in key-value form. For details, please refer to the following examples
-data.descriptionObjectA brief description of the action, in both English and Chinese.
- data.appStringAction Provider

Examples:

Query the details of the inspect action:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/actions/inspect'

{"data":{"types":[],"title":{"zh":"检查 (调试)","en":"Inspect (debug)"},"params":{},"name":"inspect","for":"$any","description":{"zh":"检查动作参数 (用以调试)","en":"Inspect the details of action params for debug purpose"},"app":"emqx_rule_engine"},"code":0}

Query all current actions:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/actions'

{"data":[{"types":[],"title":{"zh":"空动作 (调试)","en":"Do Nothing (debug)"},"params":{},"name":"do_nothing","for":"$any","description":{"zh":"此动作什么都不做,并且不会失败 (用以调试)","en":"This action does nothing and never fails. It's for debug purpose"},"app":"emqx_rule_engine"}, ...],"code":0}

# Resource Type

Query the rule engine's resource type. Note that resource types can only be provided by emqx and cannot be added

# Get the details of an action

GET /resource_types/{resource_type_name}

URL Path Parameters:

NameTypeRequiredDescription
resource_type_nameStringFalseOptional, resource type name. If resource_type_name is not specified, all currently supported resource types will be returned as an array.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectRule object
- data.titleObjectA brief description of resource types, in both English and Chinese.
- data.paramsObjectA list of parameters for the resource type expressed in key-value form. For details, please refer to the following examples
- data.descriptionObjectA brief description of resource types, in both English and Chinese.
- data.providerStringProvider of resource type

Examples:

Query details for the web_hook resource type:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resource_types/web_hook'

{"data":{"title":{"zh":"WebHook","en":"WebHook"},"provider":"emqx_web_hook","params":{"url":{"type":"string","title":{"zh":"请求 URL","en":"Request URL"},"required":true,"format":"url","description":{"zh":"请求 URL","en":"Request URL"}},"method":{"type":"string","title":{"zh":"请求方法","en":"Request Method"},"enum":["PUT","POST"],"description":{"zh":"请求方法","en":"Request Method"},"default":"POST"},"headers":{"type":"object","title":{"zh":"请求头","en":"Request Header"},"schema":{},"description":{"zh":"请求头","en":"Request Header"},"default":{}}},"name":"web_hook","description":{"zh":"WebHook","en":"WebHook"}},"code":0}

Query all current resource types:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resource_types'

{"data":[{"title":{"zh":"WebHook","en":"WebHook"},"provider":"emqx_web_hook","params":{"url":{"type":"string","title":{"zh":"请求 URL","en":"Request URL"},"required":true,"format":"url","description":{"zh":"请求 URL","en":"Request URL"}},"method":{"type":"string","title":{"zh":"请求方法","en":"Request Method"},"enum":["PUT","POST"],"description":{"zh":"请求方法","en":"Request Method"},"default":"POST"},"headers":{"type":"object","title":{"zh":"请求头","en":"Request Header"},"schema":{},"description":{"zh":"请求头","en":"Request Header"},"default":{}}},"name":"web_hook","description":{"zh":"WebHook","en":"WebHook"}}, ...],"code":0}

# Resource

Manage the resources of the rules engine. A resource is an instance of a resource type and is used to maintain related resources such as database connections.

# Gets the details of the specified resource

GET /resources/{resource_id}

URL Path Parameters:

NameTypeRequiredDescription
resource_idStringFalseOptional, the resource ID. If not specified then returns all the currently supported resource in an array.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectRule object
- data.idStringRule ID
- data.typeStringThe name of the resource type to which the resource belongs
- data.configObjectConfiguration of resources, and parameters are expressed in key-value form. For details, please refer to the following examples
- data.statusArrayStatus information for the resource. See the status of resources on the Dashboard for details.
- data.descriptionObjectA description of the resource, in both English and Chinese.

# Get all resource information

POST /resources

Request message element (json):

NameTypeRequiredDescription
typeStringTrueResource type name that specify which resource type to use to create the resource
configObjectTrueResource parameters that should conform to the format specified in the params of the corresponding resource type.
descriptionStringFalseOptional, resource description

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjectRule object
- data.idStringResource ID
- data.typeStringThe name of the resource type to which the resource belongs
- data.configObjectConfiguration of resources, and parameters are expressed in key-value form. For details, please refer to the following examples
- data.descriptionObjectA description of the resource, in both English and Chinese.

# Delete the resource

DELETE /resources/{resource_id}

Parameters: None

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Create a webhook resource with the URL of the webserver http://127.0.0.1:9910 (opens new window)

$ curl -XPOST -d '{
  "type": "web_hook",
  "config": {
      "url": "http://127.0.0.1:9910",
      "headers": {"token":"axfw34y235wrq234t4ersgw4t"},
      "method": "POST"
  },
  "description": "web hook resource-1"
}' --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources'

{"data":{"type":"web_hook","id":"resource:b12d3e44","description":"web hook resource-1","config":{"url":"http://127.0.0.1:9910","method":"POST","headers":{"token":"axfw34y235wrq234t4ersgw4t"}}},"code":0}

Query the resource you just created using the resource ID:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources/resource:b12d3e44'

{"data":{"type":"web_hook","status":[{"node":"emqx@127.0.0.1","is_alive":false}],"id":"resource:b12d3e44","description":"web hook resource-1","config":{"url":"http://127.0.0.1:9910","method":"POST","headers":{"token":"axfw34y235wrq234t4ersgw4t"}}},"code":0}

Query all resources that was currently created:

$ curl --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources'

{"data":[{"type":"web_hook","id":"resource:b12d3e44","description":"web hook resource-1","config":{"url":"http://127.0.0.1:9910","method":"POST","headers":{"token":"axfw34y235wrq234t4ersgw4t"}}}],"code":0}

Delete the resources:

$ curl -XDELETE --basic -u j11c5ff1:qc47fd11fccf1644 'https://lacd0b7b.test-cn.emqx.cloud:8443/api/resources/resource:b12d3e44'

{"code":0}