« Deployment - CRUD Deployment - Info »
Elastic Docs ›Elasticsearch Service Documentation ›RESTful API ›API reference documentation

Deployment - Commands

edit

Deployment - Commands

edit

Search Deployments

edit

Retrieves the information for all of the deployments that match the specified query.

Request

edit

POST /api/v1/deployments/_search

Query parameters

edit
Name Type Required Description

minimal_metadata

string

N

Comma separated list of attributes to include in response for deployments found. Useful for reducing response size when retrieving many deployments. Use of this parameter moves the result to the minimal_metadata section of the response.

Request body

edit

(SearchRequest) (Optional) The search query to run. When not specified, all of the deployments are matched.

Responses

edit
200

(DeploymentsSearchResponse)

The list of deployments that match the specified query and belong to the authenticated user.

Headers

x-cloud-resource-created (string)
The date-time when the resource was created (ISO format relative to UTC)
x-cloud-resource-last-modified (string)
The date-time when the resource was last modified (ISO format relative to UTC)
x-cloud-resource-version (string)
The resource version, which is used to avoid update conflicts with concurrent operations

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/_search \
-H "Authorization: ApiKey $EC_API_KEY" \
-H 'Content-Type: application/json' \
-d '
{
   "cursor" : "string",
   "from" : 0,
   "query" : {
      "bool" : {
         "filter" : [
            null
         ],
         "minimum_should_match" : 0,
         "must" : [
            null
         ],
         "must_not" : [
            null
         ],
         "should" : [
            null
         ]
      },
      "exists" : {
         "field" : "string"
      },
      "match" : {
         "some_property" : {
            "analyzer" : "string",
            "minimum_should_match" : 0,
            "operator" : "string",
            "query" : "string"
         }
      },
      "match_all" : {},
      "match_none" : {},
      "nested" : {
         "path" : "string",
         "query" : null,
         "score_mode" : "string"
      },
      "prefix" : {
         "some_property" : {
            "boost" : 0.1,
            "value" : "string"
         }
      },
      "query_string" : {
         "allow_leading_wildcard" : true,
         "analyzer" : "string",
         "default_field" : "string",
         "default_operator" : "string",
         "query" : "string"
      },
      "range" : {
         "some_property" : {
            "boost" : 0.1,
            "format" : "string",
            "gt" : {},
            "gte" : {},
            "lt" : {},
            "lte" : {},
            "time_zone" : "string"
         }
      },
      "simple_query_string" : {
         "analyze_wildcard" : true,
         "analyzer" : "string",
         "auto_generate_synonyms_phrase_query" : true,
         "default_operator" : "string",
         "fields" : [
            "string"
         ],
         "flags" : "string",
         "fuzzy_max_expansions" : 0,
         "fuzzy_prefix_length" : 0,
         "fuzzy_transpositions" : true,
         "lenient" : true,
         "minimum_should_match" : "string",
         "query" : "string",
         "quote_field_suffix" : "string"
      },
      "term" : {
         "some_property" : {
            "value" : "string"
         }
      }
   },
   "size" : 0,
   "sort" : [
      {}
   ]
}
'

Migrate Elasticsearch and associated Kibana resources to enable CCR

edit

Migrates the specified Elasticsearch resource and its associated Kibana to enable CCR (if supported).

Request

edit

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_enable-ccr

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

Query parameters

edit
Name Type Required Description

validate_only

boolean; default: false

N

When true, will not enable CCR but returns warnings if any elements may lose availability during CCR enablement

Responses

edit
200

(DeploymentResourceCommandResponse)

Standard response

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_enable-ccr \
-H "Authorization: ApiKey $EC_API_KEY"

Migrate Elasticsearch resource to use ILM

edit

Migrates the specified Elasticsearch resource to use ILM.

Request

edit

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_enable-ilm

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

Query parameters

edit
Name Type Required Description

validate_only

boolean; default: false

N

When true, does not enable ILM but returns warnings if any applications may lose availability during ILM migration.

Request body

edit

(EnableIlmRequest) (required) Information to build the ILM policies that will be created

Responses

edit
200

(DeploymentResourceCommandResponse)

Standard response

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
500

(BasicFailedReply)

We have failed you. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_enable-ilm \
-H "Authorization: ApiKey $EC_API_KEY" \
-H 'Content-Type: application/json' \
-d '
{
   "index_patterns" : [
      {
         "index_pattern" : "string",
         "node_attributes" : {
            "some_property" : "string"
         },
         "policy_name" : "string"
      }
   ]
}
'

Migrate Elasticsearch resource to use SLM

edit

Migrates the specified Elasticsearch resource to use SLM.

Request

edit

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_enable-slm

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

Query parameters

edit
Name Type Required Description

validate_only

boolean; default: false

N

When true, does not enable SLM but returns warnings if any applications may lose availability during SLM migration.

Responses

edit
200

(DeploymentResourceCommandResponse)

Standard response

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
500

(BasicFailedReply)

We have failed you. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_enable-slm \
-H "Authorization: ApiKey $EC_API_KEY"

Reset elastic user password

edit

Resets the password of the 'elastic' user.

Request

edit

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_reset-password

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

Query parameters

edit
Name Type Required Description

check_completion

boolean; default: false

N

If true, will not reset elastic user password and instead will return a status code signaling whether or not the current credentials are ready to use (eg from creation or the last call to _reset_password)

Responses

edit
200

(ElasticsearchElasticUserPasswordResetResponse)

The password reset was out carried successfully

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
500

(BasicFailedReply)

Failed to reset the 'elastic' user's password. (code: deployments.elasticsearch.password_reset_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.elasticsearch.password_reset_error])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_reset-password \
-H "Authorization: ApiKey $EC_API_KEY"

Restart Deployment Elasticsearch Resource

edit

Restarts an Elasticsearch Resource. If a Resource is active: this command re-applies the existing plan but applies a "cluster_reboot", which issues a restart command and waits for it to complete. If a Resource is inactive: this command starts it up with the most recent successful plan.

Request

edit

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_restart

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

Query parameters

edit
Name Type Required Description

cancel_pending

boolean; default: false

N

If true, cancels any pending plans before restarting. If false and there are pending plans, returns an error.

group_attribute

string; default: "__zone__"

N

Indicates the property or properties used to divide the list of instances to restart in groups. Valid options are: '__all__' (restart all at once), '__zone__' by logical zone, '__name__' one instance at a time, or a comma-separated list of attributes of the instances

restore_snapshot

boolean; default: true

N

When set to true and restoring from shutdown, then will restore the cluster from the last snapshot (if available).

shard_init_wait_time

integer; default: 600

N

The time, in seconds, to wait for shards that show no progress of initializing, before rolling the next group (default: 10 minutes)

skip_snapshot

boolean; default: true

N

If true, will not take a snapshot of the cluster before restarting.

Responses

edit
202

(DeploymentResourceCommandResponse)

The restart command was issued successfully.

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
422

(BasicFailedReply)

The command sent to a Resource found the Resource in an illegal state, the error message gives more details. (code: deployments.deployment_resource_plan_change_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_plan_change_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_restart \
-H "Authorization: ApiKey $EC_API_KEY"

Shutdown Deployment Elasticsearch Resource

edit

Shutdown Elasticsearch Resource belonging to a given Deployment.

Request

edit

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_shutdown

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

Query parameters

edit
Name Type Required Description

hide

boolean

N

Hide cluster on shutdown. Hidden clusters are not listed by default. Only applicable for Platform administrators.

skip_snapshot

boolean; default: false

N

If true, will skip taking a snapshot of the cluster before shutting the cluster down (if even possible).

Responses

edit
200

(DeploymentResourceCommandResponse)

Standard response.

400

(BasicFailedReply)

Parameter is restricted and can only be set by a Platform administrator. (code: deployments.restricted_parameter)

Headers

x-cloud-error-codes (string; allowed values: [deployments.restricted_parameter])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_shutdown \
-H "Authorization: ApiKey $EC_API_KEY"

Start all instances

edit

Starts all instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/_start

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Responses

edit
202

(DeploymentResourceCommandResponse)

The start command was issued successfully.

403

(BasicFailedReply)

The start maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/_start \
-H "Authorization: ApiKey $EC_API_KEY"

Stop all instances

edit

Stops all instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/_stop

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Responses

edit
202

(DeploymentResourceCommandResponse)

The stop command was issued successfully.

403

(BasicFailedReply)

The stop maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/_stop \
-H "Authorization: ApiKey $EC_API_KEY"

Start maintenance mode (all instances)

edit

Starts maintenance mode of all instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/maintenance-mode/_start

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Responses

edit
202

(DeploymentResourceCommandResponse)

The start maintenance command was issued successfully.

403

(BasicFailedReply)

The start maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/maintenance-mode/_start \
-H "Authorization: ApiKey $EC_API_KEY"

Stop maintenance mode (all instances)

edit

Stops maintenance mode of all instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/maintenance-mode/_stop

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Responses

edit
202

(DeploymentResourceCommandResponse)

The stop maintenance mode command was issued successfully.

403

(BasicFailedReply)

The stop maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/maintenance-mode/_stop \
-H "Authorization: ApiKey $EC_API_KEY"

Start instances

edit

Starts instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/_start

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

instance_ids

array[string]

Y

A comma-separated list of instance identifiers.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Query parameters

edit
Name Type Required Description

ignore_missing

boolean; default: false

N

If true and the instance does not exist then quietly proceed to the next instance, otherwise treated as an error

Responses

edit
202

(DeploymentResourceCommandResponse)

The start command was issued successfully.

403

(BasicFailedReply)

The start maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/_start \
-H "Authorization: ApiKey $EC_API_KEY"

Stop instances

edit

Stops instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/_stop

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

instance_ids

array[string]

Y

A comma-separated list of instance identifiers.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Query parameters

edit
Name Type Required Description

ignore_missing

boolean; default: false

N

If true and the instance does not exist then quietly proceed to the next instance, otherwise treated as an error.

Responses

edit
202

(DeploymentResourceCommandResponse)

The stop command was issued successfully.

403

(BasicFailedReply)

The start maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/_stop \
-H "Authorization: ApiKey $EC_API_KEY"

Start maintenance mode

edit

Starts maintenance mode of instances belonging to a Deployment Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/maintenance-mode/_start

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

instance_ids

array[string]

Y

A comma-separated list of instance identifiers.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Query parameters

edit
Name Type Required Description

ignore_missing

boolean; default: false

N

If true and the instance does not exist then quietly proceed to the next instance, otherwise treated as an error.

Responses

edit
202

(DeploymentResourceCommandResponse)

The start maintenance command was issued successfully.

403

(BasicFailedReply)

The start maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/maintenance-mode/_start \
-H "Authorization: ApiKey $EC_API_KEY"

Stop maintenance mode

edit

Stops maintenance mode of instances belonging to a Resource.

Request

edit

POST /api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/maintenance-mode/_stop

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

instance_ids

array[string]

Y

A comma-separated list of instance identifiers.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

resource_kind

string

Y

The kind of resource (one of elasticsearch, kibana, apm, or integrations_server).

Query parameters

edit
Name Type Required Description

ignore_missing

boolean; default: false

N

If true and the instance does not exist then quietly proceed to the next instance, otherwise treated as an error.

Responses

edit
202

(DeploymentResourceCommandResponse)

The stop maintenance mode command was issued successfully.

403

(BasicFailedReply)

The stop maintenance mode command was prohibited for the given Resource. (code: deployments.instance_update_prohibited_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.instance_update_prohibited_error])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)
  • One or more instances of the given resource type are missing. (code: deployments.instances_missing_on_update_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found, deployments.instances_missing_on_update_error])
The error codes associated with the response
500

(BasicFailedReply)

A Resource that was previously stored no longer exists. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{resource_kind}/{ref_id}/instances/{instance_ids}/maintenance-mode/_stop \
-H "Authorization: ApiKey $EC_API_KEY"

Restart Deployment Stateless Resource

edit

Restarts a Stateless Resource. If a Resource is active: this command re-applies the existing plan but applies a "cluster_reboot", which issues a restart command and waits for it to complete. If a Resource is inactive: this command starts it up with the most recent successful plan.

Request

edit

POST /api/v1/deployments/{deployment_id}/{stateless_resource_kind}/{ref_id}/_restart

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

stateless_resource_kind

string; allowed values: [kibana, apm, appsearch, enterprise_search, integrations_server]

Y

The kind of stateless resource

Query parameters

edit
Name Type Required Description

cancel_pending

boolean; default: false

N

If true, cancels any pending plans before restarting. If false and there are pending plans, returns an error.

Responses

edit
202

(DeploymentResourceCommandResponse)

The restart command was issued successfully

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
422

(BasicFailedReply)

The command sent to a Resource found the Resource in an illegal state, the error message gives more details. (code: deployments.deployment_resource_plan_change_error)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_plan_change_error])
The error codes associated with the response
500

(BasicFailedReply)

We have failed you. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{stateless_resource_kind}/{ref_id}/_restart \
-H "Authorization: ApiKey $EC_API_KEY"

Shutdown Deployment Stateless Resource

edit

Shut down Stateless Resource belonging to a given Deployment. Kibana cannot be shut down on Elasticsearch Service as it is required for Elasticsearch administrative functions, such as Snapshot Lifecycle Management and version upgrades.

Request

edit

POST /api/v1/deployments/{deployment_id}/{stateless_resource_kind}/{ref_id}/_shutdown

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

stateless_resource_kind

string; allowed values: [kibana, apm, appsearch, enterprise_search, integrations_server]

Y

The kind of stateless resource

Query parameters

edit
Name Type Required Description

hide

boolean

N

Hide cluster on shutdown. Hidden clusters are not listed by default. Only applicable for Platform administrators.

skip_snapshot

boolean; default: false

N

If true, will skip taking a snapshot of the cluster before shutting the cluster down (if even possible)

Responses

edit
200

(DeploymentResourceCommandResponse)

Standard response

400

(BasicFailedReply)

Parameter is restricted and can only be set by a Platform administrator. (code: deployments.restricted_parameter)

Headers

x-cloud-error-codes (string; allowed values: [deployments.restricted_parameter])
The error codes associated with the response
404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response
500

(BasicFailedReply)

We have failed you. (code: deployments.deployment_resource_no_longer_exists)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_resource_no_longer_exists])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{stateless_resource_kind}/{ref_id}/_shutdown \
-H "Authorization: ApiKey $EC_API_KEY"

Upgrade Kibana, APM, Integrations Server, AppSearch, Enterprise Search inside Deployment

edit

Upgrades a running cluster.

Request

edit

POST /api/v1/deployments/{deployment_id}/{stateless_resource_kind}/{ref_id}/_upgrade

Path parameters

edit
Name Type Required Description

deployment_id

string

Y

Identifier for the Deployment.

ref_id

string

Y

User-specified RefId for the Resource (or '_main' if there is only one).

stateless_resource_kind

string; allowed values: [kibana, apm, appsearch, enterprise_search, integrations_server]

Y

The kind of stateless resource

Query parameters

edit
Name Type Required Description

validate_only

boolean; default: false

N

When true, returns the update version without performing the upgrade

Responses

edit
202

(DeploymentResourceUpgradeResponse)

The upgrade command was issued successfully. Use the "GET" command on the /{deployment_id} resource to monitor progress

404

(BasicFailedReply)

  • The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
  • The Resource specified by {ref_id} cannot be found. (code: deployments.deployment_resource_not_found)

Headers

x-cloud-error-codes (string; allowed values: [deployments.deployment_not_found, deployments.deployment_resource_not_found])
The error codes associated with the response

Request example

edit
curl -XPOST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/{stateless_resource_kind}/{ref_id}/_upgrade \
-H "Authorization: ApiKey $EC_API_KEY"
« Deployment - CRUD Deployment - Info »