# REST API

EMQX Cloud API follows the REST architecture. You can access the functions of EMQX programmatically.

# API Overview

APIDescription
Authentication managementManage the creation, deletion and update of authentication information.
ACL managementManage the creation, deletion and update of ACL information.
Client managementView the online client information and kick off the client.
Blacklist managementManage the creation, deletion and get of blacklist information
Message SubscriptionCheck subscribed message.
Topic SubscriptionSubscribe, unsubscribe, batch subscribe, batch unsubscribe.
Message PublishPublish, batch publish.
MetricsCheck metrics.

# How to Use API

# Construct Request

The request address consists of the following parts:

{API}/{resource-path}?{query-string}

You can get the API access address in the API access section under the deployment details page.

api

# Authentication

HTTP API uses Basic authentication (opens new window) method, ID and password must be filled in AppID and AppSecret respectively. You can add and remove AppID/AppSecret by creating new application in the API access under the deployment details page.

# Response code

# HTTP status codes

The EMQX 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
200Success, 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 EMQX Broker interface is in JSON format, which always contains the returned code.

The possible result codes are as follows:

Return CodeDescription
0Success.
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.