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 process. This API allows you to add, modify, delete, and list projects.

Project Object

{
  "name": "default-project",
  "id": "c683b988-aa93-439c-a9ac-0d7f72b53d23",
  "type": "QUERY_ENGINE",
  "cloudId": "dremio-aws-us-east-1",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "2023-08-19T14:39:38Z",
  "modifiedAt": "2023-08-19T14:39:46Z",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "IAM_ROLE",
    "roleArn": "arn:aws:iam::362243112345:role/CustomerRole",
    "externalId": "c683b988-aa93-439c-a9ac-0d7f72b53d23"
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "catalog": {
    "storageLocation": "my.dremio.store"
  }
}

Project Attributes

name String

User-defined name for a project.

Example: my-first-project

id String (UUID)

UUID of the project.

type String

Type of the project.

Example: QUERY_ENGINE

cloudId String

Designation for cloud type and region.

Example: dremio-aws-us-east-1

state String

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

Valid Values: CREATING, ACTIVE, ARCHIVING, ARCHIVED, RESTORING, DEACTIVATING, INACTIVE, ACTIVATING

Example: ACTIVE

createdBy String (UUID)

UUID of the user who created the project.

modifiedBy String (UUID)

UUID of the user who last modified the project.

createdAt String

Timestamp when the project was created.

modifiedAt String

Timestamp when the project was last modified.

projectStore String

The external storage location for project metadata.

Example: my.dremio.store

credentials Object

The credentials used to access external project storage.

numberOfEngines Integer

Number of engines that manage compute resources for the project.

cloudType String

Type of the cloud where the project is saved; must be AWS.

catalog Object

Attributes of the catalog included within the project.

lastStateError Object

Information about any invalid credentials error for the project. Included only if the project credentials are invalid.

Attributes of the `credentials` Object

type String

The type of credential to use to access external project storage. The only valid value is IAM_ROLE.

Example: IAM_ROLE

roleArn String

For projects created on AWS clouds, the cross-account role Dremio uses to access the project store bucket. To create this IAM role, you must use the appropriate Dremio trust account ID.

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

externalId String (UUID)

UUID that is the same as the id of the project.

Attributes of the `lastStateError` Object

timestamp String

The time at which the project credentials became invalid, in 13-digit Unix timestamp format.

Example: 1707339965231

error String

The type of error. The value is always INVALID_CREDENTIALS.

Attributes of the `catalog` Object

storageLocation String

The external storage location for catalog tables and views.

Example: my.dremio.store

List All Projects

Method and URL

GET /v0/projects

Example

Request

curl -X GET 'https://api.dremio.cloud/v0/projects' \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

Response

[
  {
    "name": "default-project",
    "id": "c683b988-aa93-439c-a9ac-0d7f72b53d23",
    "type": "QUERY_ENGINE",
    "cloudId": "dremio-aws-us-east-1",
    "state": "ACTIVE",
    "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
    "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
    "createdAt": "2023-08-19T14:39:38Z",
    "modifiedAt": "2023-08-19T14:39:46Z",
    "projectStore": "my.dremio.store",
    "credentials": {
      "type": "IAM_ROLE",
      "roleArn": "arn:aws:iam::362243112345:role/CustomerRole",
      "externalId": "c683b988-aa93-439c-a9ac-0d7f72b53d23"
    },
    "numberOfEngines": 2,
    "cloudType": "AWS",
    "catalog": {
      "storageLocation": "my.dremio.store"
    }
  }
]

Response Status Codes

200 OK

403 Forbidden

Add a Project

Method and URL

POST /v0/projects

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

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 recognize subsequent retries of the same request. Generate the request ID by using a UUID generator tool. See idempotent requests for more information.

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

cloudId Body String

The cloud and region designation for storage for this project.

Example: dremio-aws-us-east-1

projectStore Body String

The external storage location for project metadata.

Example: my.dremio.store

credentials Body Object

The credentials used to access external project storage.

type Body String Optional

Type of the project.

Example: QUERY_ENGINE

Parameters of the `credentials` Object

type Body String

The type of credential to use to access external project storage. The only valid value is IAM_ROLE.

Example: IAM_ROLE

roleArn Body String

For projects created on AWS clouds, the cross-account role Dremio uses to access the project store bucket. To create this IAM role, you must use the appropriate Dremio trust account ID.

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

Example

Request

curl -X POST 'https://api.dremio.cloud/v0/projects' \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "name": "docproject",
  "requestId": "a7801e74-6c34-48b4-9e42-2cacdf06d31c",
  "cloudId": "dremio-aws-us-east-1",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "IAM_ROLE",
    "roleArn": "arn:aws:iam::362243112345:role/CustomerRole"
  },
  "type": "QUERY_ENGINE"
}'

Response

{
  "name": "docproject",
  "id": "05e2d620-5978-4269-8c96-aa463df830b7",
  "cloudId": "dremio-aws-us-east-1",
  "type": "QUERY_ENGINE",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "2023-08-21T12:22:51Z",
  "modifiedAt": "2023-08-21T12:22:59Z",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "IAM_ROLE",
    "roleArn": "arn:aws:iam::362243142826:role/CustomerRole",
    "externalId": "05e2d620-5978-4269-8c96-aa463df830b7"
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "catalog": {
    "storageLocation": "my.dremio.store"
  }
}

Response Status Codes

200   OK

400   Bad Request

403   Forbidden

500   Internal Server Error

Retrieve a Project

Method and URL

GET /v0/projects/{id}

Parameters

id Path String (UUID)

UUID of the project.

Example

Request

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

Response

{
  "name": "docproject",
  "id": "05e2d620-5978-4269-8c96-aa463df830b7",
  "cloudId": "dremio-aws-us-east-1",
  "type": "QUERY_ENGINE",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "2023-08-21T12:22:51Z",
  "modifiedAt": "2023-08-21T12:22:59Z",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "IAM_ROLE",
    "roleArn": "arn:aws:iam::362243142826:role/CustomerRole",
    "externalId": "05e2d620-5978-4269-8c96-aa463df830b7"
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "catalog": {
    "storageLocation": "my.dremio.store"
  }
}

Response Status Codes

200   OK

400   Bad Request

403   Forbidden

Modify a Project

Method and URL

PUT /v0/projects/{id}

Parameters

id Path String (UUID)

UUID of the project.

name Body String Optional

User-defined name for the project.

Example: doc-project

credentials Body Object Optional

The credentials used to access external project storage.

Parameters of the `credentials` Object

type Body String

The type of credential to use to access external project storage. The only valid value is IAM_ROLE.

Example: IAM_ROLE

roleArn Body String

For projects created on AWS clouds, the cross-account role Dremio uses to access the project store bucket. To create this IAM role, you must use the appropriate Dremio trust account ID.

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

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "name": "doc-project"
}'

Response

{
  "name": "doc-project",
  "id": "05e2d620-5978-4269-8c96-aa463df830b7",
  "cloudId": "dremio-aws-us-east-1",
  "type": "QUERY_ENGINE",
  "state": "ACTIVE",
  "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
  "createdAt": "2023-08-21T12:22:51Z",
  "modifiedAt": "2023-08-21T12:22:59Z",
  "projectStore": "my.dremio.store",
  "credentials": {
    "type": "IAM_ROLE",
    "roleArn": "arn:aws:iam::362243142826:role/CustomerRole",
    "externalId": "05e2d620-5978-4269-8c96-aa463df830b7"
  },
  "numberOfEngines": 2,
  "cloudType": "AWS",
  "catalog": {
    "storageLocation": "my.dremio.store"
  }
}

Response Status Codes

200 OK

400 Bad Request

Delete a Project

Method and URL

DELETE /v0/projects/{id}

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

Parameters

id Path String (UUID)

UUID of the project.

Example

Request

curl -X DELETE "https://api.dremio.cloud/v0/projects/$PROJECT_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes

204 No Content

500 Internal Server Error

Project Attributes​

Attributes of the credentials Object​

Attributes of the lastStateError Object​

Attributes of the catalog Object​

List All Projects​

Example​

Response Status Codes​

Add a Project​

Parameters​

Parameters of the credentials Object​

Example​

Response Status Codes​

Retrieve a Project​

Parameters​

Example​

Response Status Codes​

Modify a Project​

Parameters​

Parameters of the credentials Object​

Example​

Response Status Codes​

Delete a Project​

Parameters​

Example​

Response Status Codes​

Project Attributes

Attributes of the `credentials` Object

Attributes of the `lastStateError` Object

Attributes of the `catalog` Object

List All Projects

Example

Response Status Codes

Add a Project

Parameters

Parameters of the `credentials` Object

Example

Response Status Codes

Retrieve a Project

Parameters

Example

Response Status Codes

Modify a Project

Parameters

Parameters of the `credentials` Object

Example

Response Status Codes

Delete a Project

Parameters

Example

Response Status Codes