Principles

The Elasticsearch Service API is built on REST. This means that:

URLs are based on resource IDs.
JSON is the data interchange format.
Standard HTTP response codes and verbs are used.

RESTful API calls are stateless. Every request that you make happens in isolation from other calls and must include all the information necessary for Elasticsearch Service to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.

Calls to API endpoints require different request methods, depending on what they do. You use these four request methods to communicate with the Elasticsearch Service RESTful API:

To fetch a resource: GET
To create a new resource: POST
To update an existing resource: PUT or PATCH
To delete a resource: DELETE

Rate limiting

API calls are rate limited in a timing window. The current remaining available calls quota is available through the following header fields, included in each API call response:

x-ratelimit-interval - The time duration for the quota calculation.
x-ratelimit-remaining - The remaining number of API calls available.
x-ratelimit-limit - The total number of calls available in the duration x-ratelimit-interval.

Authentication

Elastic Cloud APIs support key-based authentication. You must create an API key and use the encoded value in the request header.
For convenience, you can export your API key into your shell environment:

export EC_API_KEY="YOUR_GENERATED_API_KEY"

For example, the following curl command retrieves a list of your deployments:

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

Fetch current account information

GET /account

Fetch current account information.

Responses

200 application/json

Account fetched successfully
Hide response attributes Show response attributes object
- id string Required
  
  The account's identifier
- trust object
  
  Settings related to the level of trust of the clusters in this account
  
  Hide trust attribute Show trust attribute object
  
  trust_all boolean Required
  
  If true, all clusters in this account will by default trust all other clusters in the same account
404 application/json

Account not found. (code: accounts.not_found)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Value is accounts.not_found.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /account

curl \
 --request GET 'https://api.elastic-cloud.com/api/v1/account'

Response examples (200)

{
  "id": "string",
  "trust": {
    "trust_all": true
  }
}

Response examples (404)

# Headers
x-cloud-error-codes: accounts.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Updates the current account

PUT /account

Updates the current account.

application/json

Body Required

the current account

trust object

Settings related to the level of trust of the clusters in this account
Hide trust attribute Show trust attribute object
- trust_all boolean Required
  
  If true, all clusters in this account will by default trust all other clusters in the same account

Responses

200 application/json

Account updated successfully
Hide response attributes Show response attributes object
- id string Required
  
  The account's identifier
- trust object
  
  Settings related to the level of trust of the clusters in this account
  
  Hide trust attribute Show trust attribute object
  
  trust_all boolean Required
  
  If true, all clusters in this account will by default trust all other clusters in the same account
404 application/json

Account not found. (code: accounts.not_found)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Value is accounts.not_found.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields

PUT /account

curl \
 --request PUT 'https://api.elastic-cloud.com/api/v1/account' \
 --header "Content-Type: application/json" \
 --data '{"trust":{"trust_all":true}}'

Request examples

{
  "trust": {
    "trust_all": true
  }
}

Response examples (200)

{
  "id": "string",
  "trust": {
    "trust_all": true
  }
}

Response examples (404)

# Headers
x-cloud-error-codes: accounts.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Updates the current account

PATCH /account

Updates the current account.

application/json

Body Required

All changes in the specified object are applied to the current account according to the JSON Merge Patch processing rules. Omitting existing fields causes the same values to be reapplied. Specifying a null value reverts the field to the default value, or removes the field when no default value exists.

string

Responses

200 application/json

Account updated successfully
Hide response attributes Show response attributes object
- id string Required
  
  The account's identifier
- trust object
  
  Settings related to the level of trust of the clusters in this account
  
  Hide trust attribute Show trust attribute object
  
  trust_all boolean Required
  
  If true, all clusters in this account will by default trust all other clusters in the same account
404 application/json

Account not found. (code: accounts.not_found)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Value is accounts.not_found.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields

PATCH /account

curl \
 --request PATCH 'https://api.elastic-cloud.com/api/v1/account' \
 --header "Content-Type: application/json" \
 --data '"string"'

Request examples

string

Response examples (200)

{
  "id": "string",
  "trust": {
    "trust_all": true
  }
}

Response examples (404)

# Headers
x-cloud-error-codes: accounts.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Get all API keys

GET /users/auth/keys

Retrieves the metadata for all of the API keys that the user generated.

Responses

200 application/json

The metadata for the API keys is retrieved.
Hide response attribute Show response attribute object
- keys array[object] Required
  
  The list of API keys.
  
  The response model for an API key.
  
  Hide keys attributes Show keys attributes object
  
  id string Required
  
  The API key ID.
  
  user_id string
  
  The user ID.
  
  organization_id string
  
  The organization ID linked to the API key
  
  description string Required
  
  The API key description. TIP: Useful when you have multiple API keys.
  
  key string
  
  The API key. TIP: Since the API key is returned only once, save it in a safe place.
  
  creation_date string(date-time) Required
  
  The date/time for when the API key is created.
  
  expiration_date string(date-time)
  
  The date/time when the API key expires.
  
  role_assignments object
  
  The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.
  
  Hide role_assignments attributes Show role_assignments attributes object
  
  platform array[object]
  
  Assignments for roles with platform scope.
  
  Assignment for a role with platform scope.
  
  Hide platform attribute Show platform attribute object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization array[object]
  
  Assignments for roles with organization scope.
  
  Assignment for a role with organization scope.
  
  Hide organization attributes Show organization attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  deployment array[object]
  
  Assignments for roles with deployment scope.
  
  Assignment for a role with deployment scope.
  
  Hide deployment attributes Show deployment attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.
  
  deployment_ids array[string]
  
  The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.
  
  project object
  
  Assignments for roles with project scope.
  
  Hide project attributes Show project attributes object
  
  elasticsearch array[object]
  
  The Elasticsearch project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
  
  observability array[object]
  
  The Observability project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide observability attributes Show observability attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
  
  security array[object]
  
  The Security project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide security attributes Show security attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

GET /users/auth/keys

curl \
 --request GET 'https://api.elastic-cloud.com/api/v1/users/auth/keys'

Response examples (200)

{
  "keys": [
    {
      "id": "string",
      "user_id": "string",
      "organization_id": "string",
      "description": "string",
      "key": "string",
      "creation_date": "2025-05-04T09:42:00Z",
      "expiration_date": "2025-05-04T09:42:00Z",
      "role_assignments": {
        "platform": [
          {
            "role_id": "string"
          }
        ],
        "organization": [
          {
            "role_id": "string",
            "organization_id": "string"
          }
        ],
        "deployment": [
          {
            "role_id": "string",
            "organization_id": "string",
            "all": true,
            "deployment_ids": [
              "string"
            ],
            "application_roles": [
              "string"
            ]
          }
        ],
        "project": {
          "elasticsearch": [
            {
              "role_id": "string",
              "organization_id": "string",
              "all": true,
              "project_ids": [
                "string"
              ],
              "application_roles": [
                "string"
              ]
            }
          ],
          "observability": [
            {
              "role_id": "string",
              "organization_id": "string",
              "all": true,
              "project_ids": [
                "string"
              ],
              "application_roles": [
                "string"
              ]
            }
          ],
          "security": [
            {
              "role_id": "string",
              "organization_id": "string",
              "all": true,
              "project_ids": [
                "string"
              ],
              "application_roles": [
                "string"
              ]
            }
          ]
        }
      }
    }
  ]
}

Create API key

POST /users/auth/keys

Creates a new API key.

application/json

Body Required

The request to create the API key

description string Required

API key description. Useful if there are multiple keys
expiration string

The optional expiration for the API key, provided as a duration (ex: '1d', '3h')
role_assignments object

The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.
Hide role_assignments attributes Show role_assignments attributes object
- platform array[object]
  
  Assignments for roles with platform scope.
  
  Assignment for a role with platform scope.
  Hide platform attribute Show platform attribute object
  
  role_id string Required
  
  The ID of the role that is assigned.
- organization array[object]
  
  Assignments for roles with organization scope.
  
  Assignment for a role with organization scope.
  Hide organization attributes Show organization attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
- deployment array[object]
  
  Assignments for roles with deployment scope.
  
  Assignment for a role with deployment scope.
  Hide deployment attributes Show deployment attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.
  
  deployment_ids array[string]
  
  The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.
- project object
  
  Assignments for roles with project scope.
  Hide project attributes Show project attributes object
  
  elasticsearch array[object]
  
  The Elasticsearch project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
  
  observability array[object]
  
  The Observability project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide observability attributes Show observability attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
  
  security array[object]
  
  The Security project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide security attributes Show security attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

Responses

201 application/json

The API key is created and returned in the body of the response.
Hide response attributes Show response attributes object
- id string Required
  
  The API key ID.
- user_id string
  
  The user ID.
- organization_id string
  
  The organization ID linked to the API key
- description string Required
  
  The API key description. TIP: Useful when you have multiple API keys.
- key string
  
  The API key. TIP: Since the API key is returned only once, save it in a safe place.
- creation_date string(date-time) Required
  
  The date/time for when the API key is created.
- expiration_date string(date-time)
  
  The date/time when the API key expires.
- role_assignments object
  
  The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.
  
  Hide role_assignments attributes Show role_assignments attributes object
  
  platform array[object]
  
  Assignments for roles with platform scope.
  
  Assignment for a role with platform scope.
  
  Hide platform attribute Show platform attribute object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization array[object]
  
  Assignments for roles with organization scope.
  
  Assignment for a role with organization scope.
  
  Hide organization attributes Show organization attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  deployment array[object]
  
  Assignments for roles with deployment scope.
  
  Assignment for a role with deployment scope.
  
  Hide deployment attributes Show deployment attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.
  
  deployment_ids array[string]
  
  The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.
  
  project object
  
  Assignments for roles with project scope.
  
  Hide project attributes Show project attributes object
  
  elasticsearch array[object]
  
  The Elasticsearch project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
  
  observability array[object]
  
  The Observability project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide observability attributes Show observability attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
  
  security array[object]
  
  The Security project-scoped role assignments to set
  
  Assignment for a role with project scope.
  
  Hide security attributes Show security attributes object
  
  role_id string Required
  
  The ID of the role that is assigned.
  
  organization_id string Required
  
  The ID of the organization the role is scoped to.
  
  all boolean
  
  When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.
  
  project_ids array[string]
  
  The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.
  
  application_roles array[string]
  
  If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.
400 application/json

The request is invalid. Specify a different request, then try again. (code: api_keys.invalid_input)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Value is api_keys.invalid_input.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields

POST /users/auth/keys

curl \
 --request POST 'https://api.elastic-cloud.com/api/v1/users/auth/keys' \
 --header "Content-Type: application/json" \
 --data '{"description":"string","expiration":"string","role_assignments":{"platform":[{"role_id":"string"}],"organization":[{"role_id":"string","organization_id":"string"}],"deployment":[{"role_id":"string","organization_id":"string","all":true,"deployment_ids":["string"],"application_roles":["string"]}],"project":{"elasticsearch":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}],"observability":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}],"security":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}]}}}'

Request examples

{
  "description": "string",
  "expiration": "string",
  "role_assignments": {
    "platform": [
      {
        "role_id": "string"
      }
    ],
    "organization": [
      {
        "role_id": "string",
        "organization_id": "string"
      }
    ],
    "deployment": [
      {
        "role_id": "string",
        "organization_id": "string",
        "all": true,
        "deployment_ids": [
          "string"
        ],
        "application_roles": [
          "string"
        ]
      }
    ],
    "project": {
      "elasticsearch": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ],
      "observability": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ],
      "security": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ]
    }
  }
}

Response examples (201)

{
  "id": "string",
  "user_id": "string",
  "organization_id": "string",
  "description": "string",
  "key": "string",
  "creation_date": "2025-05-04T09:42:00Z",
  "expiration_date": "2025-05-04T09:42:00Z",
  "role_assignments": {
    "platform": [
      {
        "role_id": "string"
      }
    ],
    "organization": [
      {
        "role_id": "string",
        "organization_id": "string"
      }
    ],
    "deployment": [
      {
        "role_id": "string",
        "organization_id": "string",
        "all": true,
        "deployment_ids": [
          "string"
        ],
        "application_roles": [
          "string"
        ]
      }
    ],
    "project": {
      "elasticsearch": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ],
      "observability": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ],
      "security": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ]
    }
  }
}

Response examples (400)

# Headers
x-cloud-error-codes: api_keys.invalid_input

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}