Manage serverless projects using the API

On this page, you can find examples of how to create and manage serverless projects using the Elastic Cloud Serverless API, covering common operations such as:

• Creating a project
• Retrieving project details
• Retrieving the project's status
• Deleting a project
• Updating a project
• Listing regions where projects can be created

To try the examples in this section, start by setting up an API key.

To learn about API principles, authentication, and how to use the OpenAPI specification, refer to the Elastic Cloud Serverless API documentation.

The available APIs are grouped by project type:

• APIs for Search projects
• APIs for Observability projects
• APIs for Security projects

To create and manage projects with the Elastic Cloud Serverless API, you must authenticate your requests with an Elastic Cloud API key.

1. As an Organization owner, create an Elastic Cloud API key with one of the following roles:

   • Organization owner
   • Cloud resource access with the Admin role assigned to all projects of the relevant type (Elasticsearch, Observability, or Security)

   Select the key's API access level based on what you need it to do: Cloud API access is enough to manage projects, while Cloud, Elasticsearch, and Kibana API access also grants access to the project's Elasticsearch and Kibana endpoints. For more details, refer to User roles and privileges.

2. Store the generated API key as an environment variable so that you don’t need to specify it again for each request:

   				
   					export API_KEY="YOUR_GENERATED_API_KEY"
   		

curl -H "Authorization: ApiKey $API_KEY" \
     -H "Content-Type: application/json" \
     "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch" \
     -XPOST --data '{
        "name": "My project",
        "region_id": "aws-us-east-1"
     }'
		

1. Replace My project with a more descriptive name in this call.
2. You can obtain a list of available regions.

The response from the create project request will include the created project details, including the project ID, the endpoints to access different apps such as Elasticsearch and Kibana, and a set of default credentials.

Example of Create project response:

{
    "id": "cace8e65457043698ed3d99da2f053f6",
    "endpoints": {
        "elasticsearch": "https://sample-project-c990cb.es.us-east-1.aws.elastic.cloud",
        "kibana": "https://sample-project-c990cb-c990cb.kb.us-east-1.aws.elastic.cloud"
    },
    "credentials": {
        "username": "admin",
        "password": "abcd12345"
    }
    (...)
}
		

You can store the project ID as an environment variable for the next requests:

				
					export PROJECT_ID=cace8e65457043698ed3d99da2f053f6
		

You can retrieve your project details through an API call:

curl -H "Authorization: ApiKey $API_KEY" \
    "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}"
		

The 'status' endpoint indicates whether the project is initialized and ready to be used. In the response, the project's phase will change from "initializing" to "initialized" when it is ready:

curl -H "Authorization: ApiKey $API_KEY" \
    "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/status"
		

Example response:

{
    "phase":"initializing"
}
		

You can delete your project via the API:

curl -XDELETE -H "Authorization: ApiKey $API_KEY" \
    "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}"
		

You can update your project using a PATCH request. Only the fields included in the body of the request will be updated.

curl -H "Authorization: ApiKey $API_KEY" \
    -H "Content-Type: application/json" \
    "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" \
    -XPATCH --data '{
        "name": "new name",
        "alias": "new-project-alias"
     }'
		

You can obtain the list of regions where projects can be created using the API:

curl -H "Authorization: ApiKey $API_KEY" \
    "https://api.elastic-cloud.com/api/v1/serverless/regions"