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

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

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

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 and billed on an hourly basis. Currently, 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.

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