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

Multiple conditions are supported. The query parameters included are shown below.

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

# 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
propertiesObjectOptional{}The Properties of the PUBLISH message

Properties:

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

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

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

{"code":0}
1
2
3
4

# 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

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

{"code":0}
1
2
3

# POST /api/v4/mqtt/unsubscribe

Unsubscribe.

Parameters (json):

NameTypeRequiredDefaultDescription
topicStringRequiredTopic
clientidStringRequiredClient identifier

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

Unsubscribe from a topic

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

{"code":0}
1
2
3

# 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
[0].propertiesObjectOptional{}The Properties of the PUBLISH message

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

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

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

# 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

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

{"code":0}
1
2
3

# 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

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

{"code":0}
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 hot updatable configuration

# GET /api/v4/reload

Return all configuration that can be hot updatable.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
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.max_packet_sizeKbytesThe max packet size of NanoMQ (Kbytes).
data.client_max_packet_sizeKbytesThe default max packet size of each client.
data.keepalive_backoffIntegerThe backoff for MQTT keepalive timeout.

Examples:

$ curl -i --basic -u admin:public -X GET 'http://127.0.0.1:8081/api/v4/reload' 

{
    "code": 0,
    "data": {
        "property_size": 64,
        "max_packet_size": 3,
        "client_max_packet_size": 5,
        "msq_len": 2048,
        "qos_duration": 10,
        "keepalive_backoff": 1250,
        "allow_anonymous": false
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Hot update configuration

# POST /api/v4/reload

Set configuration that can be hot updatable.

Parameters (json):

NameTypeRequiredValueDescription
dataObjectRequiredSee [Get hot updatable configuration](#Get hot updatable configuration)。

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/configuration' -d \
'{
       "data": {
        "property_size": 64,
        "max_packet_size": 3,
        "client_max_packet_size": 5,
        "msq_len": 2048,
        "qos_duration": 10,
        "keepalive_backoff": 1250,
        "allow_anonymous": false
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Get bridges configuration

# GET /api/v4/bridges/

Get all nodes configuration of bridges

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of ObjectsAll configuration of bridges' node
data.bridges.nodes[0].nameStringNode name
data.bridges.nodes[0].enableBooleanEnter MQTT bridge mode (default false ).
data.bridges.nodes[0].connector.serverStringRemote Broker address.
data.bridges.nodes[0].connector.proto_verBooleanMQTT client version(4|5).
data.bridges.nodes[0].connector.clientidStringMQTT client identifier.
data.bridges.nodes[0].connector.keepaliveIntegerInterval of keepalive.
data.bridges.nodes[0].connector.clean_startBooleanClean session.
data.bridges.nodes[0].connector.usernameStringLogin user name.
data.bridges.nodes[0].connector.passwordStringLogin password.
data.bridges.nodes[0].connector.conn_propertiesObjectMQTT V5 Property of Connector (see table below)
data.bridges.nodes[0].connector.ssl.enableBooleanLaunch TLS ( default false)。
data.bridges.nodes[0].connector.ssl.key_passwordStringString containing the user's password. only used if the private keyfile is password-protected.
data.bridges.nodes[0].connector.ssl.keyfileStringUser's private PEM-encoded key.
data.bridges.nodes[0].connector.ssl.certfileStringUser certificate data.
data.bridges.nodes[0].connector.ssl.cacertfileStringUser's PEM-encoded CA certificates.
data.bridges.nodes[0].quic_keepaliveDurationInterval of a sending keepalive packet via QUIC transport., (default 120s )
data.bridges.nodes[0].quic_idle_timeoutDurationHow long a connection can go idle before it is gracefully shut down. 0 to disable timeout, which may lost disconnect event msg. (default 120s )
data.bridges.nodes[0].quic_discon_timeoutDurationHow long to wait for an ACK before declaring a path dead and disconnecting, This affects stream living time.(default 20s )
data.bridges.nodes[0].quic_handshake_timeoutDurationThe Max time NanoMQ waits for establishing QUIC connection(default 60s )
data.bridges.nodes[0].hybrid_bridgingBooleanHybrid bridging: enable or disable the hybrid bridging mode,(default: false), recommend to enable it when you want to take advantage of QUIC
data.bridges.nodes[0].quic_send_idle_timeoutDurationReset congestion control after being idle SendIdleTimeout (default 60s)
data.bridges.nodes[0].quic_initial_rtt_msDurationInitial RTT estimate. (ms)
(default: 800ms)
data.bridges.nodes[0].quic_max_ack_delay_msDurationHow long to wait after receiving data before sending an ACK. (default: 100ms)
data.bridges.nodes[0].quic_qos_priorityBooleanSend QoS 1/2 msg in high prority. (default: true)
data.bridges.nodes[0].quic_0rttBoolean0RTT is a feature of QUIC to re-establish connection quickly. . (default: true
data.bridges.nodes[0].multi_streamBooleanMultiple stream option,(default false
data.bridges.nodes[0].parallelLongParallel of mqtt client.
data.bridges.nodes[0].forwardsArray[String]Array of forward topics.
data.bridges.nodes[0].subscription[0].topicStringFirst Topic.
data.bridges.nodes[0].subscription[0].qosIntegerFirst Qos.
data.bridges.nodes[0].sub_propertiesObjectMQTT V5 Property of Subscription (see table below)
data.bridges.nodes[0].max_send_queue_lenIntegerMaximum number of message send queue length
data.bridges.nodes[0].max_recv_queue_lenIntegerMaximum number of message receive queue length

Examples:

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

{
    "code": 0,
    "data": {
        "bridge": {
            "nodes": [
                {
                    "name": "emqx",
                    "enable": true,
                    "parallel": 2,
                    "connector": {
                        "server": "mqtt-tcp://broker.emqx.io:1883",
                        "proto_ver": 5,
                        "clientid": null,
                        "clean_start": true,
                        "username": "",
                        "password": "",
                        "keepalive": 60,
                        "conn_properties": {
                            "session_expiry_interval": 30,
                            "receive_maximum": 65535,
                            "maximum_packet_size": 0,
                            "topic_alias_maximum": 0,
                            "request_response_information": false,
                            "request_problem_information": true
                        },
                        "will_properties": {
                            "payload_format_indicator": 0,
                            "message_expiry_interval": 360,
                            "will_delay_interval": 20,
                            "user_properties": [
                                {
                                    "key": "key1",
                                    "value": "value1"
                                },
                                {
                                    "key": "key2",
                                    "value": "value2"
                                }
                            ]
                        }
                    },
                    "forwards": [
                        "topic1/#",
                        "topic2/#"
                    ],
                    "subscription": [
                        {
                            "topic": "cmd/topic1",
                            "qos": 1
                        },
                        {
                            "topic": "cmd/topic2",
                            "qos": 2
                        }
                    ],
                    "sub_properties": {
                        "identifier": 1,
                        "user_properties": [
                            {
                                "key": "key1",
                                "value": "value1"
                            },
                            {
                                "key": "key2",
                                "value": "value2"
                            }
                        ]
                    },
                    "tls": {
                        "enable": false,
                        "url": null,
                        "key_password": null,
                        "key": null,
                        "cert": null,
                        "cacert": null,
                        "verify_peer": false,
                        "fail_if_no_peer_cert": false
                    }
                }
            ]
        }
    }
}
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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# GET /api/v4/bridges/{bridge_name}

Returns configuration for the specified bridge node.

Path Parameters:

NameTypeRequiredDescription
bridge_nameStringTruebridge node name

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objectsfor details, see [GET /api/v4/bridges](#GET /api/v4/bridges/)

Example:

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

{
    "code": 0,
    "data": {
        "bridge": {
            "nodes": [
                {
                    "name": "emqx",
                    "enable": true,
                    "parallel": 2,
                    "connector": {
                        "server": "mqtt-tcp://broker.emqx.io:1883",
                        "proto_ver": 5,
                        "clientid": null,
                        "clean_start": true,
                        "username": "",
                        "password": "",
                        "keepalive": 60,
                        "conn_properties": {
                            "session_expiry_interval": 30,
                            "receive_maximum": 65535,
                            "maximum_packet_size": 0,
                            "topic_alias_maximum": 0,
                            "request_response_information": false,
                            "request_problem_information": true
                        },
                        "will_properties": {
                            "payload_format_indicator": 0,
                            "message_expiry_interval": 360,
                            "will_delay_interval": 20,
                            "user_properties": [
                                {
                                    "key": "key1",
                                    "value": "value1"
                                },
                                {
                                    "key": "key2",
                                    "value": "value2"
                                }
                            ]
                        }
                    },
                    "forwards": [
                        "topic1/#",
                        "topic2/#"
                    ],
                    "subscription": [
                        {
                            "topic": "cmd/topic1",
                            "qos": 1
                        },
                        {
                            "topic": "cmd/topic2",
                            "qos": 2
                        }
                    ],
                    "sub_properties": {
                        "identifier": 1,
                        "user_properties": [
                            {
                                "key": "key1",
                                "value": "value1"
                            },
                            {
                                "key": "key2",
                                "value": "value2"
                            }
                        ]
                    },
                    "tls": {
                        "enable": false,
                        "url": null,
                        "key_password": null,
                        "key": null,
                        "cert": null,
                        "cacert": null,
                        "verify_peer": false,
                        "fail_if_no_peer_cert": false
                    }
                }
            ]
        }
    }
}
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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# Update bridge configuration

# PUT /api/v4/bridges/{bridge_name}

update bridge configuration

Path Parameters:

NameTypeRequiredDescription
bridge_nameStringTruebridge node name

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObjects桥接客户端配置信息
data.nameStringNode name
data.enableBooleanEnter MQTT bridge mode (default false ).
data.connector.serverStringRemote Broker address.
data.connector.proto_verBooleanMQTT client version(4|5).
data.connector.clientidStringMQTT client identifier.
data.connector.keepaliveIntegerInterval of keepalive.
data.connector.clean_startBooleanClean session.
data.connector.usernameStringLogin user name.
data.connector.passwordStringLogin password.
data.connector.conn_propertiesObjectMQTT V5 Property of Connector (see table below)
data.connector.ssl.enableBooleanLaunch TLS ( default false)。
data.connector.ssl.key_passwordStringString containing the user's password. only used if the private keyfile is password-protected.
data.connector.ssl.keyfileStringUser's private PEM-encoded key.
data.connector.ssl.certfileStringUser certificate data.
data.connector.ssl.cacertfileStringUser's PEM-encoded CA certificates.
data.quic_keepaliveDurationInterval of a sending keepalive packet via QUIC transport., (default 120s )
data.quic_idle_timeoutDurationHow long a connection can go idle before it is gracefully shut down. 0 to disable timeout, which may lost disconnect event msg. (default 120s )
data.quic_discon_timeoutDurationHow long to wait for an ACK before declaring a path dead and disconnecting, This affects stream living time.(default 20s )
data.quic_handshake_timeoutDurationThe Max time NanoMQ waits for establishing QUIC connection(default 60s )
data.hybrid_bridgingBooleanHybrid bridging: enable or disable the hybrid bridging mode,(default: false), recommend to enable it when you want to take advantage of QUIC
data.quic_send_idle_timeoutDurationReset congestion control after being idle SendIdleTimeout (default 60s)
data.quic_initial_rtt_msDurationInitial RTT estimate. (ms)
(default: 800ms)
data.quic_max_ack_delay_msDurationHow long to wait after receiving data before sending an ACK. (default: 100ms)
data.quic_qos_priorityBooleanSend QoS 1/2 msg in high prority. (default: true)
data.quic_0rttBoolean0RTT is a feature of QUIC to re-establish connection quickly. . (default: true
data.multi_streamBooleanMultiple stream option,(default false
data.parallelLongParallel of mqtt client.
data.forwardsArray[String]Array of forward topics.
data.subscription[0].topicStringFirst Topic.
data.subscription[0].qosIntegerFirst Qos.
data.sub_propertiesObjectMQTT V5 Property of Subscription (see table below)
data.max_send_queue_lenIntegerMaximum number of message send queue length
data.max_recv_queue_lenIntegerMaximum number of message receive queue length

Example:

$ curl -i --basic -u admin:public -X PUT  'http://localhost:8081/api/v4/bridges/emqx' \
 -d '{
    "data": {
        "name": "emqx",
        "enable": true,
        "parallel": 8,
        "connector": {
            "server": "mqtt-tcp://broker.emqx.io:1883",
            "proto_ver": 4,
            "clientid": null,
            "clean_start": false,
            "username": "emqx",
            "password": "emqx123",
            "keepalive": 60
        },
        "forwards": [
            "topic1/#",
            "topic2/#"
        ],
        "subscription": [
            {
                "topic": "cmd/topic1",
                "qos": 1
            },
            {
                "topic": "cmd/topic2",
                "qos": 2
            }
        ],
        "tls": {
            "enable": false,
            "url": null,
            "key_password": null,
            "key": null,
            "cert": null,
            "cacert": null,
            "verify_peer": false,
            "fail_if_no_peer_cert": false
        },
        "quic_keepalive": "100s",
        "quic_idle_timeout": "100s",
        "quic_discon_timeout": "100s",
        "quic_send_idle_timeout": "20s",
        "quic_initial_rtt_ms": "800s",
        "quic_max_ack_delay_ms": "100s",
        "quic_multi_stream": true,
        "hybrid_bridging": true,
        "quic_qos_priority": true,
        "quic_0rtt": true
    }
}'

{"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

# 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

# Rule

Query rule engine actions

# GET /api/v4/rules/

Get rule list, including the rule's SQL, id, etc.

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBooleanFilter condition: whether the rule is enabled or not
dataArray of Objectsrule detail
data[0].idStringRule ID
data[0].rawsqlStringSQL statement, consistent with rawsql in the request

# GET /api/v4/rules/{rule_id}

Get the details of a rule, including the rule's SQL, id , etc.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
enabledBooleanFilter condition: whether the rule is enabled or not
dataObjectRule object
- data.idStringRule ID
- data.rawsqlStringSQL statement, consistent with rawsql in the request

# 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 (include repub, mysql, sqlite)
- 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
enabledBooleanFilter condition: whether the rule is enabled or not
dataObjectRule object
- data.idStringRule ID
- data.rawsqlStringSQL statement, consistent with rawsql in the request

# 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
enabledBooleanFilter condition: whether the rule is enabled or not
dataObjectRule object
- data.idStringRule ID
- data.rawsqlStringSQL statement, consistent with rawsql in the request

# 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".

$ curl -XPOST -d '{
  "rawsql": "select * from \"t/a\"",
  "actions": [{
      "name": "repub",
      "params": {
          "topic": "repub1", "address":"broker.emqx.io:1883", "clean_start": "true", "clientid": "id", "username": "admin", "password": "public", "proto_ver": 4, "keepalive": 60
      }
  }],
  "description": "repub-rule"

}' --basic -u admin:public 'http://localhost:8081/api/v4/rules'

{"data":{"rawsql":"select * from \"t/a\"","id":4,"enabled":true},"actions":[],"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13

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

$ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'

{"data":{"rawsql":"select * from \"t/a\"","id":1,"enabled":true},"actions":[],"code":0}
1
2
3

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

$ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules'

{"data":[{"rawsql":"SELECT payload.x.y as y, payload.z as z FROM \"#\" WHERE y > 10 and z != 'str'","id":1,"enabled":true},{"rawsql":"SELECT * FROM \"abc\"","id":2,"enabled":true},{"rawsql":"SELECT payload, qos FROM \"#\" WHERE qos > 0","id":3,"enabled":true},{"rawsql":"select * from \"t/a\"","id":4,"enabled":true}],"code":0}
1
2
3

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

$ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4' -d '{"rawsql":"select * from \"t/b\""}'

{"data":{"rawsql":"select * from \"t/b\"","id":4,"enabled":true},"actions":[],"code":0}
1
2
3

Disable the rule:

$ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4' -d '{"enabled": false}'
{"data":{"rawsql":"select * from \"t/b\"","id":4,"enabled":false},"actions":[],"code":0}
1
2

Delete the rule:

$ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'

{"code":0}
1
2
3