HTTP API

    EMQ X Broker’s HTTP API service listens on port 8081 by default. You can modify the listening port through the configuration file of , or enable HTTPS listening. All API calls start with api/v4 after .

    EMQ X Broker’s HTTP API uses the method of Basic Authentication HTTP API - 图1 (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”.

    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:

    result codes

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

    The possible returned 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/v4

    GET /api/v4

    Return all Endpoints supported by EMQ X Broker.

    Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArrayEndpoints list
    - data[0].pathStringEndpoint
    - data[0].nameStringEndpoint name
    - data[0].methodStringHTTP Method
    - data[0].descrStringDescription

    Examples:

    Broker Basic Information

    GET /api/v4/brokers/{node}

    Return basic information of all nodes in the cluster.

    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:

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

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers/emqx@127.0.0.1"
    3. {"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 /api/v4/nodes/{node}

    Return the status of the node.

    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:

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

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

    Client

    GET /api/v4/clients

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

    Query String 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 formatof “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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients?_page=1&_limit=10"
    3. {"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:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsClient information, for details, see

    Examples:

    Query the specified client

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

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    Kick out the specified client

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/clients/example"
    3. {"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:

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients?_page=1&_limit=10"
    3. {"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:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObjectInformation about all clients, for details, see

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/example"
    3. {"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:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/example"
    3. {"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:

    NameTypeRequiredDescription
    usernameStringTrueUsername

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsInformation about clients, for details, see

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/username/steve"
    3. {"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:

    NameTypeRequiredDescription
    usernameStringTrueUsername

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsInformation about clients, for details, see

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/clients/username/test"
    3. {"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:

    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

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/example/acl_cache"
    3. {"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:

    NameTypeRequiredDescription
    clientidStringTrueClientID

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    Delete the ACL cache

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/clients/example/acl_cache"
    3. {"code":0}

    Subscription Information

    GET /api/v4/subscriptions

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

    Query String 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_topicStringMatch 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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions?_page=1&_limit=10"
    3. {"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:

    Success Response Body (JSON):

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

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions/123"
    3. {"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:

    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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/subscriptions?_page=1&limit=10"
    3. {"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 , query all subscription information of a clientid under the specified node, and support paging mechanism.

    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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/subscriptions/sample"
    3. {"data":[{"topic":"a/+/c","qos":0,"node":"emqx@127.0.0.1","clientid":"sample"}],"code":0}

    GET /api/v4/routes

    Query String Parameters:

    NameTypeRequiredDefaultDescription
    _pageIntegerFalse1page
    _limitIntegerFalse10000Page size,default use emqx-management max_row_limit option

    Success Response Body (JSON):

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

    Examples:

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

    NameTypeRequiredDescription
    topicIntegerTrueTopic

    Success Response Body (JSON):

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

    Examples:

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

    Publish message

    POST /api/v4/mqtt/publish

    Publish MQTT message。

    Parameters (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:

    Subscribe to topic

    POST /api/v4/mqtt/subscribe

    Subscribe to MQTT topic

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

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

    POST /api/v4/mqtt/unsubscribe

    Unsubscribe.

    Parameters (json):

    NameTypeRequiredDefaultDescription
    topicStringRequiredTopic
    clientidStringRequiredClient identifier

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    Unsubscribe from a topic

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

    Message publish in batch

    POST /api/v4/mqtt/publish_batch

    Publish MQTT messages in batch.

    Parameters (json):

    NameTypeRequiredDefaultDescription
    [0].topicStringOptionalTopic, at least one of which is specified with topics
    [0].topicsStringOptionalMultiple topics divided by ,, which can be used to publish messages to multiple topics at the same time
    [0].clientidStringRequiredClient identifier
    [0].payloadStringRequiredMessage body
    [0].encodingStringOptionalplainThe encoding method used in the message body, only plain and base64 are supported currently
    [0].qosIntegerOptional0QoS level
    [0].retainBooleanOptionalfalseWhether it is a retained message or not

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ 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"},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example"}]'
    3. {"code":0}

    Topic subscription in batch

    POST /api/v4/mqtt/subscribe_batch

    Subscribe to MQTT topics in batch.

    Parameters (json):

    NameTypeRequiredDefaultDescription
    [0].topicStringOptionalTopic, at least one of which is specified with topics
    [0].topicsStringOptionalMultiple topics divided by ,, which can be used to publish messages 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, and c at one time

    1. $ 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"}]'
    3. {"code":0}

    POST /api/v4/mqtt/unsubscribe_batch

    Unsubscribe in batch.

    Parameters (json):

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

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    Unsubscribe from a,b topics at one time

    1. $ 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"}]'
    3. {"code":0}

    plugins

    GET /api/v4/plugins

    Returns information of all plugins in the cluster.

    Path Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsAll routes information
    data[0].nodeStringNode name
    data[0].pluginsArrayPlugin information, an array of objects, see below
    data[0].plugins.nameStringPlugin name
    data[0].plugins.versionStringPlugin version
    data[0].plugins.descriptionStringPlugin description
    data[0].plugins.activeBooleanWhether the plugin is active
    data[0].plugins.typeStringPlug-in type, currently includes
    auth、bridge、feature、protocol

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/plugins"
    3. {"data":[{"plugins":[{"version":"develop","type":"auth","name":"emqx_auth_clientid","description":"EMQ X 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):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsAll routes information
    data[0].nameStringPlugin name
    data[0].versionStringPlugin version
    data[0].descriptionStringPlugin description
    data[0].activeBooleanWhether the plugin is active
    data[0].typeStringPlug-n type, currently include
    auth、bridge、feature、protocol

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins"
    3. {"data":[{"version":"develop","type":"auth","name":"emqx_auth_clientid","description":"EMQ X 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):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/load"
    3. {"code":0}

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

    Unload the specified plugin under the specified node.

    Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/unload"
    3. {"code":0}

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

    Reloads the specified plugin under the specified node.

    Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/plugins/emqx_delayed_publish/reload"
    3. {"code":0}

    listeners

    GET /api/v4/listeners

    Returns information about all listeners in the cluster.

    Path Parameters: 无

    **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].identifierStringIdentifier
    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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/listeners"
    3. {"data":[{"node":"emqx@127.0.0.1","listeners":[{"shutdown_count":[],"protocol":"mqtt:ssl","max_conns":102400,"listen_on":"8883","identifier":"mqtt:ssl:external","current_conns":1,"acceptors":32},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"0.0.0.0:1883","identifier":"mqtt:tcp:external","current_conns":1,"acceptors":64},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"127.0.0.1:11883","identifier":"mqtt:tcp:internal","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":"mqtt:ws:8083","max_conns":102400,"listen_on":"8083","current_conns":0,"acceptors":16},{"shutdown_count":[],"protocol":"mqtt:wss:8084","max_conns":102400,"listen_on":"8084","current_conns":0,"acceptors":16}]}],"code":0}

    PUT /api/v4/listeners/{identifier}/restart

    Restarts a listener in the cluster

    Path Parameters: 无

    **Success Response Body (JSON):

    NameTypeDescription
    codeInteger0

    Examples:

    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/listeners/mqtt:tcp:external/restart"
    3. {"code":0}

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

    Similar with , returns the listener information for the specified node.

    **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].identifierStringIdentifier
    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:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/listeners"
    3. {"data":[{"shutdown_count":[],"protocol":"mqtt:ssl","max_conns":102400,"listen_on":"8883","identifier":"mqtt:ssl:external","current_conns":1,"acceptors":32},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"0.0.0.0:1883","identifier":"mqtt:tcp:external","current_conns":1,"acceptors":64},{"shutdown_count":[],"protocol":"mqtt:tcp","max_conns":1024000,"listen_on":"127.0.0.1:11883","identifier":"mqtt:tcp:internal","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":"mqtt:ws:8083","max_conns":102400,"listen_on":"8083","current_conns":0,"acceptors":16},{"shutdown_count":[],"protocol":"mqtt:wss:8084","max_conns":102400,"listen_on":"8084","current_conns":0,"acceptors":16}],"code":0}

    PUT /api/v4/nodes/{node}/listeners/{identifier}/restart

    Restarts a listener in the cluster

    Path Parameters: 无

    **Success Response Body (JSON):

    Examples:

    1. $ curl -i --basic -u admin:public -X PUT "http://localhost:8081/api/v4/listeners/mqtt:tcp:external/restart"

    GET /api/v4/metrics

    Returns all statistical metrics under the cluster

    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.qos1.receivedIntegerNumber of QoS 1 messages received from clients
    messages.qos2.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.received，messages.qos1.received and messages.qos2.received
    messages.sentIntegerNumber of messages sent to the client, equal to the sum of messages.qos0.sent，messages.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:

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

    Similar with GET /api/v4/metrics, returns all monitoring indicator data under the specified node.

    Path Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObjectsList of statistical metrics on each node, see for details

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/metrics"
    3. {"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 /api/v4/stats

    Return all status data in the cluster.

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

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

    Similar with GET /api/v4/stats, returns status data on the specified node.

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsList of status data on each node, see for details

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes/emqx@127.0.0.1/stats"
    3. {"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}

    Alarm

    GET /api/v4/alarms/present

    Return the current alarm information in the cluster.

    Path Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsAlarm list on each node
    data[0].nodeStringNode name
    data[0].alarmsArray of ObjectsCurrent alarm list
    data[0].alarms[0].idStringAlarm identifier
    data[0].alarms[0].descStringDetailed description of the alarm

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms/present"
    3. {"data":[{"node":"emqx@127.0.0.1","alarms":[{"id":"cpu_high_watermark","desc":"88.30833333333334"}]}],"code":0}

    GET /api/v4/alarms/present/{node}

    Returns the current alarm information under the specified node. For interface parameters and returns, see GET /api/v4/stats。

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms/present/emqx@127.0.0.1"
    3. {"data":[{"id":"cpu_high_watermark","desc":"91.68333333333332"}],"code":0}

    GET /api/v4/alarms/history

    Returns historical alarm information under the cluster.

    Path Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArray of ObjectsAlarm list on each node
    data[0].nodeStringNode name
    data[0].alarmsArray of ObjectsList of current alarms
    data[0].alarms[0].idStringAlarm identifier
    data[0].alarms[0].descStringDetailed description of the alarm
    data[0].alarms[0].clear_atStringAlarm clear time, with the format “YYYY-MM-DD HH:mm:ss”

    Examples:

    GET /api/v4/alarms/history/{node}

    Returns historical alarm information under the specified node. For interface parameters and returns, see 。

    Examples:

    1. $ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/alarms/history/emqx@127.0.0.1"
    3. {"data":[{"id":"cpu_high_watermark","desc":"93.27055293970582","clear_at":"2020-02-21 13:50:10"}],"code":0}

    ACL Cache

    DELETE /api/v4/acl-cache

    Clean acl cache on all nodes

    Query String Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageStringReturn only when an error occurs to provide more detailed error information

    Examples:

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/acl-cache"
    3. {"code":0}

    DELETE /api/v4/node/{node}/acl-cache

    Clean acl cache for specific node

    Query String Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageStringReturn only when an error occurs to provide more detailed error information

    Examples:

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/node/emqx@127.0.0.1/acl-cache"
    3. {"code":0}

    Blacklist

    GET /api/v4/banned

    Get the blacklist

    Query String Parameters:

    Same as /api/v4/clients。

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataArrayAn array of objects with the same fields as the Request Body in the POST method
    metaObjectSame as /api/v4/clients

    Examples:

    Get blacklist:

    1. $ curl -i --basic -u admin:public -vX GET "http://localhost:8081/api/v4/banned"
    3. {"meta":{"page":1,"limit":10000,"count":1},"data":[{"who":"example","until":1582265833,"reason":"undefined","by":"user","at":1582265533,"as":"clientid"}],"code":0}

    POST /api/v4/banned

    Add object to blacklist

    Parameters (json):

    NameTypeRequiredDefaultDescription
    whoStringRequiredObjects added to the blacklist, which can be client identifiers, usernames, and IP addresses
    asStringRequiredUsed to distinguish the types of blacklist objects, which can be clientid，username，peerhost
    byStringOptionaluserIndicate which object was added to the blacklist
    atIntegerOptionalCurrent system timeTime added to blacklist, unit: second
    untilIntegerOptionalCurrent system time+ 5 minutesWhen to remove from blacklist, unit: second

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    dataObjectSame as incoming Request Body

    Examples:

    Add client to blacklist:

    1. $ curl -i --basic -u admin:public -vX POST "http://localhost:8081/api/v4/banned" -d '{"who":"example","as":"clientid"}'
    3. {"data":{"who":"example","as":"clientid"},"code":0}

    DELETE /api/v4/banned/{as}/{who}

    Delete object from blacklist

    Parameters: None

    Success Response Body (JSON):

    NameTypeDescription
    codeInteger0
    messageStringReturn only when an error occurs to provide more detailed error information

    Examples:

    Delete client from blacklist

    1. $ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/banned/clientid/example"
    3. {"code":0}

    Rule

    Query rule engine actions

    GET /api/v4/rules/{rule_id}

    Get the details of a rule, including the rule’s SQL, Topics list, action list, etc. It also returns the value of the statistical index for the current rule and action.

    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

    POST /api/v4/rules

    Create a rule and return the rule ID.

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

    PUT /api/v4/rules/{rule_id}

    Update the rule and return the rule ID.

    Parameters (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 /api/v4/rules/{rule_id}

    Delete the rule

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

    1. $ curl -XPOST -d '{
    2.   "rawsql": "select * from \"t/a\"",
    3.   "actions": [{
    4.       "name": "inspect",
    5.       "params": {
    6.           "a": 1
    7.       }
    8.   }],
    9.   "description": "test-rule"
    10. }' --basic -u admin:public 'http://localhost:8081/api/v4/rules'
    12. {"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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e'
    3. {"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::

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules'
    3. {"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":

    1. $ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e' -d '{"rawsql":"select * from \"t/b\""}'
    3. {"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:

    1. $ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e' -d '{"enabled": false}'
    3. {"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:

    1. $ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:7fdb2c9e'
    3. {"code":0}

    Actions

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

    GET api/v4/actions/{action_name}

    Get the details of an action, including the action name, parameter list, etc.

    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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/actions/inspect'
    3. {"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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/actions'
    3. {"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}

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

    GET api/v4/resource_types/{resource_type_name}

    Get the details of an action, including the action name, parameter list, etc.

    Path Parameters:

    NameTypeRequiredDescription
    resource_type_nameStringFalseOptional, the resource type name. If not specified then
    returns all the currently supported resource types in 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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resource_types/web_hook'
    3. {"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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resource_types'
    3. {"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.

    GET api/v4/resources/{resource_id}

    Gets the details of the specified resource.

    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.

    POST /api/v4/resources

    Create a rule and return the resource ID.

    Parameters (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 /api/v4/resources/{resource_id}

    Delete the resource

    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 ：

    1. $ curl -XPOST -d '{
    2.   "type": "web_hook",
    3.   "config": {
    4.       "url": "http://127.0.0.1:9910",
    5.       "headers": {"token":"axfw34y235wrq234t4ersgw4t"},
    6.       "method": "POST"
    7.   },
    8.   "description": "web hook resource-1"
    9. }' --basic -u admin:public 'http://localhost:8081/api/v4/resources'
    11. {"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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resources/resource:b12d3e44'
    3. {"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:

    1. $ curl --basic -u admin:public 'http://localhost:8081/api/v4/resources'
    3. {"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}
    1. $ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/resources/resource:b12d3e44'