HTTP API

HTTP API

EMQX Broker provides HTTP APIs for integration with external systems, such as querying client information, publishing messages, and creating rules.

EMQX Broker’s HTTP API service listens on port 8081 by default. You can modify the listening port through the configuration file of etc/plugins/emqx_management.conf, or enable HTTPS listening. All API calls start with api/v4 after EMQX Broker 4.0.0 HTTP API - 图1 (opens new window).

Interface security

EMQX Broker’s HTTP API uses the method of Basic Authentication HTTP API - 图2 (opens new window). The id and password must be filled with AppID and AppSecret respectively. The default AppID and AppSecret are: admin/public. You can modify and add AppID / AppSecret in the left menu bar of Dashboard by selecting “Manage”-> “Apps”.

Response code

HTTP status codes

The EMQX 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 Code Description
200 Succeed, and the returned JSON data will provide more information
400 Invalid client request, such as wrong request body or parameters
401 Client authentication failed , maybe because of invalid authentication credentials
404 The requested path cannot be found or the requested object does not exist
500 An internal error occurred while the server was processing the request

result codes

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

The possible returned codes are as follows:

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

API Endpoints

Health check

GET /status

Serves as a health check for the node. Returns a plain text response describing the status of the node. This endpoint requires no authentication.

Returns status code 200 if the EMQX application is up and running, 503 otherwise.

Examples:

Application is running:

$ curl "http://localhost:8081/status"

Node emqx@127.0.0.1 is started
emqx is running

When EMQX application is restarting during boot up, or during restart due to join/leave cluster:

$ curl "http://localhost:8081/status"

Node emqx@127.0.0.1 is started
emqx is not_running

/api/v4

GET /api/v4

Return all Endpoints supported by EMQX Broker.

Parameters: None

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array Endpoints list
- data[0].path String Endpoint
- data[0].name String Endpoint name
- data[0].method String HTTP Method
- data[0].descr String Description

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4"

{"data":[{"path":"/auth_clientid","name":"list_clientid","method":"GET","descr":"List available clientid in the cluster"}, ...],"code":0}

Broker Basic Information

GET /api/v4/brokers/{node}

Return basic information of all nodes in the cluster.

Path Parameters:

Name Type Required Description
node String False Node name, such as “emqx@127.0.0.1.
If not specified, returns all node information

Success Response Body (JSON):

Name Type Description
code Integer 0
data Object/Array of Objects Returns the information of the specified node when the parameter exists,
otherwise, returns the information of all nodes
data.datetime String Current time, in the format of “YYYY-MM-DD HH: mm: ss”
data.node String Node name
data.node_status String Node status
data.otp_release String Erlang/OTP version used by EMQX Broker
data.sysdescr String Software description
data.uptime String EMQX Broker runtime, in the format of “H hours, m minutes, s seconds”
data.version String EMQX Broker version

Examples:

Get the basic information of all nodes:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers"

{"data":[{"version":"develop","uptime":"4 hours, 21 minutes, 19 seconds","sysdescr":"EMQX 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 admin:public -X GET "http://localhost:8081/api/v4/brokers/emqx@127.0.0.1"

{"data":{"version":"develop","uptime":"1 minutes, 51 seconds","sysdescr":"EMQX 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 /api/v4/nodes/{node}

Return the status of the node.

Path Parameters:

Name Type Required Description
node String False Node name, such as “emqx@127.0.0.1。
If not specified, returns all node information

Success Response Body (JSON):

Name Type Description
code Integer 0
data Object/Array of Objects Returns node information when node parameter exists,
otherwise, returns information about all nodes in an Array
data.connections Integer Number of clients currently connected to this node
data.load1 String CPU average load in 1 minute
data.load5 String CPU average load in 5 minute
data.load15 String CPU average load in 15 minute
data.max_fds Integer Maximum file descriptor limit for the operating system
data.memory_total String VM allocated system memory
data.memory_used String VM occupied system memory
data.node String Node name
data.node_status String Node status
data.otp_release String Erlang/OTP version used by EMQX Broker
data.process_available Integer Number of available processes
data.process_used Integer Number of used processes
data.uptime String EMQX Broker runtime
data.version String EMQX Broker version

Examples:

Get the status of all nodes:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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 admin:public -X GET "http://localhost:8081/api/v4/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}

Client

GET /api/v4/clients

Returns the information of all clients under the cluster, and supports paging.

Query String Parameters:

Name Type Required Default Description
_page Integer False 1 Page
_limit Integer False 10000 The 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.

Name Type Required Description
clientid String False Client identifier
username String False Client username
zone String False Client configuration group name
ip_address String False Client IP address
conn_state Enum False The current connection status of the client, the possible values areconnected,idle,disconnected
clean_start Bool False Whether the client uses a new session
proto_name Enum False Client protocol name, the possible values areMQTT,CoAP,LwM2M,MQTT-SN
proto_ver Integer False Client protocol version
_like_clientid String False Fuzzy search of client identifier by substring method
_like_username String False Client user name, fuzzy search by substring
_gte_created_at Integer False Search client session creation time by greater than or equal method
_lte_created_at Integer False Search client session creation time by less than or equal method
_gte_connected_at Integer False Search client connection creation time by greater than or equal method
_lte_connected_at Integer False Search client connection creation time by less than or equal method
_gte_mqueue_len Integer False Current length of message queue by greater than or equal method
_lte_mqueue_len Integer False Current length of message queue by less than or equal method
_gte_mqueue_dropped Integer False Number of messages dropped by the message queue due to exceeding the length by greater than or equal method ｜
_lte_mqueue_dropped Integer False Number of messages dropped by the message queue due to exceeding the length by less than or equal method｜

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects Information for all clients
data[0].node String Name of the node to which the client is connected
data[0].clientid String Client identifier
data[0].username String User name of client when connecting
data[0].proto_name String Client protocol name
data[0].proto_ver Integer Protocol version used by the client
data[0].ip_address String Client’s IP address
data[0].port Integer Client port
data[0].is_bridge Boolean Indicates whether the client is connected via bridge
data[0].connected_at String Client connection time, in the format of “YYYY-MM-DD HH:mm:ss”
data[0].disconnected_at String Client offline time, in the formatof “YYYY-MM-DD HH:mm:ss”，
This field is only valid and returned when connected isfalse
data[0].connected Boolean Whether the client is connected
data[0].zone String Indicate the configuration group used by the client
data[0].keepalive Integer keepalive time, with the unit of second
data[0].clean_start Boolean Indicate whether the client is using a brand new session
data[0].expiry_interval Integer Session expiration interval, with the unit of second
data[0].created_at String Session creation time, in the format “YYYY-MM-DD HH:mm:ss”
data[0].subscriptions_cnt Integer Number of subscriptions established by this client
data[0].max_subscriptions Integer Maximum number of subscriptions allowed by this client
data[0].inflight Integer Current length of inflight
data[0].max_inflight Integer Maximum length of inflight
data[0].mqueue_len Integer Current length of message queue
data[0].max_mqueue Integer Maximum length of message queue
data[0].mqueue_dropped Integer Number of messages dropped by the message queue due to exceeding the length
data[0].awaiting_rel Integer Number of awaiting PUBREC packet
data[0].max_awaiting_rel Integer Maximum allowed number of awaiting PUBREC packet
data[0].recv_oct Integer Number of bytes received by EMQX Broker (the same below)
data[0].recv_cnt Integer Number of TCP packets received
data[0].recv_pkt Integer Number of MQTT packets received
data[0].recv_msg Integer Number of PUBLISH packets received
data[0].send_oct Integer Number of bytes sent
data[0].send_cnt Integer Number of TCP packets sent
data[0].send_pkt Integer Number of MQTT packets sent
data[0].send_msg Integer Number of PUBLISH packets sent
data[0].mailbox_len Integer Process mailbox size
data[0].heap_size Integer Process heap size with the unit of byte
data[0].reductions Integer Erlang reduction
meta Object Paging information
meta.page Integer Page number
meta.limit Integer Number of data displayed per page
meta.count Integer Total number of data

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

Note: After 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 /api/v4/clients/{clientid}

Returns information for the specified client

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects Client information, for details, see
GET /api/v4/clients

Examples:

Query the specified client

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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 /api/v4/clients/{clientid}

Kick out the specified client. Note that this operation will terminate the connection with the session.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

Kick out the specified client

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/clients/example"

{"code":0}

GET /api/v4/nodes/{node}/clients

similar with GET /api/v4/clients, Returns information about all clients under the specified node, and supports paging.

Query String Parameters:

Name Type Required Default Description
_page Integer False 1 page number
_limit Integer False 10000 The 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):

Name Type Description
code Integer 0
data Array of Objects Information about all clients, see GET /api/v4/clients for details

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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 /api/v4/nodes/{node}/clients/{clientid}

Similar with GET /api/v4/clients/{clientid}，return information about the specified client under the specified node.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0
data Object Information about all clients, for details, see
GET /api/v4/clients

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

DELETE /api/v4/nodes/{node}/clients/{clientid}

Similar with DELETE /api/v4/clients/{clientid}，kick out the specified client under the specified node.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/example"

{"code":0}

GET /api/v4/clients/username/{username}

Query client information by Username. Since there may be multiple clients using the same user name, multiple client information may be returned at the same time.

Path Parameters:

Name Type Required Description
username String True Username

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects Information about clients, for details, see
GET /api/v4/clients

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

Similar with GET /api/v4/clients/username/{username}, query the information of the specified client through Username under the specified node.

Path Parameters:

Name Type Required Description
username String True Username

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects Information about clients, for details, see
GET /api/v4/clients

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

GET /api/v4/clients/{clientid}/acl_cache

Query the ACL cache of the specified client.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects ACL Details
data[0].access String Publish/Scribe
data[0].topic String MQTT Topic
data[0].result String Allow/Deny
data[0].updated_time Integer ACL Cache settling time

Examples:

Querying the ACL cache

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/example/acl_cache"

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

DELETE /api/v4/clients/{clientid}/acl_cache

Delete the ACL cache of the specified client。

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

Delete the ACL cache

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/clients/example/acl_cache"

{"code":0}

PUT /api/v4/clients/{clientid}/keepalive

Set the keepalive time (in seconds) for the specified client.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Query String Parameters:

Name Type Required Description
interval Integer True seconds：0～65535，0 means keepalive check is disable

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

Update the specified client(example) Keepalive to 10 seconds

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/clients/example/keepalive?interval=10"

{"code":0}

In addition to the above Query String, we also support passing through Body.

curl   -u admin:public -X 'PUT' http://127.0.0.1:18083/api/v4/clients/test/keepalive -d '{"interval": 10}'

{"code":0}

Subscription Information

GET /api/v4/subscriptions

Returns all subscription information under the cluster, and supports paging mechanism

Query String Parameters:

Name Type Required Default Description
_page Integer False 1 Page number
_limit Integer False 10000 The 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:

Name Type Description
clientid String Client identifier
topic String congruent query
qos Enum Possible values are 0,1,2`
share String Shared subscription group name
_match_topic String Match query

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects All subscription information
data[0].node String Node name
data[0].clientid String Client identifier
data[0].topic String Subscribe to topic
data[0].qos Integer QoS level
meta Object same as /api/v4/clients

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

Note: 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 /api/v4/subscriptions/{clientid}

Return the subscription information of the specified client in the cluster.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0
data Object All subscription information
data.node String Node name
data.clientid String Client identifier
data.topic String Subscribe to topic
data.qos Integer QoS level

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions/123"

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

GET /api/v4/nodes/{node}/subscriptions

Similar with GET /api/v4/subscriptions，returns all subscription information under the specified node, and supports paging mechanism.

Query String Parameters:

Name Type Required Default Description
_page Integer False 1 Page number
_limit Integer False 10000 The 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):

Name Type Description
code Integer 0
data Array of Objects All subscription information
data[0].node String Node name
data[0].clientid String Client identifier
data[0].topic String Subscribe to topic
data[0].qos Integer QoS level
meta Object Same as /api/v4/clients

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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}

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

Similar with GET /api/v4/subscriptions/{clientid}, query all subscription information of a clientid under the specified node, and support paging mechanism.

Path Parameters:

Name Type Required Description
clientid String True ClientID

Success Response Body (JSON):

Name Type Description
code Integer 0
data Object All subscription information
data.node String Node name
data.clientid String Client identifier
data.topic String Subscribe to topic
data.qos Integer QoS level

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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 /api/v4/routes

List all routes, support pagination.

Query String Parameters:

Name Type Required Default Description
_page Integer False 1 page
_limit Integer False 10000 Page size,default use emqx-management max_row_limit option

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects routes
data[0].topic String MQTT Topic
data[0].node String Node name
meta Object see /api/v4/clients

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/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 /api/v4/routes/{topic}

List all routes of a topic.

Path Parameters:

Name Type Required Description
topic Integer True Topic

Success Response Body (JSON):

Name Type Description
code Integer 0
data Object All routes information
data.topic String MQTT Topic
data.node String Node name

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/routes/a%2fb%2fc"

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

Publish message

POST /api/v4/mqtt/publish

Publish MQTT message。

Parameters (json):

Name Type Required Default Description
topic String Optional For topic and topics, with at least one of them specified
topics String Optional Multiple topics separated by ,. This field is used to publish messages to multiple topics at the same time
clientid String Required Client identifier
payload String Required Message body
encoding String Optional plain The encoding used in the message body. Currently only plain and base64 are supported.
qos Integer Optional 0 QoS level
retain Boolean Optional false Whether it is a retained message
properties Object Optional {} The Properties of the PUBLISH message

Properties：

Name Type Description｜
payload_format_indicator Integer 0 (0x00) Byte Indicates that the Payload is unspecified bytes, which is equivalent to not sending a Payload Format Indicator. 1 (0x01) Byte Indicates that the Payload is UTF-8 Encoded Character Data. The UTF-8 data in the Payload MUST be well-formed UTF-8 as defined by the Unicode specification and restated in RFC 3629
message_expiry_interval integer Identifier of the Message Expiry Interval. If the Message Expiry Interval has passed and the Server has not managed to start onward delivery to a matching subscriber, then it MUST delete the copy of the message for that subscriber
response_topic String Identifier of the Response Topic.The Response Topic MUST be a UTF-8 Encoded, It MUST NOT contain wildcard characters.
correlation_data String Identifier of the Correlation Data. The Server MUST send the Correlation Data unaltered to all subscribers receiving the Application Message
subscription_identifier Integer Identifier of the Subscription Identifier. It can have the value of 1 to 268,435,455. It is a Protocol Error if the Subscription Identifier has a value of 0. Multiple Subscription Identifiers will be included if the publication
is the result of a match to more than one subscription, in this case their order is not significant.
content_type String The Content Type MUST be a UTF-8 Encoded String
user_properties Object Identifier of the User Property. The Server send all User Properties unaltered in a PUBLISH packet when forwarding the Application Message to a Client

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish" -d \
'{"topic":"a/b/c", "payload":"Hello World", "qos":1, "retain":false, "clientid":"example", "properties": {"user_properties": { "id": 10010, "name": "emqx", "foo": "bar"}, "content_type": "text/plain"}}'

{"code":0}

Subscribe to topic

POST /api/v4/mqtt/subscribe

Subscribe to MQTT topic

Parameters (json):

Name Type Required Default Description
topic String Optional For topic and topics, with at least one of them specified
topics String Optional Multiple topics separated by ,. This field is used to subscribe to multiple topics at the same time
clientid String Required Client identifier
qos Integer Optional 0 QoS level

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

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

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/subscribe" -d '{"topics":"a,b,c","qos":1,"clientid":"example"}'

{"code":0}

POST /api/v4/mqtt/unsubscribe

Unsubscribe.

Parameters (json):

Name Type Required Default Description
topic String Required Topic
clientid String Required Client identifier

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

Unsubscribe from a topic

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'

{"code":0}

Message publish in batch

POST /api/v4/mqtt/publish_batch

Publish MQTT messages in batch.

Parameters (json):

Name Type Required Default Description
[0].topic String Optional Topic, at least one of which is specified with topics
[0].topics String Optional Multiple topics divided by ,, which can be used to publish messages to multiple topics at the same time
[0].clientid String Required Client identifier
[0].payload String Required Message body
[0].encoding String Optional plain The encoding method used in the message body, only plain and base64 are supported currently
[0].qos Integer Optional 0 QoS level
[0].retain Boolean Optional false Whether it is a retained message or not
[0].properties Object Optional {} The Properties of the PUBLISH message

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish_batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example","properties": {"user_properties":{"id": 10010, "name": "emqx", "foo": "bar"}}},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example","properties":{"user_properties": { "id": 10010, "name": "emqx", "foo": "bar"},"content_type": "text/plain"}}]'

{"data":[{"topic":"a/b/c","code":0},{"topic":"a/b/c","code":0}],"code":0}

Topic subscription in batch

POST /api/v4/mqtt/subscribe_batch

Subscribe to MQTT topics in batch.

Parameters (json):

Name Type Required Default Description
[0].topic String Optional Topic, at least one of which is specified with topics
[0].topics String Optional Multiple topics divided by ,, which can be used to publish messages to multiple topics at the same time
[0].clientid String Required Client identifier
[0].qos Integer Optional 0 QoS level

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

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

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/subscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"},{"topic":"c","qos":1,"clientid":"example"}]'

{"code":0}

POST /api/v4/mqtt/unsubscribe_batch

Unsubscribe in batch.

Parameters (json):

Name Type Required Default Description
[0].topic String Required Topic
[0].clientid String Required Client identifier

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

Unsubscribe from a,b topics at one time

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/unsubscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"}]'

{"code":0}

plugins

GET /api/v4/plugins

Returns information of all plugins in the cluster.

Path Parameters: None

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects All routes information
data[0].node String Node name
data[0].plugins Array Plugin information, an array of objects, see below
data[0].plugins.name String Plugin name
data[0].plugins.version String Plugin version
data[0].plugins.description String Plugin description
data[0].plugins.active Boolean Whether the plugin is active
data[0].plugins.type String Plug-in type, currently includes
auth、bridge、feature、protocol

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/plugins"

{"data":[{"plugins":[{"version":"develop","type":"auth","name":"emqx_auth_clientid","description":"EMQX Broker Authentication with ClientId/Password","active":false}, ...],"node":"emqx@127.0.0.1"}],"code":0}

GET /api/v4/nodes/{node}/plugins

Similar with GET /api/v4/plugins, return the plugin information under the specified node

Path Parameters: None

Success Response Body (JSON):

Name Type Description
code Integer 0
data Array of Objects All routes information
data[0].name String Plugin name
data[0].version String Plugin version
data[0].description String Plugin description
data[0].active Boolean Whether the plugin is active
data[0].type String Plug-n type, currently include
auth、bridge、feature、protocol

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins"

{"data":[{"version":"develop","type":"auth","name":"emqx_auth_clientid","description":"EMQX Broker Authentication with ClientId/Password","active":false}, ...],"code":0}

PUT /api/v4/nodes/{node}/plugins/{plugin}/load {#load_plugin}

Load the specified plugin under the specified node.

Parameters: None

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/load"

{"code":0}

PUT /api/v4/nodes/{node}/plugins/{plugin}/unload

Unload the specified plugin under the specified node.

Parameters: None

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/unload"

{"code":0}

PUT /api/v4/nodes/{node}/plugins/{plugin}/reload

Reloads the specified plugin under the specified node.

Parameters: None

Success Response Body (JSON):

Name Type Description
code Integer 0

Examples:

$ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/reload"

{"code":0}

（本文超出站点单文档体积上限，已按小节截断）