API keys are used to authenticate requests to the Elastic Cloud Serverless REST API. Generate your secret API key in https://cloud.elastic.co/account/keys You must provide the API key for all API requests in the Authorization header as follows:
"Authorization: ApiKey $API_KEY"
For example, if you interact with the API using the curl command:
curl -H "Authorization: ApiKey essu_..." https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch
The number of projects included can be configured with page_size. Consecutive calls can be made to retrieve next pages by providing a token.
curl \
--request GET 'https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch' \
--header "Authorization: $API_KEY"{
"next_page": "YyMzY1MDQiLCJtYXgiOiJGRiJ9fV0=",
"items": [
{
"id": "string",
"name": "my project",
"alias": "my-project-alias",
"region_id": "aws-us-east-1",
"metadata": {
"created_at": "2025-05-04T09:42:00Z",
"created_by": "1014289666002276",
"organization_id": "198583657190",
"suspended_at": "2025-05-04T09:42:00Z",
"suspended_reason": "trial expired"
},
"cloud_id": "my_project:LmF3cy5lbGFzdG",
"type": "elasticsearch",
"optimized_for": "general_purpose",
"search_lake": {
"search_power": 100,
"boost_window": 100
},
"endpoints": {
"elasticsearch": "https://my-project-alias-df6c6d.es.us-east-1.aws.elastic.cloud",
"kibana": "https://my-project-alias-df6c6d.kb.us-east-1.aws.elastic.cloud"
}
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Only the fields included in the body of the request will be updated.
ETag value fetched in a previous GET project request. Used to prevent simultaneous updates
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
The Elasticsearch project patch body
Descriptive name for a project.
Minimum length is 1, maximum length is 255.
A custom domain label compatible with RFC-1035 standards. Derived from the project name by default.
Minimum length is 1, maximum length is 50. Format should match the following pattern: ^[a-zA-Z]{1}(?:[a-zA-Z0-9-]*[a-zA-Z0-9]{1})?$.
Configuration for entire set of capabilities that make the data searchable in Elasticsearch. It can be passed as null to reset configuration to the default values.
Additional properties are allowed.
curl \
--request PATCH 'https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "If-Match: string" \
--data '{"name":"Example project"}'{
"name": "Example project"
}# Headers
ETag: string
# Payload
{
"id": "string",
"name": "my project",
"alias": "my-project-alias",
"region_id": "aws-us-east-1",
"metadata": {
"created_at": "2025-05-04T09:42:00Z",
"created_by": "1014289666002276",
"organization_id": "198583657190",
"suspended_at": "2025-05-04T09:42:00Z",
"suspended_reason": "trial expired"
},
"cloud_id": "my_project:LmF3cy5lbGFzdG",
"type": "elasticsearch",
"optimized_for": "general_purpose",
"search_lake": {
"search_power": 100,
"boost_window": 100
},
"endpoints": {
"elasticsearch": "https://my-project-alias-df6c6d.es.us-east-1.aws.elastic.cloud",
"kibana": "https://my-project-alias-df6c6d.kb.us-east-1.aws.elastic.cloud"
}
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Retrieve new project credentials, invalidating the previous ones.
ETag value fetched in a previous GET project request. Used to prevent simultaneous updates
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request POST 'https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/{id}/_reset-credentials' \
--header "Authorization: $API_KEY" \
--header "If-Match: string"# Headers
ETag: string
# Payload
{
"username": "admin",
"password": "*****"
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}The response indicates whether the project is initialized and ready to be used. The phase will change from "initializing" to "initialized" when the project is ready.
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request GET 'https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/{id}/status' \
--header "Authorization: $API_KEY"{
"phase": "initializing"
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Only the fields included in the body of the request will be updated.
ETag value fetched in a previous GET project request. Used to prevent simultaneous updates
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
The patched Observability project
Descriptive name for a project.
Minimum length is 1, maximum length is 255.
A custom domain label compatible with RFC-1035 standards. Derived from the project name by default.
Minimum length is 1, maximum length is 50. Format should match the following pattern: ^[a-zA-Z]{1}(?:[a-zA-Z0-9-]*[a-zA-Z0-9]{1})?$.
curl \
--request PATCH 'https://api.elastic-cloud.com/api/v1/serverless/projects/observability/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "If-Match: string" \
--data '{"name":"Example project"}'{
"name": "Example project"
}# Headers
ETag: string
# Payload
{
"id": "string",
"name": "my project",
"alias": "my-project-alias",
"region_id": "aws-us-east-1",
"metadata": {
"created_at": "2025-05-04T09:42:00Z",
"created_by": "1014289666002276",
"organization_id": "198583657190",
"suspended_at": "2025-05-04T09:42:00Z",
"suspended_reason": "trial expired"
},
"cloud_id": "my_project:LmF3cy5lbGFzdG",
"type": "observability",
"endpoints": {
"elasticsearch": "string",
"kibana": "string",
"apm": "string",
"ingest": "string"
}
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Retrieve new project credentials, invalidating the previous ones.
ETag value fetched in a previous GET project request. Used to prevent simultaneous updates
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request POST 'https://api.elastic-cloud.com/api/v1/serverless/projects/observability/{id}/_reset-credentials' \
--header "Authorization: $API_KEY" \
--header "If-Match: string"# Headers
ETag: string
# Payload
{
"username": "admin",
"password": "*****"
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Resume a previously suspended Observability project. Projects can be automatically suspended after their trial period has expired.
ETag value fetched in a previous GET project request. Used to prevent simultaneous updates.
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request POST 'https://api.elastic-cloud.com/api/v1/serverless/projects/observability/{id}/_resume' \
--header "Authorization: $API_KEY" \
--header "If-Match: string"{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Retrieve the custom roles defined for an Observability project.
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request GET 'https://api.elastic-cloud.com/api/v1/serverless/projects/observability/{id}/roles' \
--header "Authorization: $API_KEY"# Headers
ETag: string
# Payload
{
"additionalProperty1": {
"roles": [
{
"name": "string",
"description": "string"
}
]
},
"additionalProperty2": {
"roles": [
{
"name": "string",
"description": "string"
}
]
}
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}The response indicates whether the project is initialized and ready to be used. The phase will change from "initializing" to "initialized" when the project is ready.
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request GET 'https://api.elastic-cloud.com/api/v1/serverless/projects/observability/{id}/status' \
--header "Authorization: $API_KEY"{
"phase": "initializing"
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Management of Security projects
The number of projects included can be configured with page_size. Consecutive calls can be made to retrieve next pages by providing a token.
curl \
--request GET 'https://api.elastic-cloud.com/api/v1/serverless/projects/security' \
--header "Authorization: $API_KEY"{
"next_page": "string",
"items": [
{
"id": "string",
"name": "my project",
"alias": "my-project-alias",
"region_id": "aws-us-east-1",
"metadata": {
"created_at": "2025-05-04T09:42:00Z",
"created_by": "1014289666002276",
"organization_id": "198583657190",
"suspended_at": "2025-05-04T09:42:00Z",
"suspended_reason": "trial expired"
},
"cloud_id": "my_project:LmF3cy5lbGFzdG",
"type": "security",
"endpoints": {
"elasticsearch": "string",
"kibana": "string"
},
"search_lake": {
"data_retention": {
"max_retention_days": 42,
"default_retention_days": 42
}
},
"admin_features_package": "standard",
"product_types": [
{
"product_line": "security",
"product_tier": "complete"
}
]
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}The response will include the created project details, such as the project ID, the credentials to access the project, and the endpoints to access different apps such as Elasticsearch and Kibana. The credentials can be regenerated at any time using the _reset-credentials endpoint.
Configuration of the security project to create.
Descriptive name for a project.
Minimum length is 1, maximum length is 255.
A custom domain label compatible with RFC-1035 standards. Derived from the project name by default.
Minimum length is 1, maximum length is 50. Format should match the following pattern: ^[a-zA-Z]{1}(?:[a-zA-Z0-9-]*[a-zA-Z0-9]{1})?$.
Unique human-readable identifier for a region in Elastic Cloud.
admin features package (BYOK, BYOIDP, CCS, CCR)
Values are standard or enterprise.
Defines Security product type object with product line and tier dimensions.
At least 1 but not more than 3 elements. Default value is [{"product_line"=>"security", "product_tier"=>"complete"}, {"product_line"=>"cloud", "product_tier"=>"complete"}, {"product_line"=>"endpoint", "product_tier"=>"complete"}].
Configuration for the entire set of capabilities that make the data searchable in Security.
Additional properties are allowed.
curl \
--request POST 'https://api.elastic-cloud.com/api/v1/serverless/projects/security' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"Example project","region_id":"aws-us-east-1"}'{
"name": "Example project",
"region_id": "aws-us-east-1"
}# Headers
ETag: string
# Payload
{
"id": "string",
"name": "my project",
"alias": "my-project-alias",
"region_id": "aws-us-east-1",
"metadata": {
"created_at": "2025-05-04T09:42:00Z",
"created_by": "1014289666002276",
"organization_id": "198583657190",
"suspended_at": "2025-05-04T09:42:00Z",
"suspended_reason": "trial expired"
},
"cloud_id": "my_project:LmF3cy5lbGFzdG",
"type": "security",
"endpoints": {
"elasticsearch": "string",
"kibana": "string"
},
"search_lake": {
"data_retention": {
"max_retention_days": 42,
"default_retention_days": 42
}
},
"admin_features_package": "standard",
"product_types": [
{
"product_line": "security",
"product_tier": "complete"
}
],
"credentials": {
"username": "admin",
"password": "*****"
}
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}Retrieve new project credentials, invalidating the previous ones.
ETag value fetched in a previous GET project request. Used to prevent simultaneous updates
The ID of the project
Format should match the following pattern: ^[a-z0-9]{32}$.
curl \
--request POST 'https://api.elastic-cloud.com/api/v1/serverless/projects/security/{id}/_reset-credentials' \
--header "Authorization: $API_KEY" \
--header "If-Match: string"# Headers
ETag: string
# Payload
{
"username": "admin",
"password": "*****"
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}{
"errors": [
{
"message": "Explicative error message",
"code": "code.error"
}
]
}