Skip to main content

Update a project by API

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 plan and state, including pausing or stopping the project.

This topic explains how to change the plan 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, see 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 retrieve information about a specific project, send a GET request to the /v1/projects/PROJECT_ID endpoint. Replace PROJECT_ID with the ID of your project.

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 get project details:

curl --location --request GET "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID" \
--header "Authorization: Basic $POLARIS_API_KEY"

Samples response​

The following example shows a successful response:

{
  "metadata": {
    "uid": "f683410c-0123-4567-8910-9a584f2727b7",
    "name": "imply-docs",
    "createdOnTimestamp": "2023-10-12T00:54:38.240Z"
  },
  "spec": {
    "plan": "starter",
    "desiredState": "paused",
    "deletionProtection": false,
    "stopProtection": false,
    "region": "us-east-1"
  },
  "status": {
    "maxBytes": 25000000000,
    "currentBytes": 0,
    "deepStorageBytes": 0,
    "state": "paused",
    "version": "15f46a6e"
  }
}

Update a project​

You can update a project's name, plan, and state, as well as enable protections to prevent accidental pausing, stopping, or deletion.

To prevent pausing and stopping of a project, set the stopProtection property to true. For deletion protection, set the deletionProtection property to true.

When sizing down, ensure that your data size fits within the selected storage capacity. Exceeding capacity can cause issues with project resizing or during automatic Polaris upgrades. To manage data volume effectively and reduce manual maintenance, configure a storage policy to remove older data. For more information on storage policies, see Data lifecycle management.

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 a project's plan and state, configure the spec object as follows:

  • Set the plan property to the desired plan. See Polaris plans for details.
  • Set the desiredState property to the desired state of the project:
    • running: Resumes the project.
    • paused: Pauses the project while preserving all data and assets.
    • stopped: Stops the project. Polaris removes all data and assets from the project.

The following example shows a spec object configured to update the project's plan to a.01 and set its state to running:

{
  "spec": {
    "plan": "a.01",
    "desiredState": "running"
  }
}

When updating a project's state, consider the following:

  • You can pause a project only when it's in running state.
  • To prevent accidental pausing and stopping, set stopProtection to true.
  • To prevent accidental deletion, set deletionProtection to true.
  • You can't update a project in resuming state.
  • You can't update the state of a deleted project.

If you supply an unsupported value, Polaris returns a HTTP 400 Bad Request status code.

Sample request​

The following example shows how to change the project's plan and state:

curl --location --request PATCH "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID" \
--header "Authorization: Basic $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": "f683410c-0123-4567-8910-9a584f2727b7",
    "name": "imply-docs",
    "createdOnTimestamp": "2023-10-12T00:54:38.240Z"
  },
  "spec": {
    "plan": "a.01",
    "desiredState": "running",
    "deletionProtection": false,
    "stopProtection": false,
    "region": "us-east-1"
  },
  "status": {
    "maxBytes": 100000000000,
    "currentBytes": 0,
    "deepStorageBytes": 0,
    "state": "resuming",
    "version": "15f46a6e"
  }
}

It may take a few minutes for the project 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: