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

Attributes of the credentials Object

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.

note

Adding a new project creates an engine named default of size 2XS in the new project.

Adding a Project
POST /v0/projects

Parameters

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. Read idempotent requests for more information.

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 Body   String   Optional

Type of the project.

Example: QUERY_ENGINE


catalogName Body   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.

Example: newCatalog

Parameters of the credentials Object

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: 05e2d620-5978-4269-8c96-aa463df830b7

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   Forbidden

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.

Example: 05e2d620-5978-4269-8c96-aa463df830b7


name Body   String   Optional

User defined name for the project.

Example: doc-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 (UUID)

The ID of the project you want to delete.

Example: 05e2d620-5978-4269-8c96-aa463df830b7

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