Skip to main content

Create and manage projects by API

A project is a base entity that holds tables, data sources, files, jobs, visualizations, alerts, and reports. Each organization can have up to 25 projects per region.

This topic explains how to create and manage projects using the Projects v1 API. For information on how to manage projects in the UI, see Create and manage projects.

In this topic, all API endpoints are relative to the base URL https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io.

Prerequisites​

You must have an API key with the AdministerProjects permission. 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.

List all projects in a region​

To list all projects in a given region, send a GET request to the /v1/projects endpoint.

Sample request​

The following example shows how to retrieve a list of projects for a given region:

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

Sample response​

The following example shows a successful response:

[
  {
    "metadata": {
      "uid": "3b538a72-1234-5678-9101-632e91301e95",
      "name": "Eng US - Prod",
      "createdOnTimestamp": "2021-12-21T22:28:44.457Z"
    },
    "spec": {
      "plan": "a.01",
      "desiredState": "running",
      "deletionProtection": true,
      "stopProtection": false,
      "region": "us-east-1"
    },
    "status": {
      "maxBytes": 100000000000,
      "currentBytes": 46814050434,
      "deepStorageBytes": 32195579229,
      "state": "running",
      "version": "15f46a6e"
    }
  },
  {
    "metadata": {
      "uid": "5c9116aa-1234-5678-9101-8e45300c961a",
      "name": "Eng US - Dev",
      "createdOnTimestamp": "2023-09-08T23:11:46.636Z"
    },
    "spec": {
      "plan": "starter",
      "desiredState": "running",
      "deletionProtection": false,
      "stopProtection": false,
      "region": "us-east-1"
    },
    "status": {
      "maxBytes": 25000000000,
      "currentBytes": 1845579,
      "deepStorageBytes": 0,
      "state": "running",
      "version": "15f46a6e"
    }
  }
]

Get project details​

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.

The JSON response includes currentBytes and deepStorageBytes, which represent the amount of precached data and data only in deep storage, respectively. You can calculate the total size of the project as currentBytes + deepStorageBytes.

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"

Sample response​

The following example shows a successful response:

{
  "metadata": {
    "uid": "5c9116aa-1234-5678-9101-8e45300c961a",
    "name": "Eng US - Dev",
    "createdOnTimestamp": "2023-09-08T23:11:46.636Z"
  },
  "spec": {
    "plan": "starter",
    "desiredState": "running",
    "deletionProtection": false,
    "stopProtection": false,
    "region": "us-east-1"
  },
  "status": {
    "maxBytes": 25000000000,
    "currentBytes": 1845579,
    "deepStorageBytes": 0,
    "state": "running",
    "version": "15f46a6e"
  }
}

Create a project​

To create a project, send a POST request to the /v1/projects endpoint.

Sample request​

The following example shows how to create a new project:

curl --location --request POST "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "metadata": {
        "name": "Polaris test project"
    },
    "spec": {
        "plan": "starter"
    }
}'

Sample response​

The following example shows a successful response:

{
  "metadata": {
    "uid": "a20a3e03-ca95-4ba0-aeff-40255758c75c",
    "name": "Polaris test project",
    "createdOnTimestamp": "2024-11-07T19:09:17.634Z"
  },
  "spec": {
    "plan": "starter",
    "desiredState": "running",
    "deletionProtection": false,
    "stopProtection": false,
    "region": "us-east-1"
  },
  "status": {
    "maxBytes": 25000000000,
    "currentBytes": 0,
    "deepStorageBytes": 0,
    "state": "creating",
    "version": "15f46a6e"
  }
}

Delete a project​

Deleting a project is irreversible. When you delete a project, you also delete all of the project's assets, including tables, files, jobs, and connections. To prevent accidental deletion of a project, set the project's deletionProtection property to true.
For information about pausing or stopping a project, see Update a project.

Each organization must have at least one project. You can't delete the last project in the organization. You can delete the last project in a region as long as you have another project in a different region within the same organization.

To delete a project, send a DELETE request to the /v1/projects/PROJECT_ID endpoint. Replace PROJECT_ID with the ID of your project.

Sample request​

The following example shows how to delete a project:

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

Sample response​

A successful response returns an HTTP 202 Accepted status code.

Learn more​

See the following topics for more information: