Manage serverless projects using the API

Serverless

On this page, you can find examples of how to create and manage serverless projects using the Elastic Cloud Serverless API.

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 Observatibility projects
• APIs for Security projects

To try the examples in this section, set up an API key and create an Elastic Cloud Serverless project.

1. Create an API key.
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, such as the project ID, the credentials to access the project, and the endpoints to access different apps such as Elasticsearch and Kibana.

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 

The following examples show how to interact with the APIs, covering common operations such as:

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

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"
}

If you lose the credentials provided at the time of the project creation, you can reset the credentials by using the following endpoint:

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

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"