Create and manage projects

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, visit 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

curl --location --request GET 'https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects' \
--user ${POLARIS_API_KEY}:

Python

import requests

url = "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects"

payload={}
headers = {
  'Authorization': f'Basic {apikey}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Sample response

The following example shows a successful response:

[
    {
        "metadata": {
            "uid": "878b4e9c-8aee-4a78-9d88-9ade1333fa79",
            "name": "Polaris test project",
            "createdOnTimestamp": "2023-09-17T04:03:09.781Z"
        },
        "spec": {
            "plan": "a.01",
            "desiredState": "paused",
            "deletionProtection": false,
            "region": "us-east-1"
        },
        "status": {
            "maxBytes": 100000000000,
            "currentBytes": 0,
            "state": "paused"
        }
    },
    {
        "metadata": {
            "uid": "45c024f4-1254-4b58-8207-4111d2f80669",
            "name": "Docs project",
            "createdOnTimestamp": "2023-09-17T04:04:32.395Z"
        },
        "spec": {
            "plan": "starter",
            "desiredState": "running",
            "deletionProtection": false,
            "region": "us-east-1"
        },
        "status": {
            "maxBytes": 25000000000,
            "currentBytes": 0,
            "state": "running"
        }
    }
]

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 named Example project:

cURL

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

Python

import requests
import json

url = "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects"

payload = json.dumps({
  "metadata": {
    "name": "Example project"
  },
  "spec": {
    "plan": "starter"
  }
})
headers = {
  'Authorization': f'Basic {apikey}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Sample response

The following example shows a successful response:

{
    "metadata": {
        "uid": "5f364175-6be0-4ead-8c1e-7b106acd1d08",
        "name": "Example project",
        "createdOnTimestamp": "2023-09-17T04:05:29.870Z"
    },
    "spec": {
        "plan": "starter",
        "desiredState": "running",
        "deletionProtection": false,
        "region": "us-east-1"
    },
    "status": {
        "maxBytes": 25000000000,
        "currentBytes": 0,
        "state": "creating"
    }
}

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.

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.

Before you can delete a project, make sure that the project's deletionProtection property is set to false. You can't delete projects that have the deletionProtection property set to true.

To delete a project, send a DELETE request to the /v1/projects/PROJECT_ID endpoint.

Sample request

The following example shows how to delete a project with the project ID 68f3cab5-2e0c-4501-ae3e-150eb1acec6c:

cURL

curl --location --request DELETE 'https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/68f3cab5-2e0c-4501-ae3e-150eb1acec6c' \
--user ${POLARIS_API_KEY}:

Python

import requests

url = "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/68f3cab5-2e0c-4501-ae3e-150eb1acec6c"

payload={}
headers = {
  'Authorization': f'Basic {apikey}'
}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)

Sample response

A successful response returns an HTTP 202 Accepted status code.

Learn more

See the following topics for more information:

• Create and manage projects for information on managing projects in the Polaris UI.
• Update a project for information on how to update a project using the Projects v1 API.
• API reference for reference on the Polaris APIs.