Skip to content


EMQX exposes an HTTP management API designed following OpenAPI (Swagger) 3.0 specification.

After EMQX is started, you can visit http://localhost:18083/api-docs/index.html to view the API document and execute the management APIs from the Swagger UI. By default, under the Dashboard configuration, swagger_support is set to true, indicating Swagger UI support is enabled, which means all Swagger-related features are turned on, such as generating interactive API documentation. You can also set it to false to disable this feature. For more information, see Dashboard configuration.

The section introduces how to work with EMQX REST API.

Basic Path

EMQX has version control on the REST API, all API paths from EMQX 5.0.0 start with /api/v5.


EMQX's REST API uses HTTP Basic Authentication with API keys as authentication credentials. Before using the EMQX REST API, you need to create an API key.


For security reasons, from EMQX 5.0.0 onwards, Dashboard users cannot be used for REST API authentication. Role-based API credentials are a feature of the EMQX Enterprise edition.

Create API Keys

You can manually create API keys for authentication on the Dashboard by navigating to System -> API Key. For instructions, see System - API Keys.

You can also create API keys using the bootstrap file method. Add the following configuration to the emqx.conf file to specify the file location:

api_key = {
  bootstrap_file = "etc/default_api_key.conf"

In the specified file, add multiple API keys in the format {API Key}:{Secret Key}:{?Role}, separated by new lines:

  • API Key: Any string as the key identifier.
  • Secret Key: Use a random string as the secret key.
  • Role (optional): Specify the key's role, applicable only in the Enterprise edition.

For example:


API keys created this way are valid indefinitely.

Each time EMQX starts, it will add the data set in the file to the API key list. If an API key already exists, its Secret Key and Role will be updated.

Roles and Permissions

In the EMQX Enterprise edition, the REST API implements role-based access control. When creating an API key, you can assign one of the following 3 predefined roles:

  • Administrator: This role can access all resources and is the default value if no role is specified. The corresponding role identifier is administrator.
  • Viewer: This role can only view resources and data, corresponding to all GET requests in the REST API. The corresponding role identifier is viewer.
  • Publisher: Designed specifically for MQTT message publishing, this role is limited to accessing APIs related to message publishing. The corresponding role identifier is publisher.

Authentication Method

You can use the generated API Key and Secret Key as the username and password for Basic authentication:

HTTP Headers

Unless otherwise specified, most API requests require the Accept header to be set to application/json, and then the response will be returned in JSON format.

HTTP Response Status Code

EMQX follows the HTTP Response Status Code standard, and the possible status codes are as follows:

200Request successfully, and the returned JSON data will provide more details
201Created successfully, and the new object will be returned in the Body
204Request successfully. Usually used for delete and update operations, and the returned Body will be empty
400Bad Request. Usually request body or parameter error
401Unauthorized. API key expires or does not exist.
403Forbidden. Check if the object is in use or has dependency constraints.
404Not Found. You can refer to the message field in the Body to check the reason
409Conflict. The object already exists or the number limit is exceeded
500Internal Server Error. Check the reason in the Body and logs


For some APIs with large amounts of data, pagination functionality is provided. There are 2 types of pagination methods based on the data characteristics.

Page Number Pagination

In most APIs that support pagination, you can control the pagination by using the page (page number) and limit (page size) parameters. The maximum page size is 10000. If the limit parameter is not specified, the default is 100.

For example:

GET /clients?page=1&limit=100

In the response result, the meta field will contain pagination information. EMQX cannot predict the total number of data entries for requests using search conditions. Therefore, the meta.hasnext field indicates whether there is another page of data:


Cursor Pagination

In a few APIs where data changes rapidly, and page number pagination is inefficient, cursor pagination is used.

You can specify the starting position of the data using the position or cursor (starting position) parameter, and the limit (page size) parameter specifies the number of entries loaded from the starting position. The maximum page size is 10000. If the limit parameter is not specified, it defaults to 100.

For example:

GET /clients/{clientid}/mqueue_messages?position=1716187698257189921_0&limit=100

The meta field in the response will contain pagination information, with meta.position or meta.cursor indicating the starting position of the next page:

    "meta": {
        "start": "1716187698009179275_0",
        "position": "1716187698491337643_0"
    "data": [
            "inserted_at": "1716187698260190832",
            "publish_at": 1716187698260,
            "from_clientid": "mqttx_70e2eecf_10",
            "from_username": "undefined",
            "msgid": "000618DD161F682DF4450000F4160011",
            "mqueue_priority": 0,
            "qos": 0,
            "topic": "t/1",
            "payload": "SGVsbG8gRnJvbSBNUVRUWCBDTEk="

This pagination method efficiently handles scenarios where data changes rapidly, ensuring continuity and efficiency in data retrieval.

Error Codes

Besides the HTTP response status codes, EMQX also defines a list of error codes to identify specific errors.

When an error happens, the error code is returned in JSON format by the Body:

# GET /clients/foo

  "reason": "Client id not found"
Error CodesDescription
WRONG_USERNAME_OR_PWDWrong username or password
WRONG_USERNAME_OR_PWD_OR_API_KEY_OR_API_SECRETWrong username & password or key & secret
BAD_REQUESTRequest parameters not legal
NOT_MATCHConditions not matched
ALREADY_EXISTSResources already exist
BAD_CONFIG_SCHEMAConfiguration data not legal
BAD_RPCRPC Failed. Check the cluster status and the requested node status
BAD_TOPICTopic syntax error, topic needs to comply with the MQTT protocol standard
EXCEED_LIMITResources to be created exceed the maximum limit or minimum limit
INVALID_PARAMETERRequest parameters not legal and exceed the boundary value
CONFLICTConflicting request resources
NO_DEFAULT_VALUERequest parameters do not use default values
DEPENDENCY_EXISTSResource depends on other resources
MESSAGE_ID_SCHEMA_ERRORMessage ID parsing error
MESSAGE_ID_NOT_FOUNDMessage ID does not exist
NOT_FOUNDResource not found or does not exist
CLIENTID_NOT_FOUNDClient ID not found or does not exist
CLIENT_NOT_FOUNDClient not found or does not exist(usually not an MQTT client)
RESOURCE_NOT_FOUNDResource not found
TOPIC_NOT_FOUNDTopic not found
USER_NOT_FOUNDUser not found
INTERNAL_ERRORServer inter error
SERVICE_UNAVAILABLEService unavailable
SOURCE_ERRORSource error
REST_FAILEDReset source or configuration fails
CLIENT_NOT_RESPONSEClient not responding