Manage deployments using the Elastic Cloud API

This page shows examples of managing deployments through the deployments API, including listing deployments, getting deployment details, and creating or updating deployments.

For update workflows, the deployments API also provides dedicated operations for certain use cases, such as upgrades or Elasticsearch tier sizing changes.

If you haven’t created an API key yet, then refer to Elastic Cloud API keys.

Common operations with dedicated endpoints

For common update tasks, use the dedicated deployment operation that matches the change you need.

Dedicated operations let you update only the intended setting without submitting the full deployment resource specification. This simplifies common update workflows and helps reduce the risk of unintended changes to unrelated deployment settings.

Task	Endpoints
Upgrade a deployment to a newer Elastic Stack version	Upgrade deployment
Manage user settings of the deployment	Get deployment resource user settings Update deployment resource user settings
Scale Elasticsearch tiers by updating memory size and zone count	Get deployment Elasticsearch tiers Update deployment Elasticsearch tiers
Attach another deployment’s built-in snapshot repository (`found-snapshots`) for cross-deployment snapshot access and restore workflows	Attach snapshots from a source deployment List attached snapshot repositories Detach an attached snapshot repository
Manage deployment tags	Get the tags for a deployment Set the tags for a deployment

Use the generic Update deployment endpoint when you need to apply broader plan changes that affect multiple resources in one request.

Listing your deployments

List the details about all of your Elastic Cloud Hosted deployments.

		curl \
-H "Authorization: ApiKey $EC_API_KEY" \
https://api.elastic-cloud.com/api/v1/deployments
		
	

Getting details about a particular deployment

List the details about a particular deployment identified by id.

		curl \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID"
		
	

Using the API to create your first deployment

When you create a new deployment through the API, you have two options:

Use default values. The simplest option is to create the deployment using a set of default values that are gathered automatically from a deployment template specified in the API request.
Configure the deployment settings manually. With this option, the API request to create a new deployment is very descriptive, with many settings to tweak. If you use this option we recommend that you configure your desired deployment in the Elastic Cloud UI and copy the JSON payload.

Create a deployment using default values

This example requires minimal information in the API payload, and creates a deployment with default settings and a default name. You just need to specify one of the available deployment templates in your API request header and the deployment is created using default settings from that template.

		curl -XPOST \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/deployments?template_id=gcp-general-purpose" \
-d '
{
  "version": "9.4.1",<1>
  "region": "gcp-europe-west1"<2>
}
'
		
	

Optional: You can specify a version for the deployment. If this field is omitted a default version is used.
Required: One of the available regions must be provided in the request.

A resource field can be included in this request (check the following, manual example for the field details). When a resource is present, the content of the request is used instead of any default values provided by the deployment template.

Create a deployment

This example creates a new deployment named "my-first-api-deployment" with the following characteristics:

Version 9.4.1 of the Elastic Stack
Elasticsearch cluster in two zones with 4 GB of memory for each node
2 GB single zone Kibana instance and 1 GB Integrations Server instance

		curl -XPOST \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/deployments" \
-d '
{
  "resources": {
    "elasticsearch": [
      {
        "region": "gcp-us-central1",
        "ref_id": "main-elasticsearch",
        "plan": {
          "cluster_topology": [
            {
              "zone_count": 2,
              "elasticsearch": {
                "node_attributes": {
                  "data": "hot"
                }
              },
              "instance_configuration_id": "gcp.es.datahot.n2.68x16x45",
              "node_roles": [
                "master",
                "ingest",
                "transform",
                "data_hot",
                "remote_cluster_client",
                "data_content"
              ],
              "id": "hot_content",
              "size": {
                "value": 4096,
                "resource": "memory"
              }
            },
            {
              "zone_count": 2,
              "elasticsearch": {
                "node_attributes": {
                  "data": "warm"
                }
              },
              "instance_configuration_id": "gcp.es.datawarm.n2.68x10x190",
              "node_roles": [
                "data_warm",
                "remote_cluster_client"
              ],
              "id": "warm",
              "size": {
                "resource": "memory",
                "value": 0
              }
            },
            {
              "zone_count": 1,
              "elasticsearch": {
                "node_attributes": {
                  "data": "cold"
                }
              },
              "instance_configuration_id": "gcp.es.datacold.n2.68x10x190",
              "node_roles": [
                "data_cold",
                "remote_cluster_client"
              ],
              "id": "cold",
              "size": {
                "resource": "memory",
                "value": 0
              }
            },
            {
              "zone_count": 1,
              "elasticsearch": {
                "node_attributes": {
                  "data": "frozen"
                }
              },
              "instance_configuration_id": "gcp.es.datafrozen.n2.68x10x90",
              "node_roles": [
                "data_frozen"
              ],
              "id": "frozen",
              "size": {
                "resource": "memory",
                "value": 0
              }
            },
            {
              "zone_count": 3,
              "instance_configuration_id": "gcp.es.master.n2.68x32x45",
              "node_roles": [
                "master",
                "remote_cluster_client"
              ],
              "id": "master",
              "size": {
                "resource": "memory",
                "value": 0
              }
            },
            {
              "zone_count": 2,
              "instance_configuration_id": "gcp.es.coordinating.n2.68x16x45",
              "node_roles": [
                "ingest",
                "remote_cluster_client"
              ],
              "id": "coordinating",
              "size": {
                "resource": "memory",
                "value": 0
              }
            },
            {
              "zone_count": 1,
              "instance_configuration_id": "gcp.es.ml.n2.68x32x45",
              "node_roles": [
                "ml",
                "remote_cluster_client"
              ],
              "id": "ml",
              "size": {
                "resource": "memory",
                "value": 0
              }
            }
          ],
          "elasticsearch": {
            "version": "9.4.1",
            "enabled_built_in_plugins": []
          },
          "deployment_template": {
            "id": "gcp-us-central1"
          }
        }
      }
    ],
    "kibana": [
      {
        "elasticsearch_cluster_ref_id": "main-elasticsearch",
        "region": "gcp-us-central1",
        "plan": {
          "cluster_topology": [
            {
              "instance_configuration_id": "gcp.kibana.n2.68x32x45",
              "zone_count": 1,
              "size": {
                "resource": "memory",
                "value": 2048
              }
            }
          ],
          "kibana": {
            "version": "9.4.1"
          }
        },
        "ref_id": "main-kibana"
      }
    ],
    "integrations_server": [
      {
        "elasticsearch_cluster_ref_id": "main-elasticsearch",
        "region": "gcp-us-central1",
        "plan": {
          "cluster_topology": [
            {
              "instance_configuration_id": "gcp.integrationsserver.n2.68x32x45",
              "zone_count": 1,
              "size": {
                "resource": "memory",
                "value": 1024
              }
            }
          ],
          "integrations_server": {
            "version": "9.4.1"
          }
        },
        "ref_id": "main-integrations_server"
      }
    ]
  },
  "name": "my-first-api-deployment"
}
'
		
	

Available Regions
Availability zones for the Elasticsearch cluster
Available instance configurations
Memory allocated for each Elasticsearch node
Available templates
Availability zones for Kibana
Memory allocated for Kibana
Availability zones for Integrations Server
Memory allocated for Integrations Server

Tip

You can get the payload easily from the Elastic Cloud Console Create Deployment page, customize the regions, zones, memory allocated for each components, and then select Equivalent API request.

Using the API to create deployment with non EOL versions

You are able to create deployments with non End-of-life (EOL) versions via API, which are not selectable in the Elastic Cloud Console UI. You can simply replace the version number in the above example.

Update a deployment

Use the Update deployment endpoint when you need to apply broader plan changes that affect multiple resources or settings in one request. For some specific update tasks, use the dedicated deployment operations listed in Common operations with dedicated endpoints.

This example modifies the Elasticsearch resource by increasing the amount of memory to 8 GB.

		curl -XPUT \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID" \
-d '
{
  "name": "my-first-api-deployment-with-new-name",
  "prune_orphans": false,
  "resources": {
    "elasticsearch": [
      {
        "region": "gcp-us-central1",
        "ref_id": "main-elasticsearch",
        "plan": {
          "cluster_topology": [
            {
              "zone_count": 2,
              "elasticsearch": {
                "node_attributes": {
                  "data": "hot"
                }
              },
              "instance_configuration_id": "gcp.es.datahot.n2.68x16x45",
              "node_roles": [
                "data_hot",
                "data_content",
                "master",
                "ingest",
                "remote_cluster_client",
                "transform"
              ],
              "id": "hot_content",
              "size": {
                "value": 8192,
                "resource": "memory"
              }
            }
          ],
          "elasticsearch": {
            "version": "9.4.1"
          },
          "deployment_template": {
            "id": "gcp-us-central1"
          }
        }
      }
    ]
  }
}
'
		
	

Give the deployment a new name
Increase the amount of memory allocated for each Elasticsearch node to 8 GB

A 200 status code means that the configuration change was accepted.

Tip

You can get the payload easily from the Elastic Cloud Console deployment Edit page, customize the zone count, memory allocated for each components, and then select Equivalent API request.