# HTTP API (V4)

NanoMQ Broker provides HTTP APIs for integration with external systems, such as querying broker statistics information, clients information, subscribe topics information, and restart with new config file.

NanoMQ Broker's HTTP API service listens on port 8081 by default. You can modify the listening port through the configuration file of etc/nanomq.conf. All API calls with api/v4.

The previous version: HTTP-API (v1)

# Interface security

NanoMQ Broker's HTTP API uses the method of Basic Authentication (opens new window) or JWT Authentication (opens new window). The username and password must be filled. The default username and password are: admin/public. You can modify username and password through the configuration file of etc/nanomq.conf.

# Response code

# HTTP status codes

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

The possible status codes are as follows:

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

# result codes

The response message body of the NanoMQ 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
116Token expired

# API Endpoints

# GET /api/v4

Return all Endpoints supported by NanoMQ Broker.

Parameters:

Success Response Body (JSON):

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

Examples:

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

{"code":0,"data":[{"path":"/brokers/","name":"list_brokers","method":"GET","descr":"A list of brokers in the cluster"},{"path":"/nodes/","name":"list_nodes","method":"GET","descr":"A list of nodes in the cluster"},{"path":"/clients/","name":"list_clients","method":"GET","descr":"A list of clients on current node"},{"path":"/clients/:clientid","name":"lookup_client","method":"GET","descr":"Lookup a client in the cluster"},{"path":"/clients/username/:username","name":"lookup_client_via_username","method":"GET","descr":"Lookup a client via username in the cluster"},{"path":"/subscriptions/","name":"list_subscriptions","method":"GET","descr":"A list of subscriptions in the cluster"},{"path":"/subscriptions/:clientid","name":"lookup_client_subscriptions","method":"GET","descr":"A list of subscriptions of a client"},{"path":"/topic-tree/","name":"list_topic-tree","method":"GET","descr":"A list of topic-tree in the cluster"},{"path":"/configuration/","name":"get_broker_configuration","method":"GET","descr":"show broker configuration"},{"path":"/configuration/","name":"set_broker_configuration","method":"POST","descr":"set broker configuration"},{"path":"/ctrl/:action","name":"ctrl_broker","method":"POST","descr":"Control broker stop or restart"}]}
1
2
3

# Broker Basic Information

# GET /api/v4/brokers

Return basic information of NanoMQ Broker.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of ObjectsReturns the information of all nodes*(Only one node for NanoMQ)*
data.datetimeStringCurrent time, in the format of "YYYY-MM-DD HH: mm: ss"
data.node_statusStringNode status
data.sysdescrStringSoftware description
data.uptimeStringNanoMQ Broker runtime, in the format of "H hours, m minutes, s seconds"
data.versionStringNanoMQ Broker version
$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers"

{"code":0,"data":[{"datetime":"2022-06-07 10:02:24","node_status":"Running","sysdescr":"NanoMQ Broker","uptime":"15 Hours, 1 minutes, 38 seconds","version":"0.7.9-3"}]}
1
2
3

# Node

# GET /api/v4/nodes

Return the status of the node.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of ObjectsReturns information about all nodes in an Array
data.connectionsIntegerNumber of clients currently connected to this node
data.node_statusStringNode status
data.uptimeStringNanoMQ Broker runtime
data.versionStringNanoMQ Broker version

Examples:

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

{"code":0,"data":[{"connections":0,"node_status":"Running","uptime":"15 Hours, 22 minutes, 4 seconds","version":"0.8.1"}]}
1
2
3

# Client

# GET /api/v4/clients

支持多条件查询,其包含的查询参数有:

NameTypeRequiredDescription
clientidStringFalseClient identifier
usernameStringFalseClient username
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

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsInformation for all clients
data[0].clientidStringClient identifier
data[0].usernameStringUser name of client when connecting
data[0].proto_nameStringClient protocol name*(MQTT,CoAP,LwM2M,MQTT-SN)*
data[0].proto_verIntegerProtocol version used by the client
data[0].connectedBooleanWhether the client is connected
data[0].keepaliveIntegerkeepalive time, with the unit of second
data[0].clean_startBooleanIndicate whether the client is using a brand new session
data[0].recv_msgIntegerNumber of PUBLISH packets received

Examples:

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

{"code":0,"data":[{"client_id":"nanomq-f6d6fbfb","username":"alvin","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5,"recv_msg":3},{"client_id":"nanomq-bdf61d9b","username":"nanomq","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5,"recv_msg":0}]}
1
2
3

# 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 [GET /api/v4/clients](#GET /api/v4/clients)

Examples:

Query the specified client

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

{"code":0,"data":[{"client_id":"nanomq-29978ec1","username":"","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5}]}
1
2
3

# 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 [GET /api/v4/clients](#GET /api/v4/clients)

Examples:

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

{"code":0,"data":[{"client_id":"nanomq-56baa74d","username":"user001","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5}]}
1
2
3

# Subscription Information

# GET /api/v4/subscriptions

Multiple conditions queries are supported:

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll subscription information
data[0].clientidStringClient identifier
data[0].topicStringSubscribe to topic
data[0].qosIntegerQoS level

Examples:

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

{"code":0,"data":[{"clientid":"nanomq-29978ec1","topic":"topic123","qos":2},{"clientid":"nanomq-3020ffac","topic":"topic123","qos":2}]}
1
2
3

# GET /api/v4/subscriptions/{clientid}

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

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

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

Examples:

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

{"data":[{"topic":"a/b/c","qos":1,"clientid":"123"}],"code":0}
1
2
3

# Topic tree structure

# GET /api/v4/topic-tree

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects
data[0].clientidArray of StringArray of client identifies
data[0].topicStringSubscribe to topic
data[0].cld_cntIntegerNumber of child node

Examples:

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

{"code":0,"data":[[{"topic":"","cld_cnt":1}],[{"topic":"topic123","cld_cnt":1,"clientid":["nanomq-3a4a0956"]}],[{"topic":"123","cld_cnt":1,"clientid":["nanomq-0cfd69bb"]}],[{"topic":"456","cld_cnt":0,"clientid":["nanomq-26971dc8"]}]]}
1
2
3

# Get configuration

# GET /api/v4/configuration

Read all of configure parameters from broker.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
data.urlStringUrl of listener.
data.num_taskq_threadIntegerNumber of taskq threads used.
data.max_taskq_threadIntegerMaximum number of taskq threads used。
data.parallelLongNumber of parallel.
data.property_sizeIntegerMax size for a MQTT property.
data.msq_lenIntegerQueue length for resending messages.
data.qos_durationIntegerThe interval of the qos timer.
data.allow_anonymousBooleanAllow anonymous login.
data.tls.enableBooleanEnable TLS listener.
data.tls.urlStringURL of TLS listener.
data.tls.keyStringUser's private PEM-encoded key.
data.tls.keypassStringString containing the user's password. Only used if the private keyfile is password-protected.
data.tls.certStringUser certificate data.
data.tls.cacertStringUser's PEM-encoded CA certificates.
data.tls.verify_peerBooleanVerify peer certificate.
data.tls.fail_if_no_peer_certBooleanServer will fail if the client does not have a certificate to send.
data.websocket.enableBooleanEnable websocket listener.
data.websocket.urlStringURL of websocket listener.
data.websocket.tls_urlStringURL of TLS over websocket listerner.
data.http_server.enableBooleanEnable http server listerner.
data.http_server.portIntegerPort of http server.
data.http_server.usernameStringUser name of http server.
data.http_server.passwordStringPassword of http server.
data.bridge.bridge_modeBooleanEnter MQTT bridge mode .
data.bridge.addressStringRemote Broker address.
data.bridge.proto_verStringMQTT client version(3|4|5)。
data.bridge.clientidStringMQTT client identifier.
data.bridge.keepaliveIntegerInterval of keepalive.
data.bridge.clean_startBooleanClean seeson.
data.bridge.parallelLongParallel of mqtt client。
data.bridge.usernameStringLogin user name.
data.bridge.passwordStringLogin password.
data.bridge.forwardsArray[String]Array of forward topics.
data.bridge.forwards[0]StringTopic.
data.bridge.subscriptionArray[Object]Array of subscriptions.
data.bridge.subscription[0].topicStringTopic.

| data.bridge.subscription[0].qos | Integer | Qos. |

Examples:

$ curl -i --basic -u admin:public -X GET 'http://127.0.0.1:8081/api/v4/configuration' 
{
    "code": 0,
    "data": {
        "url": "nmq-tcp://0.0.0.0:1883",
        "num_taskq_thread": 4,
        "max_taskq_thread": 4,
        "parallel": 32,
        "property_size": 32,
        "msq_len": 64,
        "allow_anonymous": true,
        "daemon": false,
        "tls": {
            "enable": false,
            "url": "tls+nmq-tcp://0.0.0.0:8883",
            "key_password": null,
            "key": null,
            "cert": null,
            "cacert": null,
            "verify_peer": false,
            "fail_if_no_peer_cert": false
        },
        "websocket": {
            "enable": true,
            "url": "nmq-ws://0.0.0.0:8083/mqtt",
            "tls_url": "nmq-wss://0.0.0.0:8084/mqtt"
        },
        "http_server": {
            "enable": true,
            "port": 8081,
            "username": "admin",
            "password": "public",
            "auth_type": "basic"
        },
        "bridge": {
            "bridge_mode": false,
            "address": "mqtt-tcp://broker.emqx.io:1883",
            "proto_ver": 4,
            "clientid": "bridge_client",
            "clean_start": true,
            "username": "username",
            "password": "passwd",
            "keepalive": 60,
            "parallel": 2,
            "forwards": [
                "topic1/#",
                "topic2/#"
            ],
            "subscription": [
                {
                    "topic": "cmd/topic1",
                    "qos": 1
                },
                {
                    "topic": "cmd/topic2",
                    "qos": 2
                }
            ]
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# Set Configuration

# POST /api/v4/configuration

Set configure parameters for broker.

Parameters (json):

NameTypeRequiredValueDescription
dataObjectRequiredSee [Get Configuration](#Get Configuration).

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/configuration' -d \
'{
   "data": {
        "url": "nmq-tcp://0.0.0.0:1883",
        "num_taskq_thread": 8,
        "max_taskq_thread": 4,
        "parallel": 32,
        "property_size": 32,
        "msq_len": 64,
        "allow_anonymous": true,
        "daemon": false,
        "tls": {
            "enable": false,
            "url": "nmq-tls://0.0.0.0:8883",
            "key_password": null,
            "key": null,
            "cert": null,
            "cacert": null,
            "verify_peer": false,
            "fail_if_no_peer_cert": false
        },
        "websocket": {
            "enable": true,
            "url": "nmq-ws://0.0.0.0:8083/mqtt",
            "tls_url": "nmq-wss://0.0.0.0:8084/mqtt"
        },
        "http_server": {
            "enable": true,
            "port": 8081,
            "username": "admin",
            "password": "public",
            "auth_type": "basic"
        },
        "bridge": {
            "bridge_mode": false,
            "address": "127.0.0.1:1883",
            "proto_ver": 4,
            "clientid": "bridge_client",
            "clean_start": true,
            "username": "user",
            "password": "passwd",
            "keepalive": 60,
            "parallel": 1,
            "forwards": [
                "topic1/#",
                "topic2/#"
            ],
            "subscription": [
                {
                    "topic": "cmd/topic1",
                    "qos": 1
                }
            ]
        }
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# Broker Control

# POST /api/v4/ctrl/{action}

Stop or Restart the NanoMQ Broker(Usually used after the configuration is modified).

Path Parameters:

NameTypeRequiredDescription
clientidStringTruePossible values are stop, restart

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/restart'

{"code":0}
1
2
3