Skip to main content

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 --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,
      "region": "us-east-1"
    },
    "status": {
      "maxBytes": 100000000000,
      "currentBytes": 89429124964,
      "state": "running",
      "version": "custom-097f85c2"
    }
  },
  {
    "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,
      "region": "us-east-1"
    },
    "status": {
      "maxBytes": 25000000000,
      "currentBytes": 17855983674,
      "state": "running",
      "version": "eac42c64"
    }
  }
]

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 --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-raw '{
        "metadata": {
            "name": "Example project"
        },
        "spec": {
            "plan": "starter"
        }
    }'

Sample response​

The following example shows a successful response:

{
    "metadata": {
        "uid": "566819a9-1234-5678-9101-84fab09078e2",
        "name": "Example project",
        "createdOnTimestamp": "2024-01-25T00:00:25.670Z"
    },
    "spec": {
        "plan": "starter",
        "desiredState": "running",
        "deletionProtection": false,
        "region": "us-east-1"
    },
    "status": {
        "maxBytes": 25000000000,
        "currentBytes": 0,
        "state": "creating",
        "version": "eac42c64"
    }
}

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 --location --request DELETE "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/68f3cab5-2e0c-4501-ae3e-150eb1acec6c" \
--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: