# 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 ```bash curl -u key:secret -X GET {api}/deployments ``` ### Response Example ```json [ { "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 ```bash curl -u key:secret -X GET {api}/deployments/w41b11c0 ``` ### Response Example ```json { "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 ```bash curl -u key:secret -X POST {api}/deployments/w41b11c0/stop ``` ### Response Example ```json { "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 ```bash curl -u key:secret -X POST {api}/deployments/w41b11c0/start ``` ### Response Example ```json { "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. | | tps | Number | No | he number of transactions per second (TPS) for the deployment.| | deploymentType | String | Yes | The deployment plan. Must be either "serverless" or "dedicated". | ::: warning 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) ::: ::: tip 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. :::: tabs ::: tab Serverless Edition | Connections | TPS | |-------------|----------| | 1,000 | 1,000 | ::: ::: tab Dedicated Edition | 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 ```bash 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": "dedicated" }' ``` ### Response Example ```json { "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" } ```