# HTTP API

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/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 | POST /api/v1

# Broker info

Returns the information of broker.

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired2Request Code 2.
seqIntegerRequireduniqueThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerThe seq is a unique number, response get this value from request. So you can know correspondence between request and response.
repIntegerThe rep equal 2 as response to req equal 2.
data.client_sizeIntegerSubscribe client size.
data.message_inIntegerStatistic broker message in.
data.message_outIntegerStatistic broker message out.
data.message_dropIntegerStatistic broker message dropped.

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v1" -d '{"req": 2,"seq": 1111111}'
{"code":0,"seq":1111111,"rep":2,"data":{"client_size":1,"message_in":4,"message_out":0,"message_drop":4}}
1
2

# Topic info

Returns the information of all subscribe topics with client identifier and qos.

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired4Request Code 4.
seqIntegerRequireduniqueThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerThe seq is a unique number, response get this value from request. So you can know correspondence between request and response.
repIntegerThe rep equal 4 as response to req equal 4.
data[0].client_idStringclient identifier.
data[0].subscriptions[0].topicStringSubscribe topic.
data[0].subscriptions[0].qosIntegerSubscribe qos.

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v1" -d '{"req": 4,"seq": 1111111}'
{"code":0,"seq":1111111,"rep":4,"data":[{"client_id":"nanomq-ebd54382","subscriptions":[{"topic":"a/b/c","qos":0}]}]}
1
2

# Client info

Returns the information of all clients.

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired5Request Code 5.
seqIntegerRequireduniqueThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerThe seq is a unique number, response get this value from request. So you can know correspondence between request and response.
repIntegerThe rep equal 5 as response to req equal 5.
data[0].client_idStringclient identifier.
data[0].usernameStringUsername.
data[0].keepaliveIntegerKeepalive.
data[0].protocolIntegerProtocol version.
data[0].connect_statusIntegerConnected status.
data[0].message_receiveIntegerReceived message of this client.

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v1" -d '{"req": 5,"seq": 1111111}'
{"code":0,"seq":1111111,"rep":5,"data":[{"client_id":"nanomq-ebd54382","username":"nanmq","keepalive":60,"protocol":4,"connect_status":1,"message_receive":0}]
1
2

# Get Configuration

Read all of configure parameters from broker.

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired11Request Code 11.
seqIntegerRequireduniqueThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.
repIntegerThe rep equal 11 as response to req equal 11.
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].qosIntegerQos.

Example:

$ curl --location --request GET 'http://localhost:8081/api/v1' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--header 'Content-Type: application/json' \
--data-raw '{
    "req": 11,
    "seq": 9999
}'
{
    "code": 0,
    "seq": 9999,
    "rep": 11,
    "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"
        },
        "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
62
63
64
65
66
67
68

# Set Configuration

Set configure parameters for broker.

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired12Request Code 12.
seqIntegerRequireduniqueThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.
dataObjectRequiredSee Get Configuration [data](#Get Configuration).

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerThe seq is a unique number, response will carry this field. So you can know correspondence between request and response.
repIntegerThe rep equal 12 as response to req equal 12.

Example:

$ curl --location --request POST 'http://localhost:8081/api/v1' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--header 'Content-Type: application/json' \
--data-raw '{
    "req": 12,
    "seq": 111,
    "data": {
        "url": "nmq-tcp://0.0.0.0:1883",
        "num_taskq_thread": 10,
        "max_taskq_thread": 10,
        "parallel": 10,
        "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": true,
            "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
                }
            ]
        }
    }
}'

{"code":0,"seq":111,"rep":12}
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
62
63
64
65
66