Skip to main content

Projects

A project is the logical entity for isolating compute, data and other resources needed by a team for data analysis. An organization may contain multiple projects. Projects are linked to your cloud account - your first project was created and linked to your cloud account as part of the signup. This API allows you to add, modify, delete and list projects.

Project Object (AWS Example)
[
  {
    "name": "default-project",
    "id": "c683b988-aa93-439c-a9ac-0d7f72b53d23",
    "type": "QUERY_ENGINE",
    "cloudId": "37b34779-13f1-48e5-b2c8-f3db4c824733",
    "state": "ACTIVE",
    "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
    "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
    "createdAt": "Thu Aug 19 14:39:38 UTC 2023",
    "modifiedAt": "Thu Aug 19 14:39:46 UTC 2023",
    "projectStore": "my.dremio.store",
    "credentials": {
      "type": "ACCESS_KEY",
      "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
      "secretAccessKey": null
    },
    "numberOfEngines": 2,
    "cloudType": "AWS",
    "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
  }
]
Project Object (Azure Example)
[
  {
    "name": "azure-project",
    "id": "09d9e30d-0b10-4ea7-821c-8e902c47f908",
    "type": "QUERY_ENGINE",
    "cloudId": "3986c088-93f1-41b8-a45a-d51831478f71",
    "state": "ACTIVE",
    "createdBy": "c2697d8e-d455-495c-ae56-a5ce30d1b02e",
    "modifiedBy": "c2697d8e-d455-495c-ae56-a5ce30d1b02e",
    "createdAt": "Mon Oct 23 14:08:50 UTC 2023",
    "modifiedAt": "Mon Oct 23 14:08:54 UTC 2023",
    "projectStore": "teststoragecontainer",
    "credentials": {
      "type": "AZURE_STORAGE_CLIENT_CREDENTIALS",
      "tenantId": "10070cc4-8877-4b2b-a8c8-b5c7e640d1cd",
      "clientId": "ba71d0bb-d8ef-43b4-be0f-0cc5d080449b",
      "clientSecret": "secret",
      "accountName": "testaccount"
    },
    "numberOfEngines": 3,
    "cloudType": "AZURE",
    "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
  }
]

Project Attributes​

name

String

User defined name for a project.

Example my-first-project

id

String (UUID)

Unique identifier of a project.

Example c683b988-aa93-439c-a9ac-0d7f72b53d23

type

String

Type of the project.

Example QUERY_ENGINE

cloudId

String (UUID)

The ID of the cloud where compute resources will be created.

Example 37b34779-13f1-48e5-b2c8-f3db4c824733

state

String

The current state of the project. If the state is ARCHIVING, ARCHIVED, or RESTORING, only users having the OWNERSHIP privilege on a project or users in the ADMIN role will have access to the project.

Enum CREATING, ACTIVE, ARCHIVING, ARCHIVED, RESTORING, DEACTIVATING, INACTIVE, ACTIVATING

Example ACTIVE

createdBy

String (UUID)

The unique identifier for the user that created the project.

Example de8a47bf-432a-4d83-b60e-90d86cda8d70

modifiedBy

String (UUID)

The unique identifier for the user that last modified the project.

Example de8a47bf-432a-4d83-b60e-90d86cda8d70

createdAt

String

Date and time that the project was created.

Example Thu Aug 19 14:39:38 UTC 2023

modifiedAt

String

Date and time that the cloud was last modified.

Example Thu Aug 19 14:39:46 UTC 2023

projectStore

String

The Amazon S3 bucket or Azure storage container that Dremio Cloud uses to store metadata for this project.

Example my.dremio.store

credentials

object

The credentials used to configure the storage settings for the cloud.

numberOfEngines

Integer

Number of engines that manage compute resources for the project.

Example 2

cloudType

String

Type of the cloud where the project is saved.

Enum AWS, AZURE, UNKNOWN

Example AWS

primaryCatalogId

String (UUID)

The unique identifier for the project's primary Arctic catalog.

Example cc9d3b9c-4b16-01ed-8067-d1f871042d9f

credentials​

type

String

The type of credentials used to configure the storage settings for the project. For projects created on AWS clouds, the value is either ACCESS_KEY or IAM_ROLE. For projects created on Azure clouds, the value is AZURE_APP_CLIENT_CREDENTIALS.

Example ACCESS_KEY

accessKeyId

String

For projects created on AWS clouds, the access key generated from the AWS IAM User you created to provide Dremio Cloud with storage capabilities. This field is required if you selected ACCESS_KEY for credentials.

Example AKIAJIPU77TQL8LR6OIR

secretAccessKey

String

For projects created on AWS clouds, the secret key generated from the AWS IAM User you created to provide Dremio Cloud with storage access. This field is required if you selected ACCESS_KEY for credentials. The value is returned as null in API responses.

Example vJalrXUtnFEMI/K7MDENG/bPxRfiDYEXAMPLEKEY

roleArn

String

For projects created on AWS clouds, the cross-account role used to access the project store bucket. To create this IAM Role, you need to provide the Trust Account ID (572051091487) and External ID. This field is required if you selected IAM_ROLE for credentials.

Example arn:aws:iam::461138020052:role/CustomerRole

instanceProfileArn

String

For projects created on AWS clouds, the instance profile used by Dremio Cloud engines to access the project store bucket. This field is required if you selected IAM_ROLE for credentials. The value is returned as null in API responses.

Example arn:aws:iam::461138020052:instance-profile/InstanceRole

externalId

String

An ID required to identify Dremio Cloud as a provider. This field is required if you selected IAM_ROLE for credentials. The value is returned as null in API responses.

Example c9560ff9-2c21-472b-8d9e-139eaab6bb49

tenantId

String (UUID)

For projects created on Azure clouds, the ID of the Azure tenant used for the cloud.

Example 10070cc4-8877-4b2b-a8c8-b5c7e640d1cd

clientId

String (UUID)

For projects created on Azure clouds, the application (client) ID of the registered app used for compute access.

Example ba71d0bb-d8ef-43b4-be0f-0cc5d080449b

clientSecret

String

For projects created on Azure clouds, the client secret you created in the registered app used for compute access. To keep the secret secure, Dremio returns the clientSecret value as secret in API responses.

Example secret

accountName

String

For projects created on Azure clouds, the name of the Azure storage account used for compute access.

Example testaccount

Listing All Projects​

Returns a list of all the projects and the metadata for each project.

Listing All Projects
GET /v0/projects
Example Request
curl -X GET 'https://api.dremio.cloud/v0/projects' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
[
  {
    "name": "default-project",
    "id": "c683b988-aa93-439c-a9ac-0d7f72b53d23",
    "type": "QUERY_ENGINE",
    "cloudId": "37b34779-13f1-48e5-b2c8-f3db4c824733",
    "state": "ACTIVE",
    "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
    "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
    "createdAt": "Thu Aug 19 14:39:38 UTC 2023",
    "modifiedAt": "Thu Aug 19 14:39:46 UTC 2023",
    "projectStore": "my.dremio.store",
    "credentials": {
      "type": "ACCESS_KEY",
      "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
      "secretAccessKey": null
    },
    "numberOfEngines": 2,
    "cloudType": "AWS",
    "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
  },
  {
    "name": "azure-project",
    "id": "09d9e30d-0b10-4ea7-821c-8e902c47f908",
    "type": "QUERY_ENGINE",
    "cloudId": "3986c088-93f1-41b8-a45a-d51831478f71",
    "state": "ACTIVE",
    "createdBy": "c2697d8e-d455-495c-ae56-a5ce30d1b02e",
    "modifiedBy": "c2697d8e-d455-495c-ae56-a5ce30d1b02e",
    "createdAt": "Mon Oct 23 14:08:50 UTC 2023",
    "modifiedAt": "Mon Oct 23 14:08:54 UTC 2023",
    "projectStore": "teststoragecontainer",
    "credentials": {
      "type": "AZURE_STORAGE_CLIENT_CREDENTIALS",
      "tenantId": "10070cc4-8877-4b2b-a8c8-b5c7e640d1cd",
      "clientId": "ba71d0bb-d8ef-43b4-be0f-0cc5d080449b",
      "clientSecret": "secret",
      "accountName": "testaccount"
    },
    "numberOfEngines": 3,
    "cloudType": "AZURE",
    "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
  }
]

Responses​

200

OK

403

Forbidden

Adding a Project​

Add a project.

Adding a Project
POST /v0/projects

Parameters​

Project​

name

body

String

User defined name for the project.

Example docproject

requestId

body

string (UUID)

Optional

User-defined idempotency key, which is a unique value generated by the user that the server uses to register consequent retries of the same request. Generate the request ID by using a UUID generator tool.

For more information, read idempotent requests.

Example a7801e74-6c34-48b4-9e42-2cacdf06d31c

cloudId

body

String (UUID)

The ID of the cloud where compute resources will be created.

Example 37b34779-13f1-48e5-b2c8-f3db4c824733

projectStore

body

string

The Amazon S3 bucket or Azure storage container for Dremio Cloud to use to store metadata for this project.

Example my.dremio.store

credentials

body

object

The credentials for Dremio to use to configure the storage settings for the cloud

type

String

Optional

Type of the project.

Example QUERY_ENGINE

catalogName

String

For projects that use an AWS compute environment, the name to use for the project's primary Arctic catalog. The catalogName can contain only alphanumeric characters, underscores, and hyphens. The catalogName cannot match the name of an existing Arctic catalog.

credentials​

type

body

String

The type of credentials to use to configure the storage settings for the cloud. For projects created on AWS clouds, the value is either ACCESS_KEY or IAM_ROLE. For projects created on Azure clouds, the value is AZURE_APP_CLIENT_CREDENTIALS.

Example ACCESS_KEY

accessKeyId

body

String

For projects created on AWS clouds, the access key generated from the AWS IAM User you created to provide Dremio Cloud with storage capabilities. This field is required if you selected ACCESS_KEY for credentials.

Example AKIAJIPU77TQL8LR6OIR

secretAccessKey

body

String

For projects created on AWS clouds, the secret key generated from the AWS IAM User you created to provide Dremio Cloud with storage access. This field is required if you selected ACCESS_KEY for credentials.

Example vJalrXUtnFEMI/K7MDENG/bPxRfiDYEXAMPLEKEY

roleArn

body

String

For projects created on AWS clouds, the cross-account role Dremio Cloud uses to access the project store bucket. To create this IAM Role, you need to provide the Trust Account ID (572051091487) and External ID. This field is required if you selected IAM_ROLE for credentials.

Example arn:aws:iam::461138020052:role/CustomerRole

instanceProfileArn

body

String

For projects created on AWS clouds, the instance profile used by Dremio Cloud engines to access the project store bucket. This field is required if you selected IAM_ROLE for credentials.

Example arn:aws:iam::461138020052:instance-profile/InstanceRole

externalId

body

String

For projects created on AWS clouds, the ID required to identify Dremio Cloud as a provider. This field is required if you selected IAM_ROLE for credentials.

Example c9560ff9-2c21-472b-8d9e-139eaab6bb49

tenantId

body

String (UUID)

For projects created on Azure clouds, the ID of the Azure tenant used for the cloud.

Example 10070cc4-8877-4b2b-a8c8-b5c7e640d1cd

clientId

body

String (UUID)

For projects created on Azure clouds, the application (client) ID of the registered app used for compute access.

Example ba71d0bb-d8ef-43b4-be0f-0cc5d080449b

clientSecret

body

String

For projects created on Azure clouds, the client secret you created in the registered app used for compute access.

Example odj+a]xWAk2E*2.WmjU0wtfiLEXAMPLE

accountName

body

String

For projects created on Azure clouds, the name of the Azure storage account used for compute access.

Example testaccount


Example Request to Add a Project on an AWS Cloud
curl -X POST 'https://api.dremio.cloud/v0/projects' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json' \
-d '{
  "name": "docproject",
  "requestId": "a7801e74-6c34-48b4-9e42-2cacdf06d31c",
  "cloudId": "37b34779-13f1-48e5-b2c8-f3db4c824733",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "ACCESS_KEY",
    "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
    "secretAccessKey": "vJalrXUtnFEMI/K7MDENG/bPxRfiDYEXAMPLEKEY"
  },
  "type": "QUERY_ENGINE"
}'
Example Response to Add a Project on an AWS Cloud
{
  "name": "docproject",
  "id": "05e2d620-5978-4269-8c96-aa463df830b7",
  "type": "QUERY_ENGINE",
  "cloudId": "37b34779-13f1-48e5-b2c8-f3db4c824733",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "Sat Aug 21 12:22:51 UTC 2023",
  "modifiedAt": "Sat Aug 21 12:22:59 UTC 2023",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "ACCESS_KEY",
    "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
    "secretAccessKey": null
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
}

Example Request to Add a Project on an Azure Cloud
curl -X POST 'https://api.dremio.cloud/v0/projects' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json' \
-d '{
  "name": "azure-project",
  "requestId": "ex301e74-6c34-48b4-9e42-72d00f0d6c71",
  "cloudId": "b913a696-449b-4005-8d99-cdd302c5fe82",
  "projectStore": "teststoragecontainer",
  "credentials": {
    "type": "AZURE_STORAGE_CLIENT_CREDENTIALS",
    "tenantId": "10070cc4-8877-4b2b-a8c8-b5c7e640d1cd",
    "clientId": "ba71d0bb-d8ef-43b4-be0f-0cc5d080449b",
    "clientSecret": "odj+a]xWAk2E*2.WmjU0wtfiLEXAMPLE",
    "accountName": "testaccount"
  }
}'
Example Response to Add a Project on an Azure Cloud
{
  "name": "azure-project",
  "id": "09d9e30d-0b10-4ea7-821c-8e902c47f908",
  "type": "QUERY_ENGINE",
  "cloudId": "3986c088-93f1-41b8-a45a-d51831478f71",
  "state": "ACTIVE",
  "createdBy": "c2697d8e-d455-495c-ae56-a5ce30d1b02e",
  "modifiedBy": "c2697d8e-d455-495c-ae56-a5ce30d1b02e",
  "createdAt": "Mon Oct 23 14:08:50 UTC 2023",
  "modifiedAt": "Mon Oct 23 14:08:54 UTC 2023",
  "projectStore": "teststoragecontainer",
  "credentials": {
      "type": "AZURE_STORAGE_CLIENT_CREDENTIALS",
      "tenantId": "10070cc4-8877-4b2b-a8c8-b5c7e640d1cd",
      "clientId": "ba71d0bb-d8ef-43b4-be0f-0cc5d080449b",
      "clientSecret": "secret",
      "accountName": "testaccount"
  },
  "numberOfEngines": 3,
  "cloudType": "AZURE",
  "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
}

Responses​

200

OK

400

Bad Request

403

Forbidden

500

Internal Server Error

Retrieving a Project​

Get the project metadata for an existing project by providing the project ID that was returned on creation of the project.

Retrieiving a Project
GET /v0/projects/{id}

Parameters​

id

path

String (UUID)

The ID of the project for which you want to retrieve metadata.

Example Request
curl -X GET 'https://api.dremio.cloud/v0/projects/05e2d620-5978-4269-8c96-aa463df830b7' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
{
  "name": "docproject",
  "id": "05e2d620-5978-4269-8c96-aa463df830b7",
  "type": "QUERY_ENGINE",
  "cloudId": "37b34779-13f1-48e5-b2c8-f3db4c824733",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "Sat Aug 21 12:22:51 UTC 2023",
  "modifiedAt": "Sat Aug 21 12:22:59 UTC 2023",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "ACCESS_KEY",
    "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
    "secretAccessKey": null
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
}

Responses​

200

OK

400

Bad Request

403

Access denied. You do not have OWNERSHIP privilege on the project.

Modifying a Project​

Modify the project by providing the project ID that was returned on creation of the project. Parameters that are not provided will be left unchanged.

note

Currently only the name of a project can be modified.

Modifying a Project
PUT /v0/projects/{id}

Parameters​

id

path

String (UUID)

The ID of the project you want to update.

name

body

String

Optional

User defined name for the project.

Example Request
curl -X PUT 'https://api.dremio.cloud/v0/projects/05e2d620-5978-4269-8c96-aa463df830b7' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json' \
-d '{
    "name": "doc-project" 
 }'
Example Response
{
  "name": "doc-project",
  "id": "05e2d620-5978-4269-8c96-aa463df830b7",
  "type": "QUERY_ENGINE",
  "cloudId": "37b34779-13f1-48e5-b2c8-f3db4c824733",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "Sat Aug 21 12:22:51 UTC 2023",
  "modifiedAt": "Sat Aug 21 12:22:59 UTC 2023",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "ACCESS_KEY",
    "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
    "secretAccessKey": null
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "primaryCatalogId": "cc9d3b9c-4b16-01ed-8067-d1f871042d9f"
}

Responses​

200

OK

400

Bad Request

Deleting a Project​

Delete the project by providing the project ID that was returned on creation of the project.

note

Dremio Cloud does not allow you to delete a project that is the only project in an organization.

Deleting a Project
DELETE /v0/projects/{id}

Parameters​

id

path

String

The ID of the project that you want to delete.

Example Request
curl -X DELETE 'https://api.dremio.cloud/v0/projects/05e2d620-5978-4269-8c96-aa463df830b7' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
No response

Responses​

200

OK

500

Internal Server Error