Skip to content

Commit 2ad8845

Browse files
kosabogikosabogi
committed
Adds Serverless Project Management API page
1 parent e245c17 commit 2ad8845

File tree

2 files changed

+155
-0
lines changed

2 files changed

+155
-0
lines changed

‎docs/reference/elasticsearch/rest-apis/elastic-cloud-serverless-api.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
mapped_pages:
3+
- https://github.com/elastic/docs-content/blob/main/serverless/pages/manage-your-project-rest-api.asciidoc
4+
applies_to:
5+
serverless:
6+
elasticsearch: preview
7+
observability: preview
8+
security: preview
9+
navigation_title: Serverless Project Management API
10+
---
11+
12+
# Elastic Cloud Serverless Project Management API [serverless-project-management-api]
13+
14+
You can manage serverless projects using the [Elastic Cloud Serverless Project Management APIs](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/).
15+
16+
The available APIs are grouped by project type:
17+
18+
- APIs for [Search projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-elasticsearch-projects)
19+
- APIs for [Observatibility projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-observability-projects)
20+
- APIs for [Security projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-security-projects)
21+
22+
The following examples show how to interact with the APIs, covering common operations such as:
23+
- [Creating a project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project)
24+
- [Retrieving project details](#general-manage-project-with-api-get-project)
25+
- [Retrieving the project's status](#general-manage-project-with-api-get-project-status)
26+
- [Resetting credentials](#general-manage-project-with-api-reset-credentials)
27+
- [Deleting a project](#general-manage-project-with-api-delete-project)
28+
- [Updating a project](#general-manage-project-with-api-update-project)
29+
- [Listing regions where projects can be created](#general-manage-project-with-api-list-available-regions)
30+
31+
## Set up an API key
32+
33+
1. [Create an API key](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys).
34+
2. Store the generated API key as an environment variable so that you don’t need to specify it again for each request:
35+
36+
```console
37+
export API_KEY="YOUR_GENERATED_API_KEY"
38+
```
39+
40+
## Create an {{es-serverless}} project [general-manage-project-with-api-create-a-serverless-elasticsearch-project]
41+
42+
```bash
43+
curl -H "Authorization: ApiKey $API_KEY" \
44+
-H "Content-Type: application/json" \
45+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch" \
46+
-XPOST --data '{
47+
"name": "My project", <1>
48+
"region_id": "aws-us-east-1" <2>
49+
}'
50+
```
51+
1. Replace `My project` with a more descriptive name in this call.
52+
2. You can obtain a [list of available regions](#general-manage-project-with-api-list-available-regions).
53+
54+
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}}.
55+
56+
Example of `Create project` response:
57+
58+
```console-response
59+
{
60+
"id": "cace8e65457043698ed3d99da2f053f6",
61+
"endpoints": {
62+
"elasticsearch": "https://sample-project-c990cb.es.us-east-1.aws.elastic.cloud",
63+
"kibana": "https://sample-project-c990cb-c990cb.kb.us-east-1.aws.elastic.cloud"
64+
},
65+
"credentials": {
66+
"username": "admin",
67+
"password": "abcd12345"
68+
}
69+
(...)
70+
}
71+
```
72+
73+
You can store the project ID as an environment variable for the next requests:
74+
75+
```console
76+
export PROJECT_ID=cace8e65457043698ed3d99da2f053f6
77+
```
78+
79+
## Get project [general-manage-project-with-api-get-project]
80+
81+
You can retrieve your project details through an API call:
82+
83+
```bash
84+
curl -H "Authorization: ApiKey $API_KEY" \
85+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}"
86+
```
87+
88+
## Get project status [general-manage-project-with-api-get-project-status]
89+
90+
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:
91+
92+
```bash
93+
curl -H "Authorization: ApiKey $API_KEY" \
94+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/status"
95+
```
96+
97+
Example response:
98+
99+
```console-response
100+
{
101+
"phase":"initializing"
102+
}
103+
```
104+
105+
## Reset Credentials [general-manage-project-with-api-reset-credentials]
106+
107+
If you lose the credentials provided at the time of the project creation, you can reset the credentials by using the following endpoint:
108+
109+
```bash
110+
curl -H "Authorization: ApiKey $API_KEY" \
111+
-XPOST \
112+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/_reset-credentials"
113+
```
114+
115+
## Delete Project [general-manage-project-with-api-delete-project]
116+
117+
You can delete your project via the API:
118+
119+
```bash
120+
curl -XDELETE -H "Authorization: ApiKey $API_KEY" \
121+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}"
122+
```
123+
124+
## Update Project [general-manage-project-with-api-update-project]
125+
126+
You can update your project using a PATCH request. Only the fields included in the body of the request will be updated.
127+
128+
```bash
129+
curl -H "Authorization: ApiKey $API_KEY" \
130+
-H "Content-Type: application/json" \
131+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" \
132+
-XPATCH --data '{
133+
"name": "new name",
134+
"alias": "new-project-alias"
135+
}'
136+
```
137+
138+
## List available regions [general-manage-project-with-api-list-available-regions]
139+
140+
You can obtain the list of regions where projects can be created using the API:
141+
142+
```bash
143+
curl -H "Authorization: ApiKey $API_KEY" \
144+
"https://api.elastic-cloud.com/api/v1/serverless/regions"
145+
```
146+
147+
148+
149+
150+
151+
152+
153+
154+

‎docs/reference/elasticsearch/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ toc:
107107
- file: rest-apis/term-vectors-examples.md
108108
- file: rest-apis/update-cc-api-key-examples.md
109109
- file: rest-apis/vector-tile-search.md
110+
- file: rest-apis/elastic-cloud-serverless-api.md
110111
- file: mapping-reference/index.md
111112
children:
112113
- file: mapping-reference/document-metadata-fields.md

0 commit comments

Comments
 (0)