Skip to main content

Space

You can use the Catalog API to retrieve information about spaces and the child objects they contain, as well as to create and delete spaces. Spaces are top-level entities in the catalog; to create a folder inside a space, see Folder.

Space Object 
{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "s1",
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "createdAt": "2026-07-14T18:44:43.237Z",
  "children": [
    {
      "id": "f1ec2376-882e-406f-b37d-c97e8804b662",
      "path": [
        "s1",
        "test-folder"
      ],
      "tag": "eb3c936d-e476-4bfd-9738-1619e9da4c32",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    }
  ]
}

Space Attributes​

entityType String

For spaces, the entityType is space.

id String (UUID)

UUID of the space.

name String

The name of the space. Since a space is always a top-level entity, it is identified by name rather than by path. The name cannot contain a period (.), a double quote ("), or an @ character.

tag String (UUID)

UUID of the version of the space. Dremio changes this tag whenever a change is made to the space.

createdAt String

Timestamp when the space was created.

children Array of Object

List of items inside the space. See Attributes of Objects in the children Array for the shape of each item.

Add a Space​

Method and URL 
POST /v0/projects/{project_id}/catalog

Parameters​

project_id Path   String (UUID)

entityType Body   String

The type of catalog object. For spaces, the entityType is space.

name Body   String

The name of the space that you are creating. Cannot contain a period (.), a double quote ("), or an @ character.

Example​

Request 
curl -X POST "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
      "entityType": "space",
      "name": "s1"
    }'
Response 
{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "s1",
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "createdAt": "2026-07-14T18:44:43.237Z",
  "children": []
}

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

Retrieve a Space by ID​

Method and URL 
GET /v0/projects/{project_id}/catalog/{id}

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID of the space.

maxChildren Query   Integer   Optional

Specify the maximum number of child objects to include in each page of results. Use in concert with the pageToken parameter to split large sets of results into multiple pages. For more information, see the maxChildren query parameter.

Example: ?maxChildren=25

pageToken Query   String   Optional

Specify the token for retrieving the next page of results. Must be used in concert with the maxChildren parameter. If the space has more child objects than the specified maxChildren value, the response includes a nextPageToken attribute. Add the pageToken query parameter with the nextPageToken value to the request URL to retrieve the next page of results. See pageToken query parameter for more information.

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

exclude Query   String   Optional

When using exclude, the children field is excluded from the response. See the exclude query parameter for usage examples.

Example: ?exclude=children

Example​

Request 
curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$SPACE_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'
Response 
{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "s1",
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "createdAt": "2026-07-14T18:44:43.237Z",
  "children": [
    {
      "id": "f1ec2376-882e-406f-b37d-c97e8804b662",
      "path": [
        "s1",
        "test-folder"
      ],
      "tag": "eb3c936d-e476-4bfd-9738-1619e9da4c32",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    }
  ]
}

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

Retrieve a Space by Path​

Method and URL 
GET /v0/projects/{project_id}/catalog/by-path/{name}

Parameters​

project_id Path   String (UUID)

name Path   String

Name of the space, since a space is always a single path segment. If the name includes special characters for URLs, such as spaces, use URL encoding to replace the special characters with their UTF-8-equivalent characters.

maxChildren Query   Integer   Optional

Specify the maximum number of child objects to include in each page of results. Use in concert with the pageToken parameter to split large sets of results into multiple pages. For more information, see the maxChildren query parameter.

Example: ?maxChildren=25

pageToken Query   String   Optional

Specify the token for retrieving the next page of results. Must be used in concert with the maxChildren parameter. If the space has more child objects than the specified maxChildren value, the response includes a nextPageToken attribute. Add the pageToken query parameter with the nextPageToken value to the request URL to retrieve the next page of results. See pageToken query parameter for more information.

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

exclude Query   String   Optional

When using exclude, the children field is excluded from the response. See the exclude query parameter for usage examples.

Example: ?exclude=children

Example​

Request 
curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/by-path/s1" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'
Response 
{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "s1",
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "createdAt": "2026-07-14T18:44:43.237Z",
  "children": [
    {
      "id": "f1ec2376-882e-406f-b37d-c97e8804b662",
      "path": [
        "s1",
        "test-folder"
      ],
      "tag": "eb3c936d-e476-4bfd-9738-1619e9da4c32",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    }
  ]
}

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

Delete a Space​

Delete the specified space.

note

Only empty spaces can be deleted. If the space contains any child objects — folders, tables, views, or functions — the request fails with a 409 Conflict response. Delete all child objects in the space before deleting the space itself.

Method and URL 
DELETE /v0/projects/{project_id}/catalog/{id}

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID of the space.

Example​

Request 
curl -X DELETE "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$SPACE_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

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict