Deployment Management API

This page describes how to use the API to retrieve a deployment list, query deployment status, start and stop deployments, and create new deployments.

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.
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, and "dedicated" for dedicated 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,
        "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,
        "createAt": "2025-04-17 08:36",
        "deploymentID": "b1f77113",
        "deploymentName": "deployment-b1f77113",
        "deploymentType": "dedicated",
        "platform": "AWS",
        "projectName": "test",
        "region": "N. Virginia (us-east-1)",
        "status": "running",
        "version": "v5"
    }
]

View Status of a Specific Deployment

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

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,
    "createAt": "2024-07-22 05:32",
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "deploymentType": "dedicated",
    "platform": "AWS",
    "region": "N. Virginia (us-east-1)",
    "status": "running"
}

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

This method can only be requested once within 60 minutes. The deployment will be created in the default project. Currently, only v5 versions of EMQX 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.
deploymentType	String	Yes	The deployment plan. Must be either "serverless" or "dedicated".

Serverless Deployment Support

Serverless deployments are currently only supported in the following platforms and regions:

• AWS: North America (us-east-1), Europe (eu-central-1)
• Google Cloud: Asia–Pacific (asia-southeast1)

Supported Platforms and Regions

Here is the list of supported platforms, regions, and their deployment types:

Cloud Platform	Platform Code	Region Name	Region Code	Serverless Support	Dedicated Support
AWS	aws	N. Virginia	us-east-1	✅	✅
		Ohio	us-east-2		✅
		N. California	us-west-1		✅
		Oregon	us-west-2		✅
		Ireland	eu-west-1		✅
		London	eu-west-2		✅
		Frankfurt	eu-central-1	✅	✅
		Singapore	ap-southeast-1		✅
		Mumbai	ap-south-1		✅
		Hong Kong	ap-east-1		✅
		Tokyo	ap-northeast-1		✅
		Sydney	ap-southeast-2		✅
Azure	azure	East US	eastus		✅
		West US 2	westus2		✅
		West US 3	westus3		✅
		West Europe	westeurope		✅
		Germany West Central	germanywestcentral		✅
		North Europe	northeurope		✅
		Southeast Asia	southeastasia		✅
		Japan East	japaneast		✅
Google Cloud	gcp	South Carolina	us-east1		✅
		Oregon	us-west1		✅
		Iowa	us-central1		✅
		Frankfurt	europe-west3		✅
		Finland	europe-north1		✅
		Mumbai	asia-south1		✅
		Singapore	asia-southeast1	✅	✅
		Taiwan	asia-east1		✅
		Tokyo	asia-northeast1		✅

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 "dedicated" or "serverless").
freeTrial	Boolean	Whether the deployment is a free trial.
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 (null for default project).
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.

Request Example

curl -u key:secret -X POST {api}/deployments \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "aws",
    "region": "us-east-1",
    "connections": 1000,
    "deploymentType": "dedicated"
  }'

Response Example

{
    "createAt": "2025-04-17 15:30",
    "deploymentID": "i9d0961f",
    "deploymentName": "deployment-i9d0961f",
    "deploymentType": "dedicated",
    "freeTrial": false,
    "platform": "aws",
    "ports": {
        "1883": {
            "status": "running",
            "protocol": "mqtt"
        },
        "8083": {
            "status": "running",
            "protocol": "ws"
        },
        "8084": {
            "status": "running",
            "protocol": "wss"
        },
        "8883": {
            "status": "running",
            "protocol": "mqtts"
        }
    },
    "projectID": null,
    "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"
}