Deployment Management API

This page describes how to use the Platform API to list deployments, retrieve deployment details and connection information, start and stop deployments, create deployments, and create Deployment API Keys.

List Deployments

URI

GET /deployments

TIP

This method can only be requested 60 times within 60 minutes.

Request Message

None

Response Messages

• 200:

Name	Type	Description
connections	Number	The number of connections for the deployment.
tps	Number	The number of transactions per second (TPS) for the deployment.
createAt	String	The creation time of the deployment.
deploymentID	String	The unique deployment ID.
deploymentName	String	The name of the deployment.
deploymentType	String	The type of deployment: "serverless" for Serverless editions, "dedicated" for Dedicated editions and "dedicatedFlex" for Dedicated Flex editions
platform	String	The cloud service provider for the deployment.
projectName	String	The name of the project associated with the deployment.
region	String	The region where the deployment is located.
status	String	The current status of the deployment: "running", "starting", or "stopped".
version	String	The version of the deployment.

• 401: API Key authentication failed.
• 403: API Key lacks permission to access the requested resource.
• 429: Request limit exceeded.

Request Example

curl -u key:secret -X GET {api}/deployments

Response Example

[
    {
        "connections": 1000,
        "tps": 1000,
        "createAt": "2024-11-21 02:51",
        "deploymentID": "mdfba81f",
        "deploymentName": "deployment-mdfba81f",
        "deploymentType": "serverless",
        "platform": "AWS",
        "projectName": "default",
        "region": "N. Virginia (us-east-1)",
        "status": "stopped",
        "version": "v5"
    },
    {
        "connections": 1000,
        "tps": 1000,
        "createAt": "2025-04-17 08:36",
        "deploymentID": "b1f77113",
        "deploymentName": "deployment-b1f77113",
        "deploymentType": "dedicatedFlex",
        "platform": "AWS",
        "projectName": "test",
        "region": "N. Virginia (us-east-1)",
        "status": "running",
        "version": "v5"
    }
]

Get Deployment Details and Connection Information

URI

GET /deployments/{deployment_id}

TIP

This method can only be requested 60 times within 60 minutes. {deployment_id} refers to the deployment ID, not the deployment name.

Request Message

None

Response Messages

• 200:

Name	Type	Description
connections	Number	The number of connections for the deployment.
tps	Number	he number of transactions per second (TPS) for the deployment.
createAt	String	The creation time of the deployment.
deploymentID	String	The unique deployment ID.
deploymentName	String	The name of the deployment.
deploymentType	String	The type of deployment, "dedicated" for dedicated versions and "dedicatedFlex" for dedicated flex versions
platform	String	The cloud service provider for the deployment.
region	String	The region where the deployment is located.
status	String	The current status of the deployment: "running", "starting", or "stopped".
connection	Object or null	Connection information for the deployment. For a running deployment, this object includes its connection addresses, all available ports and their status, and the API address. For a deployment that is not running, this field is null.

401: API Key authentication failed.

403: API Key lacks permission to access the requested resource.

404: Deployment not found.

429: Request limit exceeded.

Request Example

curl -u key:secret -X GET {api}/deployments/w41b11c0

Response Example

{
    "connections": 1000,
    "tps": 1000,
    "createAt": "2024-07-22 05:32",
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "deploymentType": "dedicated",
    "platform": "AWS",
    "region": "N. Virginia (us-east-1)",
    "status": "running",
    "connection": {
        "address": "mqtt.example.com",
        "ports": [
            {"protocol": "mqtt", "port": 1883, "status": "running"},
            {"protocol": "mqtts", "port": 8883, "status": "running"},
            {"protocol": "ws", "port": 8083, "status": "running"},
            {"protocol": "wss", "port": 8084, "status": "running"}
        ],
        "apiEndpoint": "https://mqtt.example.com:8443/api/v5"
    }
}

The addresses and ports above are examples. Use the values returned for your deployment, and connect only to ports whose status is running.

For a deployment that is not running, the response includes "connection": null:

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "status": "stopped",
    "connection": null
}

Create a Deployment API Key

Use a Platform API Key to create a Deployment API Key for a running Dedicated or Dedicated Flex deployment. This operation is not available for Serverless deployments or deployments that are not running.

The Platform API Key must have the Deployment_API_Key permission and access to the target project. The target deployment must belong to the account associated with the Platform API Key. A deployment can have up to 5 Deployment API Keys. Each Platform API Key is limited to 2 successful Deployment API Key creations per hour.

URI

POST /deployments/{deployment_id}/applications

{deployment_id} is the deployment ID, not the deployment name.

Request Message

The request body is optional. If you provide a body, use application/json and include the whitelist field.

Name	Type	Required	Description
whitelist	Object	Required when a body is provided	Deployment API permissions represented as a mapping of API paths to arrays of allowed HTTP methods. Each specified HTTP method must be available for its corresponding API path in the deployment.
description	String or null	No	Key description, up to 128 characters. Defaults to an empty string when omitted.

For example, "/api/v5/clients": ["GET"] grants permission only to list clients. You can specify different methods for different paths in the same whitelist. Permissions not listed are not granted to the new key. Grant only the permissions needed, based on those available to the deployment.

Important Notice

If you omit the request body, the new key receives all API permissions available to the deployment. An empty JSON object {} is not equivalent to an omitted body and is rejected. Requests with an invalid whitelist or an incorrect Content-Type are also rejected without creating a key.

Response Messages

• 201: Created successfully.

Name	Type	Description
appID	String	App ID (AK) of the new Deployment API Key.
appSecret	String	App Secret (SK) of the new Deployment API Key, returned only at creation.

• 400: The deployment type or status does not support this operation, a requested permission is unavailable, or the deployment has reached its key limit.
• 401: Platform API Key authentication failed.
• 403: The Platform API Key lacks the Deployment_API_Key permission or access to the target project.
• 404: Deployment not found.
• 415: The request body's media type is not supported.
• 422: Invalid request parameters or body.
• 429: Request limit exceeded.

Request Example

This example creates a key that can list clients and list or create users in the built-in database. Before running the command, set the environment variables to the Platform API endpoint, Platform API Key credentials, and target deployment ID.

curl --user "$PLATFORM_API_KEY:$PLATFORM_API_SECRET" \
  -X POST "$PLATFORM_API_ENDPOINT/deployments/$DEPLOYMENT_ID/applications" \
  -H "Content-Type: application/json" \
  -d '{
    "whitelist": {
      "/api/v5/clients": ["GET"],
      "/api/v5/authentication/password_based:built_in_database/users": ["GET", "POST"]
    },
    "description": "Application API access"
  }'

Set PLATFORM_API_ENDPOINT to the Platform API endpoint that ends with /public_api/v1. The /api/v5/ paths in this example are available only when supported by the target deployment. Available paths and methods vary by deployment.

Response Example

{
  "appID": "example-app-id",
  "appSecret": "example-app-secret"
}

Store appSecret securely because you cannot retrieve its plaintext value after creation. The new key appears in the Console, and audit logs do not expose the secret. To call the Deployment API, use connection.apiEndpoint from the deployment details and authenticate with appID and appSecret through HTTP Basic Authentication. Do not use the Platform API Key to call the Deployment API.

Stop Deployment

URI

POST /deployments/{deployment_id}/stop

TIP

This method can only be requested 5 times within 60 minutes. {deployment_id} refers to the deployment ID, not the deployment name. This action is only available for dedicated deployments.

Request Message

None

Response Messages

• 201:

Name	Type	Description
deploymentID	String	The unique deployment ID.
deploymentName	String	The name of the deployment.
operation	String	The type of operation: "stopping" indicates a stop operation.

• 401: API Key authentication failed.
• 403: API Key lacks permission to access the requested resource.
• 404: Deployment not found.
• 422: Invalid request parameters.
• 429: Request limit exceeded.

Request Example

curl -u key:secret -X POST {api}/deployments/w41b11c0/stop

Response Example

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "stopping"
}

Start Deployment

URI

POST /deployments/{deployment_id}/start

TIP

This method can only be requested 5 times within 60 minutes. {deployment_id} refers to the deployment ID, not the deployment name. This action is only available for dedicated deployments.

Request Message

None

Response Messages

• 201:

Name	Type	Description
deploymentID	String	The unique deployment ID.
deploymentName	String	The name of the deployment.
operation	String	The type of operation: "starting" indicates a start operation.

• 401: API Key authentication failed.
• 403: API Key lacks permission to access the requested resource.
• 404: Deployment not found.
• 422: Invalid request parameters.
• 429: Request limit exceeded.

Request Example

curl -u key:secret -X POST {api}/deployments/w41b11c0/start

Response Example

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "starting"
}

Create Deployment

URI

POST /deployments

TIP

Each Platform API Key can successfully create up to 2 deployments per hour. The deployment will be created in the default project and billed on an hourly basis. EMQX v5 and v6 deployments are supported.

Request Message

Name	Type	Required	Description
platform	String	Yes	The cloud platform where the deployment is hosted.
region	String	Yes	The region where the deployment will be created.
connections	Number	Yes	The number of connections for the deployment. Serverless deployments support 1,000 connections, while dedicated deployments support between 1,000 and 10,000 connections.
tps	Number	Yes	The number of transactions per second (TPS) for the deployment.
deploymentType	String	Yes	The deployment plan. Must be either "serverless" or "dedicatedFlex".
deploymentName	String	No	The name of the deployment. If omitted, the system generates a default name.
deploymentVersion	String	Yes	The deployment version. Supported values are "v5" and "v6".
projectID	String	Yes	The project ID. Can be obtained via the project list.
freeTrial	Boolean	Yes	Whether the deployment is a free trial. Must be set to false.

For supported cloud providers and regions by plan, see Cloud Providers and Regions.

Different deployment editions support different connection numbers and TPS specifications.

Connections	TPS
1,000	1,000

Connections	TPS
1,000	1,000
2,000	2,000
5,000	10,000
10,000	20,000

Response Messages

• 201:

Name	Type	Description
createAt	String	The creation time of the deployment.
deploymentID	String	The unique deployment ID.
deploymentName	String	The name of the deployment.
deploymentType	String	The type of deployment (either "dedicatedFlex" or "serverless").
platform	String	The cloud platform identifier.
ports	Object	Port configurations for different protocols (MQTT, WebSocket, etc.).
projectID	String	The ID of the project to which this deployment belongs.
region	String	The cloud region identifier.
regionLabel	String	The human-readable name of the region.
spec	Object	Deployment specifications, including connections, version, etc.
status	String	The current status of the deployment (running, stopped, pending).
subscription	Boolean	Whether this deployment is subscription-based.
userID	String	The ID of the user who owns this deployment.

• 400: Bad Request
• 401: API Key authentication failed.
• 403: API Key lacks permission to access the requested resource.
• 422: Invalid request parameters.
• 429: The Platform API Key has reached the limit of 2 successful deployment creations per hour.

Request Example

curl -u key:secret -X POST {api}/deployments \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "aws",
    "region": "us-east-1",
    "connections": 1000,
    "tps": 1000,
    "deploymentType": "dedicatedFlex",
    "deploymentVersion": "v5",
    "projectID": "00000001",
    "freeTrial": false
  }'

Response Example

{
    "createAt": "2025-04-17 15:30",
    "deploymentID": "i9d0961f",
    "deploymentName": "deployment-i9d0961f",
    "deploymentType": "dedicatedFlex",
    "platform": "aws",
    "ports": {
        "1883": {
            "status": "running",
            "protocol": "mqtt"
        },
        "8083": {
            "status": "running",
            "protocol": "ws"
        },
        "8084": {
            "status": "running",
            "protocol": "wss"
        },
        "8883": {
            "status": "running",
            "protocol": "mqtts"
        }
    },
    "projectID": "00000001",
    "region": "us-east-1",
    "regionLabel": "N. Virginia (us-east-1)",
    "spec": {
        "connections": 1000,
        "deploymentVersion": "v5",
        "freeTraffic": 100,
        "node": 2,
        "protection": false,
        "tps": 1000,
        "version": 5.2
    },
    "status": "pending",
    "subscription": false,
    "tls": null,
    "userID": "00000001"
}