Elastic Cloud Enterprise API
1
https://{{hostname}}/api/v1
This RESTful API enables you to create and manage both your Elastic Stack deployments and the ECE platform.
NOTE: This documentation applies to the Elastic Cloud Enterprise API only. If you are using Elasticsearch Service, use the Elastic Cloud API.
This API supports both key-based and token-based authentication. Key-based is generally the preferred method. For details about creating an API key or bearer token, refer to Authentication.
Documentation source and versions
This documentation is derived from https://api.elastic-cloud.com/api/v1/api-docs/swagger.json. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.
This is version 1
of this API documentation.
Last update on Oct 29, 2024.
Accounts
Retrieve and update the current Elasticsearch Service account.
curl \
-X PUT https://{{hostname}}/api/v1/account \
-d '{"trust":{"trust_all":true}}'
{
"trust": {
"trust_all": true
}
}
{
"id": "string",
"trust": {
"trust_all": true
}
}
# Headers
x-cloud-error-codes: accounts.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Body Required
The login request
-
The username part of the login request
-
The plain text password part of the login request
-
login_state object
Configure how the API responds after a successful login.
Additional properties are allowed.
Responses
-
Login successful, returns the token in the body (if 'login_state.path' not specified)
-
Redirects to '/sso/token#BEARER_TOKEN?state=LOGIN_STATE' with the fragment containing a bearer token (if 'login_state.path' is specified)
Additional properties are allowed.
-
The supplied authentication is invalid. (code:
root.unauthenticated
) -
The administrator needs to configure the authentication cluster. (code:
authc.no_authentication_cluster
) -
The authentication cluster failed to process the request. The response body contains details about the error. (code:
authc.authentication_cluster_error
)
curl \
-X POST https://{{hostname}}/api/v1/users/auth/_login \
-d '{"username":"string","password":"string","login_state":{"path":"string"}}'
{
"username": "string",
"password": "string",
"login_state": {
"path": "string"
}
}
{
"token": "string",
"session_expiration_time": "2025-05-04T09:42:00+00:00"
}
{}
# Headers
x-cloud-error-codes: root.unauthenticated
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: authc.no_authentication_cluster
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: authc.authentication_cluster_error
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Responses
-
The token refreshed successfully and was returned in the body of the response.
-
The authentication token is invalid or expired. (code:
root.unauthorized
) -
The administrator needs to configure the authentication cluster. (code:
authc.no_authentication_cluster
) -
The authentication cluster failed to process the request. The response body contains details about the error. (code:
authc.authentication_cluster_error
)
curl \
-X POST https://{{hostname}}/api/v1/users/auth/_refresh
{
"token": "string",
"session_expiration_time": "2025-05-04T09:42:00+00:00"
}
# Headers
x-cloud-error-codes: root.unauthorized
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: authc.no_authentication_cluster
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: authc.authentication_cluster_error
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Get all API keys
Retrieves the metadata for all of the API keys that the user generated.
curl \
-X GET https://{{hostname}}/api/v1/users/auth/keys
{
"keys": [
{
"id": "string",
"user_id": "string",
"organization_id": "string",
"description": "string",
"key": "string",
"creation_date": "2025-05-04T09:42:00+00:00",
"expiration_date": "2025-05-04T09:42:00+00:00"
}
]
}
curl \
-X DELETE https://{{hostname}}/api/v1/users/auth/keys \
-d '{"keys":["string"]}'
{
"keys": [
"string"
]
}
{}
Get all API keys for all users
Retrieves the metadata for all of the API keys for all users.
curl \
-X GET https://{{hostname}}/api/v1/users/auth/keys/_all
{
"keys": [
{
"id": "string",
"user_id": "string",
"organization_id": "string",
"description": "string",
"key": "string",
"creation_date": "2025-05-04T09:42:00+00:00",
"expiration_date": "2025-05-04T09:42:00+00:00"
}
]
}
Available authentication methods
Provides information about available authentication methods.
curl \
-X GET https://{{hostname}}/api/v1/users/auth/methods
{
"password": true,
"saml": true,
"openid": true,
"sso_methods": [
{
"sso_type": "saml",
"name": "string",
"url": "string"
}
]
}
Get a user API key
Retrieves the API key metadata for a user.
Path parameters
-
The user ID.
-
The API Key ID.
curl \
-X GET https://{{hostname}}/api/v1/users/{user_id}/auth/keys/{api_key_id}
{
"id": "string",
"user_id": "string",
"organization_id": "string",
"description": "string",
"key": "string",
"creation_date": "2025-05-04T09:42:00+00:00",
"expiration_date": "2025-05-04T09:42:00+00:00"
}
# Headers
x-cloud-error-codes: api_keys.key_not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Delete an API key for a user
Delete or invalidate an API key for a user.
Path parameters
-
The user ID.
-
The API Key ID.
curl \
-X DELETE https://{{hostname}}/api/v1/users/{user_id}/auth/keys/{api_key_id}
{}
# Headers
x-cloud-error-codes: api_keys.key_not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Billing costs analysis
Get an overview of your costs by organization ID.
Get charts for the organization. Currently unavailable in self-hosted ECE.
EXPERIMENTAL (it may change in future versions): Retrieves the usage charts for the organization.
Path parameters
-
Identifier for the organization
Query parameters
-
from string
A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
-
to string
A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
-
bucketing_strategy string
The desired bucketing strategy for the charts. Defaults to
daily
.Values are
daily
ormonthly
. Default value isDaily
.
Responses
-
The usage charts of an organization.
-
The specified date range is invalid. (code:
costs.invalid_date_range
) -
The current user does not have access to the requested organization. (code:
organization.invalid_access
) -
Organization not found. (code:
organization.not_found
) -
Too many requests. (code:
billing_service.rate_limited
) -
Error fetching the itemized costs for the organization. (code:
billing_service.failed_request
)
curl \
-X GET https://{{hostname}}/api/v1/billing/costs/{organization_id}/charts
{
"data": [
{
"timestamp": 42,
"values": [
{
"id": "string",
"name": "string",
"value": 42.0
}
]
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.rate_limited
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Get charts by deployment. Currently unavailable in self-hosted ECE.
EXPERIMENTAL (it may change in future versions): Retrieves the usage charts for the given deployment.
Path parameters
-
Identifier for the organization
-
Id of a Deployment
Query parameters
-
from string
A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
-
to string
A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
-
bucketing_strategy string
The desired bucketing strategy for the charts. Defaults to
daily
.Values are
daily
ormonthly
. Default value isDaily
.
Responses
-
The usage charts of a deployment.
-
The specified date range is invalid. (code:
costs.invalid_date_range
) -
The current user does not have access to the requested organization. (code:
organization.invalid_access
) -
Organization not found. (code:
organization.not_found
) -
Too many requests. (code:
billing_service.rate_limited
) -
Error fetching the itemized costs for the organization. (code:
billing_service.failed_request
)
curl \
-X GET https://{{hostname}}/api/v1/billing/costs/{organization_id}/deployments/{deployment_id}/charts
{
"data": [
{
"timestamp": 42,
"values": [
{
"id": "string",
"name": "string",
"value": 42.0
}
]
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.rate_limited
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Comments
Manage resource comments.
Create a Comment
Creates a comment for the given Resource.
Path parameters
-
The kind of Resource that a Comment belongs to. Should be one of [elasticsearch, kibana, apm, appsearch, enterprise_search, integrations_server, allocator, constructor, runner, proxy].
-
Id of the Resource that a Comment belongs to.
Responses
-
The Comment that was just created.
-
Your current session does not have a user id associated with it. (code:
comments.no_user_id
) -
No Resource of the given type and id exist. (code:
comments.resource_does_not_exist
) -
A Comment already exists with the generated id. Please try again. (code:
comments.id_already_exists
)
curl \
-X POST https://{{hostname}}/api/v1/comments/{resource_type}/{resource_id} \
-d '{"message":"string"}'
{
"message": "string"
}
# Headers
x-cloud-resource-version: string
x-cloud-resource-created: string
x-cloud-resource-last-modified: string
# Payload
{
"id": "string",
"user_id": "string",
"message": "string"
}
# Headers
x-cloud-error-codes: comments.no_user_id
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: comments.resource_does_not_exist
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: comments.id_already_exists
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Path parameters
-
The kind of Resource that a Comment belongs to. Should be one of [elasticsearch, kibana, apm, appsearch, enterprise_search, integrations_server, allocator, constructor, runner, proxy].
-
Id of the Resource that a Comment belongs to.
-
Id of a Comment
curl \
-X GET https://{{hostname}}/api/v1/comments/{resource_type}/{resource_id}/{comment_id}
# Headers
x-cloud-resource-version: string
x-cloud-resource-created: string
x-cloud-resource-last-modified: string
# Payload
{
"id": "string",
"user_id": "string",
"message": "string"
}
# Headers
x-cloud-error-codes: comments.comment_does_not_exist
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Path parameters
-
The kind of Resource that a Comment belongs to. Should be one of [elasticsearch, kibana, apm, appsearch, enterprise_search, integrations_server, allocator, constructor, runner, proxy].
-
Id of the Resource that a Comment belongs to.
-
Id of a Comment
Query parameters
-
version string
If specified then checks for conflicts against the version stored in the persistent store (returned in 'x-cloud-resource-version' of the GET request)
Responses
-
Comment updated successfully.
-
- The Comment does not belong to you. (code:
comments.unauthorised
) - Your current session does not have a user id associated with it. (code:
comments.no_user_id
)
- The Comment does not belong to you. (code:
-
The Comment you want does not exist. (code:
comments.comment_does_not_exist
) -
The version you sent does not match the persisted version. (code:
comments.version_conflict
)
curl \
-X PUT https://{{hostname}}/api/v1/comments/{resource_type}/{resource_id}/{comment_id} \
-d '{"message":"string"}'
{
"message": "string"
}
# Headers
x-cloud-resource-version: string
x-cloud-resource-created: string
x-cloud-resource-last-modified: string
# Payload
{
"id": "string",
"user_id": "string",
"message": "string"
}
# Headers
x-cloud-error-codes: comments.unauthorised
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: comments.comment_does_not_exist
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: comments.version_conflict
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Path parameters
-
The kind of Resource that a Comment belongs to. Should be one of [elasticsearch, kibana, apm, appsearch, enterprise_search, integrations_server, allocator, constructor, runner, proxy].
-
Id of the Resource that a Comment belongs to.
-
Id of a Comment
Query parameters
-
version string
If specified then checks for conflicts against the version stored in the persistent store (returned in 'x-cloud-resource-version' of the GET request)
Responses
-
Comment deleted successfully.
Additional properties are allowed.
-
- The Comment does not belong to you. (code:
comments.unauthorised
) - Your current session does not have a user id associated with it. (code:
comments.no_user_id
)
- The Comment does not belong to you. (code:
-
The Comment you want does not exist. (code:
comments.comment_does_not_exist
) -
The version you sent does not match the persisted version. (code:
comments.version_conflict
)
curl \
-X DELETE https://{{hostname}}/api/v1/comments/{resource_type}/{resource_id}/{comment_id}
# Headers
x-cloud-resource-version: string
x-cloud-resource-created: string
x-cloud-resource-last-modified: string
# Payload
{}
# Headers
x-cloud-error-codes: comments.unauthorised
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: comments.comment_does_not_exist
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: comments.version_conflict
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Deployments
Perform CRUD operations, resync, and commands on your deployments.