API Reference

The Dremio REST API provides programmatic access to manage your data infrastructure, execute queries, and configure data sources.

Make your first API call in minutes.

Base URLs

All REST endpoints build on one of the supported base URLs:

Dremio API – https://api.dremio.cloud/v0/
- Example: https://api.dremio.cloud/v0/projects to list all projects.
Dremio Login – https://login.dremio.cloud/
- Example: https://login.dremio.cloud/oauth/token to create an OAuth access token.
Iceberg Catalog REST – https://catalog.dremio.cloud/api/iceberg/v1/
- Example: https://catalog.dremio.cloud/api/iceberg/v1/namespaces to get Open Catalog namespaces using Iceberg Catalog REST.

Prerequisites

Access Token: Create a personal access token for authenticating each of your API calls. Before using your API application in production, Dremio recommends exchanging the PAT for an OAuth access token.
Project ID: Most Dremio API operations manage or use project resources such as the catalog, data sources, engines, and jobs. To copy your Project ID, click in the side navigation bar, select Project Settings, then copy the Project ID.

Example

List all catalog entries using the Dremio API

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

UUIDs

Many Dremio entities use Universally Unique Identifiers (UUIDs) as identifiers. UUIDs are 128-bit values displayed as 36 characters, such as 1e5f38e4-8209-46dc-96f0-cfbd3276dbd8. You'll receive UUIDs in API responses and use them in subsequent requests to reference specific resources, including projects, sources, datasets, and roles.

Dremio also uses UUIDs as version tags. When you retrieve an entity, the response includes a tag attribute containing a UUID that identifies the current version. When updating an entity, you must include this tag to ensure you're modifying the latest version and prevent conflicts from concurrent updates.

Idempotent Requests

Idempotence is an operation or service call that produces the same result when called multiple times. API endpoints support idempotency to safely retry requests without performing duplicate operations. This is helpful when an API request is interrupted in transit and a response is not received.

To create an idempotent request, add a requestId parameter to the request body. The value should be a unique generated UUID. The server uses this idempotency key to identify subsequent retries of the same API request and will return the same response without repeating the operation.

Only POST operations accept the idempotency key. To get a successful POST response for entities, you must add the requestId parameter in the corresponding POST request. Adding idempotent keys in PUT, GET, and DELETE operations has no impact as these methods are naturally idempotent.

An idempotent key can be reused after 24 hours in a new POST operation.

Timestamps

Dremio timestamps use ISO 8601 format in UTC: YYYY-MM-DDTHH:mm:ss.sssZ. For example, 2024-01-31T09:50:01.012Z represents January 31, 2024, at 9:50:01.012 AM UTC.

Query Parameters

Dremio supports query parameters for many API endpoints. The documentation for each API lists the supported query parameters for specific endpoints, along with any default and maximum values for the query parameters. The table below shows which endpoints support which query parameters.

Endpoint	Pagination	Filtering	Sorting	Fields
Catalog				`include`
Source	`pageToken`, `maxChildren`			`include`, `exclude`
Folder	`pageToken`, `maxChildren`			`include`, `exclude`
Data Maintenance	`pageToken`, `maxResults`	`filter`
Reflection Summary	`pageToken`, `maxResults`	`filter`	`orderBy`
Job Results	`limit`, `offset`
Scripts	`maxResults`, `offset`	`search`, `createdBy`, `ownedBy`	`orderBy`
Search	`pageToken`, `maxResults`	`filter`
User Defined Functions				`include`

`pageToken`

Use the pageToken query parameter to split large sets of results into multiple pages. When an endpoint supports pageToken, the response may include the continuation token under different field names:

Endpoint	Response Field
Data Maintenance	`pageToken`
Folder	`nextPageToken`
Reflection Summary	`nextPageToken`

Endpoints may support the pageToken query parameter based on either a built-in maximum number of results per page or a user-specified maximum that is established with a separate query parameter. The documentation for each API lists the built-in maximum or the query parameter to use to specify a maximum, as applicable.

note

Do not change any other query parameters included in the request URL when you use pageToken.

Built-in Maximum

If the endpoint has a built-in maximum number of results per page, responses automatically include a page token attribute when the response contains more results than the built-in maximum. Use the value for this token in the request URL as the pageToken value to retrieve the next page of results.

For example, the Reflection summary endpoint supports the pageToken parameter. If the reflection summary contains more than 50 results, the response will include the nextPageToken attribute. To retrieve the next 50 results, add ?pageToken={nextPageToken_value} to the request URL:

Example

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

For subsequent requests, replace the pageToken value in the request URL with the token value from the previous response. If the response does not include a token attribute and value, you have retrieved the last page of available results.

User-Specified Maximum

For endpoints that require users to specify a maximum number of results per page with a separate query parameter, responses only include a page token attribute if your initial request URL includes the separate query parameter and the response contains more results than the maximum you specify. Add the value for this token to the request URL as the pageToken value, keeping the separate query parameter as well, to retrieve the next page of results.

Catalog API endpoints for retrieving non-filesystem sources and folders by ID or path support the maxChildren query parameter for specifying the maximum number of child objects to include in each response. If the response contains more than the specified number of child objects, the response includes the nextPageToken attribute. To retrieve the next page of results, add ?pageToken={nextPageToken_value} to the request URL. This example shows a request URL that uses the pageToken query parameter with the maxChildren query parameter set to 25:

Example

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$SOURCE_ID?maxChildren=25&pageToken=BhQxNjc0MjhlYi03OTM2LTRlYTItYTFmYi0yM2IxYWM2ZTk0NTQSAA==" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

`maxResults`

Use the maxResults query parameter to specify the maximum number of results to retrieve in each request.

For example, if you want to retrieve no more than 25 results for an endpoint that supports the maxResults query parameter, append ?maxResults=25 to the request URL:

Example

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

`filter`

Use the filter query parameter to filter responses so that they include only results with the specified attributes and values. The value for the filter query parameter is a URL-encoded JSON string that represents a JSON object specifying the desired attributes and values.

For example, the Reflection summary endpoint supports the filter query parameter for certain specific attributes. To retrieve only the raw reflections that are refreshed manually or by schedule, are enabled, and apply to datasets with samples.dremio.com in their paths, the filter JSON object would look like this:

Example

{
  "reflectionType": ["RAW"],
  "refreshStatus": ["MANUAL","SCHEDULED"],
  "enabledFlag": true,
  "reflectionNameOrDatasetPath": "samples.dremio.com"
}

To use the JSON object as the filter value, convert it to URL-encoded JSON and add it to the request URL:

Example

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/reflection-summary?filter=%7B%0A%20%20%22reflectionType%22%3A%20%5B%22RAW%22%5D%2C%0A%20%20%22refreshStatus%22%3A%20%5B%22MANUAL%22%2C%22SCHEDULED%22%5D%2C%0A%20%20%22enabledFlag%22%3A%20true%2C%0A%20%20%22reflectionNameOrDatasetPath%22%3A%20%22samples.dremio.com%22%0A%7D" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

See the endpoint-specific documentation to learn which attributes each endpoint supports for the filter query parameter.

`limit`

The limit query parameter allows you to retrieve a specific number of results. For endpoints that support the limit query parameter, you can specify the number of results to retrieve. For example, if you only want to retrieve the first 10 available results, add ?limit=10 to the request URL:

Example

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/job/$JOB_ID/results?limit=10" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

`offset`

The offset query parameter allows you to skip a specific number of results in the response. When a response contains many results, you can use the limit and offset query parameters together to break the response into pages.

For example, consider a job result response object that contains 5,000 results. The Job API allows you to retrieve a maximum of 500 results per request. To retrieve all 5,000 results, start by adding ?limit=500 to the request URL to retrieve the first 500:

Example

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/job/$JOB_ID/results?limit=500" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

In the next request, to retrieve the next 500 results (rows 501–1,000), add &offset=500 to the request URL:

Example

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/job/$JOB_ID/results?limit=500&offset=500" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

To retrieve the next 500 results (rows 1,001–1,500), increment the offset parameter to 1,000 in the next request:

Example

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/job/$JOB_ID/results?limit=500&offset=1000" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

Continue incrementing the offset parameter in requests until you have retrieved all 5,000 results.

`include`

The include query parameter allows you to return the name of a non-default response field. You can retrieve either a list of access control list names (aclNames) or a list of permissions.

Example

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

`exclude`

The exclude query parameter allows you to exclude the children field from the response.

Example

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

`orderBy`

Use the orderBy query parameter to organize the response in ascending or descending order based on the value of the specified attribute. The default is ascending order. To specify descending order, add a - character before the attribute name.

For example, the Reflection summary endpoint supports ordering the response by reflectionName, datasetName, or reflectionType. To organize the response in ascending order by reflectionName:

Example

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

To organize the response in descending order, add a - before the attribute name:

Example

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

See the endpoint-specific documentation to learn which attributes each endpoint supports for the orderBy query parameter.

`createdBy`

Use the createdBy query parameter to limit the request to objects created by a specific user.

For example, this Scripts API request retrieves only scripts that were created by the user whose ID is 8be516f3-04c4-4d19-824d-5a70b3c4442e:

Example

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

`ownedBy`

Use the ownedBy query parameter to limit the request to objects owned by a specific user.

For example, this Scripts API request retrieves only scripts that are owned by the user whose ID is 8be516f3-04c4-4d19-824d-5a70b3c4442e:

Example

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

`search`

Use the search query parameter to limit the request to objects that contain values that include the search string.

For example, the Scripts API supports the search query parameter for the name attribute. This Scripts API request retrieves only scripts whose values for the name attribute include dev:

Example

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

See the documentation for each API to learn about endpoint-specific support for the search query parameter, including information about searchable attributes.

`maxChildren`

The maxChildren query parameter allows you to specify the maximum number of child objects to include in each response. This example shows a request URL that uses the maxChildren query parameter set to 25:

Example

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

Use the maxChildren query parameter in concert with the pageToken query parameter to split large sets of results into multiple pages.

Response Headers

Dremio API responses include HTTP headers that provide additional information about responses. Each header includes a case-insensitive name and a value, separated by a colon.

The following response headers are common to Dremio API endpoints:

Header Name	Example Value	Description
allow	GET,OPTIONS	Request methods the endpoint supports.
alt-svc	h3=":443"; ma=2592000,h3-29=":443"; ma=2592000	Information that allows servers to direct clients to load objects from a different server.
cache-control	no-cache, no-store	Caching instructions for browsers and shared caches.
content-length	418	Size of the response body, in bytes.
content-type	application/json	MIME type of the object.
date	Fri, 14 Apr 2023 19:11:08 GMT	Date and time when the response originated.
strict-transport-security	max-age=31536000; includeSubDomains	Instructions for browsers about accessing the server using HTTPS only, along with the duration (in seconds) that the client should remember the instructions.
vary	Accept-Encoding, User-Agent	Names of request headers that could have affected the response's generation.
x-content-type-options	nosniff	Instructions about following the MIME type in the content-type header. Blocks content sniffing.
x-request-id	34fbe950-8f02-974c-880a-467b61dcea86	Unique identifier the client generates and passes to the server so that requests can be correlated with server logs.
x-xss-protection	1; mode=block	Instructions used to stop pages from loading when a browser detects reflected cross-site scripting attacks.

Iceberg REST Catalog API

Open Catalog implements the Iceberg REST Catalog specification. The complete API specification, including endpoint definitions and request/response schemas, is available in the Iceberg REST Catalog API documentation.

Iceberg REST Catalog Example

#!/bin/bash

# Export the inputs 
export CATALOG_NAME=<your catalog name>
export USER_PAT=<your PAT token>
export BASE_URL=https://catalog.dremio.cloud/api/iceberg/v1

# Get an OAuth access token
json=$(curl -X POST https://login.dremio.cloud/oauth/token \
    --data-urlencode "scope=dremio.all" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:dremio:personal-access-token" \
    --data-urlencode "subject_token=$USER_PAT")

token=$(echo "$json" | jq -r '.access_token')

# Get the Open Catalog from Iceberg Catalog REST
curl -X GET $BASE_URL/config?warehouse=$CATALOG_NAME \
-H "Authorization: Bearer $token" -H 'Content-Type: application/json' 

# Get the namespaces
curl -X GET $BASE_URL/$CATALOG_NAME/namespaces \
-H "Authorization: Bearer $token" -H 'Content-Type: application/json' 

# Get a list of tables from a namespace called folder1
curl -X GET $BASE_URL/$CATALOG_NAME/namespaces/folder1/tables \
-H "Authorization: Bearer $token" -H 'Content-Type: application/json' 

# Get table1 from folder1
curl -X GET $BASE_URL/$CATALOG_NAME/namespaces/folder1/tables/table1 \
-H "Authorization: Bearer $token" -H 'Content-Type: application/json' 

# Get table1 credentials
curl -X GET $BASE_URL/$CATALOG_NAME/namespaces/folder1/tables/table1/credentials \
-H "Authorization: Bearer $token" -H 'Content-Type: application/json' 

Base URLs​

Prerequisites​

Example​

UUIDs​

Idempotent Requests​

Timestamps​

Query Parameters​

pageToken​

Built-in Maximum​

User-Specified Maximum​

maxResults​

filter​

limit​

offset​

include​

exclude​

orderBy​

createdBy​

ownedBy​

search​

maxChildren​

Response Headers​

Iceberg REST Catalog API​

Base URLs

Prerequisites

Example

UUIDs

Idempotent Requests

Timestamps

Query Parameters

`pageToken`

Built-in Maximum

User-Specified Maximum

`maxResults`

`filter`

`limit`

`offset`

`include`

`exclude`

`orderBy`

`createdBy`

`ownedBy`

`search`

`maxChildren`

Response Headers

Iceberg REST Catalog API