From 2ad8845786282ad9259d0b5aa70602658b957488 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Thu, 26 Jun 2025 12:21:19 +0200 Subject: [PATCH 1/2] Adds Serverless Project Management API page --- .../rest-apis/elastic-cloud-serverless-api.md | 154 ++++++++++++++++++ docs/reference/elasticsearch/toc.yml | 1 + 2 files changed, 155 insertions(+) create mode 100644 docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md diff --git a/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md b/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md new file mode 100644 index 0000000000000..2833e6479ed98 --- /dev/null +++ b/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md @@ -0,0 +1,154 @@ +--- +mapped_pages: + - https://github.com/elastic/docs-content/blob/main/serverless/pages/manage-your-project-rest-api.asciidoc +applies_to: + serverless: + elasticsearch: preview + observability: preview + security: preview +navigation_title: Serverless Project Management API +--- + +# Elastic Cloud Serverless Project Management API [serverless-project-management-api] + +You can manage serverless projects using the [Elastic Cloud Serverless Project Management APIs](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/). + +The available APIs are grouped by project type: + +- APIs for [Search projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-elasticsearch-projects) +- APIs for [Observatibility projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-observability-projects) +- APIs for [Security projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-security-projects) + +The following examples show how to interact with the APIs, covering common operations such as: +- [Creating a project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project) +- [Retrieving project details](#general-manage-project-with-api-get-project) +- [Retrieving the project's status](#general-manage-project-with-api-get-project-status) +- [Resetting credentials](#general-manage-project-with-api-reset-credentials) +- [Deleting a project](#general-manage-project-with-api-delete-project) +- [Updating a project](#general-manage-project-with-api-update-project) +- [Listing regions where projects can be created](#general-manage-project-with-api-list-available-regions) + +## Set up an API key + +1. [Create an API key](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys). +2. Store the generated API key as an environment variable so that you don’t need to specify it again for each request: + +```console +export API_KEY="YOUR_GENERATED_API_KEY" +``` + +## Create an {{es-serverless}} project [general-manage-project-with-api-create-a-serverless-elasticsearch-project] + +```bash +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", <1> + "region_id": "aws-us-east-1" <2> + }' +``` +1. Replace `My project` with a more descriptive name in this call. +2. You can obtain a [list of available regions](#general-manage-project-with-api-list-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 {{es}} and {{kib}}. + +Example of `Create project` response: + +```console-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: + +```console +export PROJECT_ID=cace8e65457043698ed3d99da2f053f6 +``` + +## Get project [general-manage-project-with-api-get-project] + +You can retrieve your project details through an API call: + +```bash +curl -H "Authorization: ApiKey $API_KEY" \ + "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" +``` + +## Get project status [general-manage-project-with-api-get-project-status] + +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: + +```bash +curl -H "Authorization: ApiKey $API_KEY" \ + "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/status" +``` + +Example response: + +```console-response +{ + "phase":"initializing" +} +``` + +## Reset Credentials [general-manage-project-with-api-reset-credentials] + +If you lose the credentials provided at the time of the project creation, you can reset the credentials by using the following endpoint: + +```bash +curl -H "Authorization: ApiKey $API_KEY" \ + -XPOST \ + "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/_reset-credentials" +``` + +## Delete Project [general-manage-project-with-api-delete-project] + +You can delete your project via the API: + +```bash +curl -XDELETE -H "Authorization: ApiKey $API_KEY" \ + "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" +``` + +## Update Project [general-manage-project-with-api-update-project] + +You can update your project using a PATCH request. Only the fields included in the body of the request will be updated. + +```bash +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" + }' +``` + +## List available regions [general-manage-project-with-api-list-available-regions] + +You can obtain the list of regions where projects can be created using the API: + +```bash +curl -H "Authorization: ApiKey $API_KEY" \ + "https://api.elastic-cloud.com/api/v1/serverless/regions" +``` + + + + + + + + + diff --git a/docs/reference/elasticsearch/toc.yml b/docs/reference/elasticsearch/toc.yml index 16bffed9e0699..0d54f6d0dc1e4 100644 --- a/docs/reference/elasticsearch/toc.yml +++ b/docs/reference/elasticsearch/toc.yml @@ -107,6 +107,7 @@ toc: - file: rest-apis/term-vectors-examples.md - file: rest-apis/update-cc-api-key-examples.md - file: rest-apis/vector-tile-search.md + - file: rest-apis/elastic-cloud-serverless-api.md - file: mapping-reference/index.md children: - file: mapping-reference/document-metadata-fields.md From 9088070f869a64d50568884885b38efbf12f25a7 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Mon, 30 Jun 2025 12:24:46 +0200 Subject: [PATCH 2/2] Updates structure --- .../rest-apis/elastic-cloud-serverless-api.md | 39 +++++++++++-------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md b/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md index 2833e6479ed98..97adde4dd1730 100644 --- a/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md +++ b/docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md @@ -11,7 +11,9 @@ navigation_title: Serverless Project Management API # Elastic Cloud Serverless Project Management API [serverless-project-management-api] -You can manage serverless projects using the [Elastic Cloud Serverless Project Management APIs](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/). +On this page, you can find examples of how to interact with the [Elastic Cloud Serverless Project Management APIs](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/). + +To learn about API principles, authentication, and how to use the OpenAPI specification, refer to the [Elastic Cloud Serverless Project Management APIs](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/) documentation. The available APIs are grouped by project type: @@ -19,16 +21,9 @@ The available APIs are grouped by project type: - APIs for [Observatibility projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-observability-projects) - APIs for [Security projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-security-projects) -The following examples show how to interact with the APIs, covering common operations such as: -- [Creating a project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project) -- [Retrieving project details](#general-manage-project-with-api-get-project) -- [Retrieving the project's status](#general-manage-project-with-api-get-project-status) -- [Resetting credentials](#general-manage-project-with-api-reset-credentials) -- [Deleting a project](#general-manage-project-with-api-delete-project) -- [Updating a project](#general-manage-project-with-api-update-project) -- [Listing regions where projects can be created](#general-manage-project-with-api-list-available-regions) +To try the examples in this section, [set up an API key](#general-manage-project-with-api-set-up-api-key) and [create an {{es-serverless}} project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project). -## Set up an API key +## Set up an API key [general-manage-project-with-api-set-up-api-key] 1. [Create an API key](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys). 2. Store the generated API key as an environment variable so that you don’t need to specify it again for each request: @@ -76,7 +71,19 @@ You can store the project ID as an environment variable for the next requests: export PROJECT_ID=cace8e65457043698ed3d99da2f053f6 ``` -## Get project [general-manage-project-with-api-get-project] +## API examples + +The following examples show how to interact with the APIs, covering common operations such as: + +- [Creating a project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project) +- [Retrieving project details](#general-manage-project-with-api-get-project) +- [Retrieving the project's status](#general-manage-project-with-api-get-project-status) +- [Resetting credentials](#general-manage-project-with-api-reset-credentials) +- [Deleting a project](#general-manage-project-with-api-delete-project) +- [Updating a project](#general-manage-project-with-api-update-project) +- [Listing regions where projects can be created](#general-manage-project-with-api-list-available-regions) + +### Get project [general-manage-project-with-api-get-project] You can retrieve your project details through an API call: @@ -85,7 +92,7 @@ curl -H "Authorization: ApiKey $API_KEY" \ "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" ``` -## Get project status [general-manage-project-with-api-get-project-status] +### Get project status [general-manage-project-with-api-get-project-status] 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: @@ -102,7 +109,7 @@ Example response: } ``` -## Reset Credentials [general-manage-project-with-api-reset-credentials] +### Reset Credentials [general-manage-project-with-api-reset-credentials] If you lose the credentials provided at the time of the project creation, you can reset the credentials by using the following endpoint: @@ -112,7 +119,7 @@ curl -H "Authorization: ApiKey $API_KEY" \ "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/_reset-credentials" ``` -## Delete Project [general-manage-project-with-api-delete-project] +### Delete Project [general-manage-project-with-api-delete-project] You can delete your project via the API: @@ -121,7 +128,7 @@ curl -XDELETE -H "Authorization: ApiKey $API_KEY" \ "https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" ``` -## Update Project [general-manage-project-with-api-update-project] +### Update Project [general-manage-project-with-api-update-project] You can update your project using a PATCH request. Only the fields included in the body of the request will be updated. @@ -135,7 +142,7 @@ curl -H "Authorization: ApiKey $API_KEY" \ }' ``` -## List available regions [general-manage-project-with-api-list-available-regions] +### List available regions [general-manage-project-with-api-list-available-regions] You can obtain the list of regions where projects can be created using the API: