Skip to main content

Update a project via API

info

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 --location --request GET "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669" \
--user ${POLARIS_API_KEY}:

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

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: