Elastic Stack (ELK Stack) Deployments API

openapi: 3.2.0
info:
  version: '1'
  title: Elastic Cloud Enterprise Deployments API
  termsOfService: ''
servers:
- url: https://{{hostname}}/api/v1
security:
- basicAuth: []
- apiKey: []
tags:
- name: Deployments
paths:
  /deployments:
    get:
      tags:
      - Deployments
      summary: List Deployments
      description: List Deployments.
      operationId: list-deployments
      responses:
        '200':
          description: The list of deployments that belong to the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentsListResponse'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
    post:
      tags:
      - Deployments
      summary: Create Deployment
      description: Creates a Deployment.
      operationId: create-deployment
      parameters:
      - name: request_id
        in: query
        description: An optional idempotency token - if two create requests share the same request_id token (min size 32 characters, max 128) then only one deployment will be created, the second request will return the info of that deployment (in the same format described below, but with blanks for auth-related fields)
        required: false
        schema:
          type: string
      - name: validate_only
        in: query
        description: If true, will just validate the Deployment definition but will not perform the creation
        required: false
        schema:
          type: boolean
          default: false
      - name: template_id
        in: query
        description: An optional template id - if present, the referenced template will be used to fill in the resources field of the deployment creation request. If any resources are present in the request together with the template, the ones coming in the request will prevail and no merging with the template will be performed.
        required: false
        schema:
          type: string
      responses:
        '201':
          description: The request was valid and a new deployment was created
          headers:
            x-cloud-resource-version:
              description: The resource version, which is used to avoid update conflicts with concurrent operations
              schema:
                type: string
            x-cloud-resource-created:
              description: The date-time when the resource was created (ISO format relative to UTC)
              schema:
                type: string
            x-cloud-resource-last-modified:
              description: The date-time when the resource was last modified (ISO format relative to UTC)
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentCreateResponse'
        '202':
          description: The request was valid and deployment creation had already been started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentCreateResponse'
        '200':
          description: The request was valid (used when validate_only is true).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentCreateResponse'
        '400':
          description: The deployment request had errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentCreateRequest'
        description: The deployment definition
        required: true
  /deployments/_resync:
    post:
      tags:
      - Deployments
      summary: Resynchronize Deployments
      description: Resynchronizes the search index for all the deployments.
      operationId: resync-deployments
      parameters:
      - name: skip_matching_version
        in: query
        description: When true, skips the document indexing when the version matches the in-memory copy.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: The deployments resync operation executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexSynchronizationResults'
        '500':
          description: 'The deployments resync operation failed. (code: `deployments.resync_failed`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.resync_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - resync
  /deployments/_search:
    post:
      tags:
      - Deployments
      summary: Search Deployments
      description: Retrieves the information for all of the deployments that match the specified query.
      operationId: search-deployments
      parameters:
      - name: minimal_metadata
        in: query
        description: 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.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The list of deployments that match the specified query and belong to the authenticated user.
          headers:
            x-cloud-resource-version:
              description: The resource version, which is used to avoid update conflicts with concurrent operations
              schema:
                type: string
            x-cloud-resource-created:
              description: The date-time when the resource was created (ISO format relative to UTC)
              schema:
                type: string
            x-cloud-resource-last-modified:
              description: The date-time when the resource was last modified (ISO format relative to UTC)
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentsSearchResponse'
      x-doc:
        tag: Deployment - Commands
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        description: (Optional) The search query to run. When not specified, all of the deployments are matched.
  /deployments/eligible-remote-clusters:
    post:
      tags:
      - Deployments
      summary: Get eligible remote clusters
      description: Returns the list of deployments which contain eligible remote clusters for a specific version.
      operationId: search-eligible-remote-clusters
      parameters:
      - name: version
        in: query
        description: The version of the Elasticsearch cluster cluster that will potentially be configured to have remote clusters.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of deployments which contains eligible remote clusters for a specific version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentsSearchResponse'
        '400':
          description: 'The provided version is invalid. (code: `stackpack.invalid_version`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - stackpack.invalid_version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - Remote Clusters
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        description: (Optional) The search query to run against all deployments containing eligible remote clusters. When not specified, all the eligible deployments are matched.
  /deployments/{deployment_id}:
    get:
      tags:
      - Deployments
      summary: Get Deployment
      description: Retrieves information about a Deployment.
      operationId: get-deployment
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      - name: show_security
        in: query
        description: Whether to include the Elasticsearch 2.x security information in the response - can be large per cluster and also include credentials
        required: false
        schema:
          type: boolean
          default: false
      - name: show_metadata
        in: query
        description: Whether to include the full cluster metadata in the response - can be large per cluster and also include credentials
        required: false
        schema:
          type: boolean
          default: false
      - name: show_plans
        in: query
        description: Whether to include the full current and pending plan information in the response - can be large per cluster
        required: false
        schema:
          type: boolean
          default: true
      - name: show_plan_logs
        in: query
        description: Whether to include with the current and pending plan information the attempt log - can be very large per cluster
        required: false
        schema:
          type: boolean
          default: false
      - name: show_plan_history
        in: query
        description: "Whether to include the plan history with the current and pending plan information. The results can be very large per cluster.\n By default, if a given resource kind (e.g. Elasticsearch, Kibana, etc.) has more than 100 plans\n (which should be very rare, most likely caused by a bug) only 100 plans are returned for the given resource type:\n The first 10 plans, and the last 90 plans for that resource type.\n If ALL of the plans are desired, pass the `force_all_plan_history` parameter with a value of `true`.\n"
        required: false
        schema:
          type: boolean
          default: false
      - name: show_plan_defaults
        in: query
        description: If showing plans, whether to show values that are left at their default value (less readable but more informative)
        required: false
        schema:
          type: boolean
          default: false
      - name: convert_legacy_plans
        in: query
        description: If showing plans, whether to leave pre-2.0.0 plans in their legacy format (the default), or whether to update them to 2.0.x+ format (if 'true')
        required: false
        schema:
          type: boolean
          default: false
      - name: show_system_alerts
        in: query
        description: Number of system alerts (such as forced restarts due to memory limits) to be included in the response - can be large per cluster. Negative numbers or 0 will not return field.
        required: false
        schema:
          type: integer
          default: 0
      - name: show_settings
        in: query
        description: Whether to show cluster settings in the response.
        required: false
        schema:
          type: boolean
          default: false
      - name: show_instance_metrics
        in: query
        description: Whether to show resources instance metrics in the response.
        required: false
        schema:
          type: boolean
          default: true
      - name: show_instance_configurations
        in: query
        description: If true, will return details for each instance configuration referenced by the deployment.
        required: false
        schema:
          type: boolean
          default: true
      - name: enrich_with_template
        in: query
        description: If showing plans, whether to enrich the plan by including the missing elements from the deployment template it is based on
        required: false
        schema:
          type: boolean
          default: true
      - name: force_all_plan_history
        in: query
        description: "Force show the entire plan history no matter how long.\n As noted in the `show_plan_history` parameter description, by default, a maximum of 100 plans are shown per resource. \n If `true`, this parameter overrides the default, and ALL plans are returned.\n Use with care as the plan history can be VERY large. Consider pairing with `show_plan_logs=false`.\n "
        required: false
        schema:
          type: boolean
          default: false
      - name: clear_transient
        in: query
        description: If set (defaults to false) then removes the transient section from all child resources, making it safe to reapply via an update
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The Deployment info response
          headers:
            x-cloud-resource-version:
              description: The resource version, which is used to avoid update conflicts with concurrent operations
              schema:
                type: string
            x-cloud-resource-created:
              description: The date-time when the resource was created (ISO format relative to UTC)
              schema:
                type: string
            x-cloud-resource-last-modified:
              description: The date-time when the resource was last modified (ISO format relative to UTC)
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentGetResponse'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
    put:
      tags:
      - Deployments
      summary: Update Deployment
      description: Updates a Deployment.
      operationId: update-deployment
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      - name: hide_pruned_orphans
        in: query
        description: Whether or not to hide orphaned resources that were shut down (relevant if prune on the request is true)
        required: false
        schema:
          type: boolean
          default: false
      - name: skip_snapshot
        in: query
        description: Whether or not to skip snapshots before shutting down orphaned resources (relevant if prune on the request is true)
        required: false
        schema:
          type: boolean
          default: false
      - name: validate_only
        in: query
        description: If true, will just validate the Deployment definition but will not perform the update
        required: false
        schema:
          type: boolean
          default: false
      - name: version
        in: query
        description: If specified then checks for conflicts against the version stored in the persistent store (returned in 'x-cloud-resource-version' of the GET request)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The request was valid and the deployment was updated.
          headers:
            x-cloud-resource-version:
              description: The resource version, which is used to avoid update conflicts with concurrent operations
              schema:
                type: string
            x-cloud-resource-created:
              description: The date-time when the resource was created (ISO format relative to UTC)
              schema:
                type: string
            x-cloud-resource-last-modified:
              description: The date-time when the resource was last modified (ISO format relative to UTC)
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentUpdateResponse'
        '400':
          description: The deployment request had errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentUpdateRequest'
        description: The deployment definition
        required: true
    delete:
      tags:
      - Deployments
      summary: Delete Deployment
      description: Deletes a Deployment and all its resources.
      operationId: delete-deployment
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request was valid and the deployment was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentDeleteResponse'
        '400':
          description: The Deployment resources have not been shutdown yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
  /deployments/{deployment_id}/_restore:
    post:
      tags:
      - Deployments
      summary: Restores a shutdown Deployment
      description: Restores all resources in a Deployment.
      operationId: restore-deployment
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      - name: restore_snapshot
        in: query
        description: Whether or not to restore a snapshot for those resources that allow it.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The request was valid and the resources of the deployment were restored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentRestoreResponse'
        '400':
          description: There are Elasticsearch resources in the deployment which are not shut down.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
  /deployments/{deployment_id}/_resync:
    post:
      tags:
      - Deployments
      summary: Resynchronize Deployment
      description: Immediately resynchronizes the search index for the selected deployment.
      operationId: resync-deployment
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The deployment resync operation executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexSynchronizationResults'
        '500':
          description: 'The deployment resync operation failed for deployment {deployment_id}. (code: `deployments.resync_failed`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.resync_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - resync
  /deployments/{deployment_id}/_shutdown:
    post:
      tags:
      - Deployments
      summary: Shuts down Deployment
      description: Shuts down all resources in a Deployment.
      operationId: shutdown-deployment
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      - name: hide
        in: query
        description: Whether or not to hide the deployment and its resources.Only applicable for Platform administrators.
        required: false
        schema:
          type: boolean
      - name: skip_snapshot
        in: query
        description: Whether or not to skip snapshots before shutting down the resources
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The request was valid and the resources of the deployment were shutdown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentShutdownResponse'
        '400':
          description: 'Parameter is restricted and can only be set by a Platform administrator. (code: `deployments.restricted_parameter`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.restricted_parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '401':
          description: You are not authorized to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - CRUD
  /deployments/{deployment_id}/apm/{ref_id}:
    get:
      tags:
      - Deployments
      summary: Get Deployment APM Resource Info
      description: Get info about an APM Resource belonging to a given Deployment.
      operationId: get-deployment-apm-resource-info
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment
        required: true
        schema:
          type: string
      - name: ref_id
        in: path
        description: User-specified RefId for the Resource (or '_main' if there is only one).
        required: true
        schema:
          type: string
      - name: show_metadata
        in: query
        description: Whether to include the full cluster metadata in the response - can be large per cluster and also include credentials.
        required: false
        schema:
          type: boolean
          default: false
      - name: show_plans
        in: query
        description: Whether to include the full current and pending plan information in the response - can be large per cluster.
        required: false
        schema:
          type: boolean
          default: true
      - name: show_plan_logs
        in: query
        description: Whether to include with the current and pending plan information the attempt log - can be very large per cluster.
        required: false
        schema:
          type: boolean
          default: false
      - name: show_plan_history
        in: query
        description: Whether to include with the current and pending plan information the plan history- can be very large per cluster.
        required: false
        schema:
          type: boolean
          default: false
      - name: show_plan_defaults
        in: query
        description: If showing plans, whether to show values that are left at their default value (less readable but more informative).
        required: false
        schema:
          type: boolean
          default: false
      - name: show_settings
        in: query
        description: Whether to show cluster settings in the response.
        required: false
        schema:
          type: boolean
          default: false
      - name: clear_transient
        in: query
        description: If set (defaults to false) then removes the transient section from all child resources, making it safe to reapply via an update
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Standard response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApmResourceInfo'
        '404':
          description: 'The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'We have failed you. (code: `deployments.deployment_resource_no_longer_exists`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_resource_no_longer_exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Deployment - Info
  /deployments/{deployment_id}/apm/{ref_id}/_reset-token:
    post:
      tags:
      - Deployments
      summary: Reset the secret token for an APM resource.
      description: Reset the token of an APM resource.
      operationId: deployment-apm-reset-secret-token
      parameters:
      - name: deployment_id
        in: path
        description: Identifier for the Deployment.
        required: true
        schema:
          type: string
      - name: ref_id
        in: path
        description: User-specified RefId for the Resource (or '_main' if there is only one).
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Response containing the new secret token, plan to apply it starts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApmCrudResponse'
        '400':
          description: 'Reset token is not supported when APM is managed by Elastic Agent. (code: `clusters.cluster_plan_state_error`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - clusters.cluster_plan_state_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: '* 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:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_not_found
                - deployments.deployment_resource_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'We have failed you. (code: `deployments.deployment_resource_no_longer_exists`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - deployments.deployment_resource_no_longer_exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: APM routes
  /deployments/{deployment_id}/appsearch/{ref_id}:
    get:
      tags:
      - Deployments
      summary: Get Deploym

# --- truncated at 32 KB (432 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-deployments-api-openapi.yml