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

result codes

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

The possible returned codes are as follows:

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

API Endpoints

GET /api/v4

Return all Endpoints supported by NanoMQ Broker.

Parameters: NULL

Success Response Body (JSON):

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

Examples:

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

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

Broker Basic Information

GET /api/v4/brokers

Return basic information of NanoMQ Broker.

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Object/Array of Objects	Returns the information of all nodes*(Only one node for NanoMQ)*
data.datetime	String	Current time, in the format of "YYYY-MM-DD HH: mm: ss"
data.node_status	String	Node status
data.sysdescr	String	Software description
data.uptime	String	NanoMQ Broker runtime, in the format of "H hours, m minutes, s seconds"
data.version	String	NanoMQ 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"}]}

Node

GET /api/v4/nodes

Return the status of the node.

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Object/Array of Objects	Returns information about all nodes in an Array
data.connections	Integer	Number of clients currently connected to this node
data.node_status	String	Node status
data.uptime	String	NanoMQ Broker runtime
data.version	String	NanoMQ 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"}]}

Statistical information

GET /api/v4/metrics

Return statistical information of NanoMQ.

Success Response Body (JSON):

Name	Type	Description
metrics	Object/Array of Objects	Unsupport now, (null)
cpuinfo	Integer Percent	NanoMQ CPU usage
memory	Integer	NanoMQ memory usage

Examples:

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

{"metrics":[],"cpuinfo":"0.00%","memory":"20049920"}

GET /api/v4/prometheus

Return Prometheus statistical information.

Success Response Body (text/plain):

Name	Type	Description
nanomq_connections_count	gauge	Number of connections
nanomq_connections_max	gauge	Maximum supported number of connections
nanomq_sessions_count	gauge	Number of sessions
nanomq_sessions_max	gauge	Maximum supported number of sessions
nanomq_topics_count	gauge	Number of topics
nanomq_topics_max	gauge	Maximum supported number of topics
nanomq_subscribers_count	gauge	Number of subscribers
nanomq_subscribers_max	gauge	Maximum supported number of subscribers
nanomq_messages_received	counter	The counter of messages received
nanomq_messages_sent	counter	The counter of messages sent
nanomq_messages_dropped	counter	The counter of messages dropped
nanomq_memory_usage	gauge	CPU Usage
nanomq_memory_usage_max	gauge	Maximum CPU Usage
nanomq_cpu_usage	gauge	Memory Usage
nanomq_cpu_usage_max	gauge	Maximum memory Usage

Examples:

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

# TYPE nanomq_connections_count gauge
# HELP nanomq_connections_count
nanomq_connections_count 0
# TYPE nanomq_connections_max gauge
# HELP nanomq_connections_max
nanomq_connections_max 0
# TYPE nanomq_sessions_count gauge
# HELP nanomq_sessions_count
nanomq_sessions_count 0
# TYPE nanomq_sessions_max gauge
# HELP nanomq_sessions_max
nanomq_sessions_max 0
# TYPE nanomq_topics_count gauge
# HELP nanomq_topics_count
nanomq_topics_count 0
# TYPE nanomq_topics_max gauge
# HELP nanomq_topics_max
nanomq_topics_max 0
# TYPE nanomq_subscribers_count gauge
# HELP nanomq_subscribers_count
nanomq_subscribers_count 0
# TYPE nanomq_subscribers_max gauge
# HELP nanomq_subscribers_max
nanomq_subscribers_max 0
# TYPE nanomq_messages_received counter
# HELP nanomq_messages_received
nanomq_messages_received 0
# TYPE nanomq_messages_sent counter
# HELP nanomq_messages_sent
nanomq_messages_sent 0
# TYPE nanomq_messages_dropped counter
# HELP nanomq_messages_dropped
nanomq_messages_dropped 0
# TYPE nanomq_memory_usage gauge
# HELP nanomq_memory_usage (b)
nanomq_memory_usage 19922944
# TYPE nanomq_memory_usage_max gauge
# HELP nanomq_memory_usage_max (b)
nanomq_memory_usage_max 19922944
# TYPE nanomq_cpu_usage gauge
# HELP nanomq_cpu_usage (%)
nanomq_cpu_usage 0.00
# TYPE nanomq_cpu_usage_max gauge
# HELP nanomq_cpu_usage_max (%)
nanomq_cpu_usage_max 0.00

Client

GET /api/v4/clients

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

Name	Type	Required	Description
clientid	String	False	Client identifier
username	String	False	Client username
conn_state	Enum	False	The current connection status of the client, the possible values areconnected,idle,disconnected
clean_start	Bool	False	Whether the client uses a new session
proto_name	Enum	False	Client protocol name, the possible values areMQTT,CoAP,LwM2M,MQTT-SN
proto_ver	Integer	False	Client protocol version

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	Information for all clients
data[0].clientid	String	Client identifier
data[0].username	String	User name of client when connecting
data[0].proto_name	String	Client protocol name*(MQTT,CoAP,LwM2M,MQTT-SN)*
data[0].proto_ver	Integer	Protocol version used by the client
data[0].connected	Boolean	Whether the client is connected
data[0].keepalive	Integer	keepalive time, with the unit of second
data[0].clean_start	Boolean	Indicate whether the client is using a brand new session
data[0].recv_msg	Integer	Number 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}]}

GET /api/v4/clients/{clientid}

Returns information for the specified client

Path Parameters:

Name	Type	Required	Description
clientid	String	True	ClientID

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	Client information, for details, see [GET /api/v4/clients](#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}]}

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

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

Path Parameters:

Name	Type	Required	Description
username	String	True	Username

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	Information about clients, for details, see [GET /api/v4/clients](#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}]}

Subscription Information

GET /api/v4/subscriptions

Multiple conditions queries are supported:

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	All subscription information
data[0].clientid	String	Client identifier
data[0].topic	String	Subscribe to topic
data[0].qos	Integer	QoS 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}]}

GET /api/v4/subscriptions/{clientid}

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

Path Parameters:

Name	Type	Required	Description
clientid	String	True	ClientID

Success Response Body (JSON):

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

Examples:

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

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

Publish message

POST /api/v4/mqtt/publish

Publish MQTT message。

Parameters (json):

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

Properties：

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

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

{"code":0}

Subscribe to topic

POST /api/v4/mqtt/subscribe (Unsupported now)

Subscribe to MQTT topic

Parameters (json):

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

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

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

{"code":0}

POST /api/v4/mqtt/unsubscribe (Unsupported now)

Unsubscribe.

Parameters (json):

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

Unsubscribe from a topic

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

{"code":0}

Message publish in batch

POST /api/v4/mqtt/publish_batch

Publish MQTT messages in batch.

Parameters (json):

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish_batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example","properties": {"user_properties":{"id": 10010, "name": "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}

Topic subscription in batch

POST /api/v4/mqtt/subscribe_batch (Unsupported now)

Subscribe to MQTT topics in batch.

Parameters (json):

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

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

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

{"code":0}

POST /api/v4/mqtt/unsubscribe_batch (Unsupported now)

Unsubscribe in batch.

Parameters (json):

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

Unsubscribe from a,b topics at one time

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

{"code":0}

Topic tree structure

GET /api/v4/topic-tree

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects
data[0].clientid	Array of String	Array of client identifies
data[0].topic	String	Subscribe to topic
data[0].cld_cnt	Integer	Number 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"]}]]}

Get hot updatable configuration

GET /api/v4/reload

Return all configuration that can be hot updatable.

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data.property_size	Integer	Max size for a MQTT property.
data.msq_len	Integer	Queue length for resending messages.
data.qos_duration	Integer	The interval of the qos timer.
data.allow_anonymous	Boolean	Allow anonymous login.
data.max_packet_size	Kbytes	The max packet size of NanoMQ (Kbytes).
data.client_max_packet_size	Kbytes	The default max packet size of each client.
data.keepalive_backoff	Integer	The backoff for MQTT keepalive timeout.

Examples:

$ curl -i --basic -u admin:public -X GET 'http://127.0.0.1:8081/api/v4/reload' -d \
'{
    "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
    }
}'

Hot update configuration

POST /api/v4/reload

Set configuration that can be hot updatable.

Parameters (json):

Name	Type	Required	Value	Description
data	Object	Required		See [Get hot updatable configuration](#Get hot updatable configuration)。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

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

Update configuration file

POST /api/v4/config_update

Update config file.

Parameters (json):

Name	Type	Required	Value	Description
data	Object	Required		The transferred data content is a new configuration. You can refer to the configuration for details.

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

$ curl --basic -u admin:public -X POST "http://localhost:8081/api/v4/config_update" -d \
'
 # NanoMQ Configuration 0.18.0
 
 # #============================================================
 # # NanoMQ Broker
 # #============================================================
 
 mqtt {
     property_size = 32
     max_packet_size = 10KB
     max_mqueue_len = 2048
     retry_interval = 10s
     keepalive_multiplier = 1.25
 
     # Three of below, unsupported now
     max_inflight_window = 2048
     max_awaiting_rel = 10s
     await_rel_timeout = 10s
 }
 
 listeners.tcp {
     bind = "0.0.0.0:1883"
 }
 
 # listeners.ssl {
 # 	bind = "0.0.0.0:8883"
 # 	keyfile = "/etc/certs/key.pem"
 # 	certfile = "/etc/certs/cert.pem"
 # 	cacertfile = "/etc/certs/cacert.pem"
 # 	verify_peer = false
 # 	fail_if_no_peer_cert = false
 # }
 
 listeners.ws {
     bind = "0.0.0.0:8083/mqtt"
 }
 
 http_server {
     port = 8081
     limit_conn = 2
     username = admin
     password = public
     auth_type = basic
     jwt {
         public.keyfile = "/etc/certs/jwt/jwtRS256.key.pub"
     }
 }
 
 log {
     to = [file, console]
     level = info
     dir = "/tmp"
     file = "nanomq.log"
     rotation {
         size = 10MB
         count = 5
     }
 }
 
 auth {
     allow_anonymous = true
     no_match = allow
     deny_action = ignore
 
     cache = {
         max_size = 32
         ttl = 1m
     }
 
     # password = {include "/etc/nanomq_pwd.conf"}
     # acl = {include "/etc/nanomq_acl.conf"}
 }
'

{"code":0}

Get bridges configuration

GET /api/v4/bridges/

Get all nodes configuration of bridges

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	All configuration of bridges' node
data.bridges.nodes[0].name	String	Node name
data.bridges.nodes[0].enable	Boolean	Enter MQTT bridge mode (default false ).
data.bridges.nodes[0].connector.server	String	Remote Broker address.
data.bridges.nodes[0].connector.proto_ver	Boolean	MQTT client version（4｜5）.
data.bridges.nodes[0].connector.clientid	String	MQTT client identifier.
data.bridges.nodes[0].connector.keepalive	Integer	Interval of keepalive.
data.bridges.nodes[0].connector.clean_start	Boolean	Clean session.
data.bridges.nodes[0].connector.username	String	Login user name.
data.bridges.nodes[0].connector.password	String	Login password.
data.bridges.nodes[0].connector.conn_properties	Object	MQTT V5 Property of Connector (see table below)
data.bridges.nodes[0].connector.ssl.enable	Boolean	Launch TLS （ default false）。
data.bridges.nodes[0].connector.ssl.key_password	String	String containing the user's password. only used if the private keyfile is password-protected.
data.bridges.nodes[0].connector.ssl.keyfile	String	User's private PEM-encoded key.
data.bridges.nodes[0].connector.ssl.certfile	String	User certificate data.
data.bridges.nodes[0].connector.ssl.cacertfile	String	User's PEM-encoded CA certificates.
data.bridges.nodes[0].quic_keepalive	Duration	Interval of a sending keepalive packet via QUIC transport., （default 120s )
data.bridges.nodes[0].quic_idle_timeout	Duration	How 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_timeout	Duration	How 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_timeout	Duration	The Max time NanoMQ waits for establishing QUIC connection（default 60s )
data.bridges.nodes[0].hybrid_bridging	Boolean	Hybrid 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_timeout	Duration	Reset congestion control after being idle SendIdleTimeout (default 60s)
data.bridges.nodes[0].quic_initial_rtt_ms	Duration	Initial RTT estimate. (ms) (default: 800ms)
data.bridges.nodes[0].quic_max_ack_delay_ms	Duration	How long to wait after receiving data before sending an ACK. (default: 100ms)
data.bridges.nodes[0].quic_qos_priority	Boolean	Send QoS 1/2 msg in high prority. (default: true)
data.bridges.nodes[0].quic_0rtt	Boolean	0RTT is a feature of QUIC to re-establish connection quickly. . （default: true）
data.bridges.nodes[0].multi_stream	Boolean	Multiple stream option，（default false）
data.bridges.nodes[0].parallel	Long	Parallel of mqtt client.
data.bridges.nodes[0].forwards[0].remote_topic	String	First forward remote_topics.
data.bridges.nodes[0].forwards[0].local_topic	String	First forward remote_topics.
data.bridges.nodes[0].subscription[0].remote_topic	String	First remote_topic.
data.bridges.nodes[0].subscription[0].local_topic	String	First local_topic.
data.bridges.nodes[0].subscription[0].qos	Integer	First Qos.
data.bridges.nodes[0].sub_properties	Object	MQTT V5 Property of Subscription (see table below)
data.bridges.nodes[0].max_send_queue_len	Integer	Maximum number of message send queue length
data.bridges.nodes[0].max_recv_queue_len	Integer	Maximum 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": [
                        {
                            "remote_topic": "fwd/topic1",
                            "local_topic": "topic1",
                        },
                        {
                            "remote_topic": "fwd/topic2",
                            "local_topic": "topic2",
                        }
                    ],
                    "subscription": [
                        {
                            "remote_topic": "cmd/topic1",
                            "local_topic": "topic1",
                            "qos": 1
                        },
                        {
                            "remote_topic": "cmd/topic2",
                            "local_topic": "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
                    }
                }
            ]
        }
    }
}

GET /api/v4/bridges/{bridge_name}

Returns configuration for the specified bridge node.

Path Parameters:

Name	Type	Required	Description
bridge_name	String	True	bridge node name

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	for 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": [
                        {
                            "remote_topic": "fwd/topic1",
                            "local_topic": "topic1",
                        },
                        {
                            "remote_topic": "fwd/topic2",
                            "local_topic": "topic2",
                        }
                    ],
                    "subscription": [
                        {
                            "remote_topic": "cmd/topic1",
                            "local_topic": "topic1",
                            "qos": 1
                        },
                        {
                            "remote_topic": "cmd/topic2",
                            "local_topic": "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
                    }
                }
            ]
        }
    }
}

Update bridge configuration

PUT /api/v4/bridges/{bridge_name}

update bridge configuration dynamically, and trigger a reconnection to valid it. (This API only works for TCP now)

Path Parameters:

Name	Type	Required	Description
bridge_name	String	True	bridge node name

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
bridge_name	Objects	name of bridging node
bridge_name.name	String	Node name
bridge_name.enable	Boolean	MQTT bridge mode (default false ).
bridge_name.server	String	Remote Broker address.
bridge_name.proto_ver	Integer	MQTT client version（4｜5）
bridge_name.clientid	String	MQTT client identifier.
bridge_name.keepalive	Duration	Interval of keepalive.
bridge_name.clean_start	Boolean	Clean session flag.
bridge_name.username	String	Login user name.
bridge_name.password	String	Login password.
bridge_name.conn_properties	Object	MQTT V5 Property
bridge_name.will_properties	Object	MQTT V5 Property of will message
bridge_name.ssl.enable	Boolean	Launch TLS
bridge_name.ssl.key_password	String	String containing the user's password. only used if the private keyfile is password-protected.
bridge_name.ssl.keyfile	String	User's private PEM-encoded key.
bridge_name.ssl.certfile	String	User certificate data.
bridge_name.ssl.cacertfile	String	User's PEM-encoded CA certificates.
bridge_name.parallel	Long	number of Parallel processor of mqtt client.
bridge_name.forwards[0].remote_topic	String	No.x forward remote_topic.
bridge_name.forwards[0].local_topic	String	No.x forward local_topic.
bridge_name.subscription[0].remote_topic	String	No.x subscribe remote_topic.
bridge_name.subscription[0].local_topic	String	No.x subscribe local_topic.
bridge_name.subscription[0].qos	Integer	No.x subscribe Qos.
bridge_name.sub_properties	Object	MQTT V5 Property of Subscription (see table below)
bridge_name.max_send_queue_len	Integer	Maximum number of message send queue length
bridge_name.max_recv_queue_len	Integer	Maximum number of message receive queue length

Example:

$ curl -i --basic -u admin:public -X PUT 'http://localhost:8081/api/v4/bridges/emqx' -d '{
    "emqx": {
        "name": "emqx",
        "enable": true,
        "parallel": 8,
        "server": "mqtt-tcp://broker.emqx.io:1883",
        "proto_ver": 4,
        "clientid": "hello3",
        "clean_start": true,
        "username": "emqx",
        "password": "emqx123",
        "keepalive": 60,
        "forwards": [
            {
                "remote_topic": "fwd/topic1",
                "local_topic": "local/topic1"
            },
            {
                "remote_topic": "fwd/topic3",
                "local_topic": "local/topic3"
            }
        ],
        "subscription": [
            {
                "remote_topic": "cmd/topic1",
                "local_topic": "local/topic1",
                "qos": 1
            },
            {
                "remote_topic": "cmd/topic3",
                "local_topic": "local/topic3",
                "qos": 2
            }
        ]
    }
}'

{"code":0}

Returning 108 may be due to one of the following two reasons:

Incorrect specification of the "name" parameter in the URL. A naming error in the JSON. For example, in the above example, the "emqx" in the JSON does not match the "emqx" name in the URL. Returning 109 is because the JSON data is invalid.

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

Dynamically change the subscription Topics of bridging connection. (works for both TCP & QUIC)

Path Parameters:

Name	Type	Required	Description
bridge_name	String	True	bridge node name

Name	Type	Required	Description
code	Integer	0
data	Objects	bridge node name
data.subscription[0].remote_topic	String	subscription remote_topic
data.subscription[0].local_topic	String	subscription local_topic
data.subscription[0].qos	Integer	subscription QoS
data.sub_properties	Object	Subscription MQTT V5 property
data.sub_properties.identifier	Integer	Subscription id
data.sub_properties.user_properties	Object	Subscription user property

Example:

Take bridge name = EMQX as an example

$ curl --location 'http://127.0.0.1:8081/api/v4/bridges/sub/emqx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--data '{
    "data": {
        "subscription": [
            {
                "remote_topic": "cmd/topic4",
                "local_topic": "topic4",
                "qos": 1
            },
            {
                "remote_topic": "cmd/topic5",
                "local_topic": "topic5",
                "qos": 2
            }
        ],
        "sub_properties": {
            "identifier": 1,
            "user_properties": [
                {
                    "key": "key1",
                    "value": "value1"
                },
                {
                    "key": "key2",
                    "value": "value2"
                }
            ]
        }
    }
}'

{"code":0}

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

Dynamically change the subscription Topics of bridging connection. (works for both TCP & QUIC)

Path Parameters:

Name	Type	Required	Description
bridge_name	String	True	bridge node name

Success Response Body (JSON):

Name	Type	Required	Description
code	Integer	0
data	Objects	bridge node name
data.unsubscription[0].topic	String	subscription topic
data.unsubscription[0].qos	Integer	subscription QoS
data.unsub_properties	Object	Subscription MQTT V5 property
data.unsub_properties.identifier	Integer	Subscription id
data.unsub_properties.user_properties	Object	Subscription user property

Example:

$ curl --location 'http://127.0.0.1:8081/api/v4/bridges/unsub/emqx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--data '{
    "data": {
        "unsubscription": [
            {
                "topic": "cmd/topic1"
            },
            {
                "topic": "cmd/topic2"
            }
        ],
        "unsub_properties": {
            "user_properties": [
                {
                    "key": "key1",
                    "value": "value1"
                },
                {
                    "key": "key2",
                    "value": "value2"
                }
            ]
        }
    }
}'

{"code":0}

Broker Control

POST /api/v4/ctrl/{action}

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

Path Parameters:

Name	Type	Required	Description
clientid	String	True	Possible values are stop, restart

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

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

{"code":0}

Rule

Query rule engine actions

GET /api/v4/rules/

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	Filter condition: whether the rule is enabled or not
data	Array of Objects	rule detail
data[0].id	String	Rule ID
data[0].rawsql	String	SQL 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:

Name	Type	Required	Description
rule_id	String	False	Optional, Rule ID. If rule_id is not specified then returns all created rules in an array

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	Filter condition: whether the rule is enabled or not
data	Object	Rule object
- data.id	String	Rule ID
- data.rawsql	String	SQL statement, consistent with rawsql in the request

POST /api/v4/rules

Create a rule and return the rule ID.

Parameters (json):

Name	Type	Required	Description
rawsql	String	True	SQL statements of rules
actions	Array	True	Action list
- actions[0].name	String	True	Action name (include repub, mysql, sqlite)
- actions[0].params	Object	True	Action parameters, that is expressed in key-value form. For details, please refer to the example of adding rules
description	String	False	Optional, rule description

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	Filter condition: whether the rule is enabled or not
data	Object	Rule object
- data.id	String	Rule ID
- data.rawsql	String	SQL statement, consistent with rawsql in the request

PUT /api/v4/rules/{rule_id}

Update the rule and return the rule ID.

Parameters (json):

Name	Type	Required	Description
rawsql	String	True	Optional, SQL statement of the rule
actions	Array	True	Optional, action list
- actions[0].name	String	True	Optional, action name
- actions[0].params	Object	True	Optional, action parameters, that is expressed in key-value form. For details, please refer to the example of adding rules
description	String	False	Optional, rule description

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	Filter condition: whether the rule is enabled or not
data	Object	Rule object
- data.id	String	Rule ID
- data.rawsql	String	SQL statement, consistent with rawsql in the request

DELETE /api/v4/rules/{rule_id}

Delete the rule

Parameters: None

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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":"mqtt-tcp://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}

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}

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}

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}

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}

Delete the rule:

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

{"code":0}