Update a project via API
The Imply Polaris Project v1 API has been deprecated and will be removed by the end of September 2024. Use the Projects v1 API instead. See the API migration guide for more information.
You can use the Imply Polaris Projects v1 API to monitor the amount of data storage consumed by your project and manage the project's size and state.
This topic explains how to change the size and state of a project using the Projects v1 API. For information on how to update a project in the UI, see Scale a project and Pause and resume a project.
In this topic, all API endpoints are relative to the base URL https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io
.
Prerequisites
To scale a project, you must be on a paid plan. To learn how to upgrade to a paid plan from a free trial, see Upgrade to a paid plan.
You must have an API key with the AdministerScaling
and ManageProjects
permissions.
In the examples below, the key value is stored in the variable POLARIS_API_KEY
.
For information about how to obtain an API key and assign permissions, see API key authentication.
For more information on permissions, visit Permissions reference.
Get project details
The Projects v1 API lets you retrieve information about individual projects, including the maximum project capacity and current usage. This is helpful if you want to analyze your storage consumption and scale a project up or down depending on the remaining capacity.
To view project details, send a GET
request to the /v1/projects/PROJECT_ID
endpoint.
If you do not know the ID of your project, send a GET
request the /v1/projects
endpoint to retrieve the list of projects for the organization.
The uid
property of the project object contains the project ID.
Sample request
The following example shows how to return information about a project with the ID 45c024f4-1234-5678-8207-4111d2f80669
:
- cURL
- Python
curl --location --request GET "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669" \
--user ${POLARIS_API_KEY}:
import os
import requests
url = "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669"
apikey = os.getenv("POLARIS_API_KEY")
payload = {}
headers = {
'Authorization': f'Basic {apikey}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
Samples response
The following example shows a successful response:
{
"metadata": {
"uid": "45c024f4-1234-5678-8207-4111d2f80669",
"name": "Docs project",
"createdOnTimestamp": "2023-09-17T04:04:32.395Z"
},
"spec": {
"plan": "starter",
"desiredState": "stopped",
"deletionProtection": false,
"region": "us-east-1"
},
"status": {
"maxBytes": 25000000000,
"currentBytes": 0,
"state": "stopped",
"version": "eac42c64"
}
}
Update a project
You can update the name, size, and state of a project.
To update a project, send a PATCH
request to the /v1/projects/PROJECT_ID
endpoint.
Include the application/merge-patch+json
Media Type in the HTTP header of your request.
To change the project's size and state, configure the spec
object as follows:
- Set the value of the
plan
property to the desired project size. - Set the value of the
desiredState
property to the desired state of the project:- running: The project is running.
- paused: The project is paused while the storage volume is kept.
- stopped: The project is stopped while the storage volume is removed.
The following snippet shows a spec
object that is configured to change the size of the project to a.01
and the state of the project to running
:
"spec": {
"plan": "a.01",
"desiredState": "running"
}
When updating the state of a project, consider the following:
- You can pause a project only when it is in a
running
state. - You cannot update the
desiredState
of a deleted project.
If an unsupported value is supplied, Polaris returns a HTTP 400 Bad Request
status code.
Sample request
The following example shows how to change the size of a project to a.01
and update the project's state to running
:
- cURL
- Python
curl --location --request PATCH "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669" \
--user ${POLARIS_API_KEY}: \
--header "Content-Type: application/merge-patch+json" \
--data-raw '{
"spec": {
"plan": "a.01",
"desiredState": "running"
}
}'
import os
import requests
import json
url = "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669"
apikey = os.getenv("POLARIS_API_KEY")
payload = json.dumps({
"spec": {
"plan": "a.01",
"desiredState": "running"
}
})
headers = {
'Content-Type': 'application/merge-patch+json',
'Authorization': f'Basic {apikey}'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
Sample response
The following example shows a successful response:
{
"metadata": {
"uid": "45c024f4-1234-5678-8207-4111d2f80669",
"name": "Docs project",
"createdOnTimestamp": "2023-09-17T04:04:32.395Z"
},
"spec": {
"plan": "a.01",
"desiredState": "running",
"deletionProtection": false,
"region": "us-east-1"
},
"status": {
"maxBytes": 100000000000,
"currentBytes": 0,
"state": "resuming",
"version": "eac42c64"
}
}
It may take a few minutes for the project's state to update.
To verify that the project has been updated, send a GET
request to the /v1/projects/PROJECT_ID
endpoint.
Learn more
See the following topics for more information:
- Billing overview for reference on the pricing structure of Polaris.
- Monitor account usage for information on monitoring account usage from the Polaris UI.
- API reference for reference on the Polaris APIs.