API Reference

The Dremio REST API is organized by resource types such as sources and is designed around RESTful principles. HTTP GET is used to retrieve existing resources, POST creates new ones, PUT updates them and DELETE removes them.

Base URL

All API URLs referenced in this documentation have the following base URL unless otherwise specified:

Base URL

{hostname}/api/v3

Versions prior to v3 are considered internal and are subject to change without notice.

In this documentation, curly braces ({}) are used to indicate sections of URLs where you have to supply a value. For example:

User-supplied values in URLs

/api/v3/source/{id}

Authentication

The Dremio REST API requires authentication with either a personal access token created in the Dremio UI or an authentication token generated with your username and password. Follow the instructions in this section to learn how to authenticate to the Dremio REST API with a personal access token or an authentication token.

Personal Access Token Enterprise

Personal access tokens (PATs) are created in the Dremio UI. Follow the instructions in Creating a PAT to get a PAT to use in API requests.

API requests that use a PAT token must use the Authorization header. The header's value must specify the Bearer type followed by a space and the PAT: Bearer {PAT}. This example request to retrieve a catalog demonstrates how to use a PAT in an API request:

Example Request Using PAT

curl -X GET 'https://{hostname}/api/v3/catalog' \
--header 'Authorization: Bearer dJhGBUDAVv+9Wlsp/I/o/87Vq+omuvpC/YEy6U25S79i74KhD2W6q2sr44emKy==' \
--header 'Content-Type: application/json'

Authentication Token

Authentication tokens are generated from your Dremio username and password. They expire every 30 hours. When an authentication token expires, you must generate a new one. API requests that use an authentication token must use the Authorization header.

caution

API versions prior to v3 are considered internal and are subject to change without notice.

To generate an authentication token:

1. Send an API request to the login URL, with your Dremio username and password in the request body.

Example Request

curl -X POST 'http://{hostname}/apiv2/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"userName": "dremio",
"password": "dremio123"
}'

The request returns a JSON user structure:

Example Response

{
  "token": "4ksrt534vk7fkq64xh55g7776b",
  "userName": "dremio",
  "firstName": "Dre",
  "lastName": "Mio",
  "expires": 1686578200000,
  "email": "dremio@dremio.test",
  "userId": "5a679dd5-52d7-402a-871d-7fbee3fe8007",
  "admin": true,
  "clusterId": "7468ce46-58af-4dce-a42f-4c51048968f5",
  "clusterCreatedAt": 1681311939728,
  "version": "24.0.0-main-202305040803350903-2d5579e3",
  "permissions": {
    "canUploadProfiles": true,
    "canDownloadProfiles": true,
    "canEmailForSupport": true,
    "canChatForSupport": false,
    "canViewAllJobs": true,
    "canCreateUser": true,
    "canCreateRole": true,
    "canCreateSource": true,
    "canUploadFile": true,
    "canManageNodeActivity": true,
    "canManageEngines": true,
    "canManageQueues": true,
    "canManageEngineRouting": true,
    "canManageSupportSettings": true
  },
  "userCreatedAt": 1681311939789
}

note

If your password includes single or double quotes, you may need to escape the quotes in your authentication token request. The required escapes vary depending on how you send the request.

For example, if you use cURL and the password is example'6852", the password value should be example'\''6852\" in the authentication token request.

2. Copy the value of the token attribute in the JSON user structure. This value is called the token string.

3. Append the token string to _dremio to compose the required Authorization header for API requests: _dremio{tokenstring}.

   This example request to retrieve a catalog demonstrates how to use the token string retrieved in step 1:

   Example Request Using Authentication Token

   curl -X GET 'https://{hostname}/api/v3/catalog' \
   --header 'Authorization: _dremio4ksrt534vk7fkq64xh55g7776b' \
   --header 'Content-Type: application/json'

Errors

Error messages will be sent back in the response body using the following format:

Error message format

{
  "errorMessage": "brief error message",
  "moreInfo": "detailed error message"
}

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 for that endpoint.

pageToken Query Parameter

For endpoints that support the pageToken query parameter, responses will include a page token if the Dremio instance has more results than the maximum per page. Use the value for this token in your request URL as the pageToken value to retrieve the next page of results.

As an 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 Request with pageToken Query Parameter

curl -X GET 'https://{hostname}/api/v3/reflection-summary?pageToken=BhQxNjc0MjhlYi03OTM2LTRlYTItYTFmYi0yM2IxYWM2ZTk0NTQSAA==' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header '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.

note

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

maxResults Query Parameter

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 Request with maxResults Query Parameter

curl -X GET 'https://{hostname}/api/v3/reflection-summary?maxResults=25' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

filter Query Parameter

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 that specifies the desired attributes and values.

As an 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 JSON Object for Filter

{
  "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 Request with filter Query Parameter

curl -X GET 'https://{hostname}/api/v3/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' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

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

orderBy Query Parameter

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 Request with orderBy Query Parameter (Ascending Order)

curl -X GET 'https://{hostname}/api/v3/reflection-summary?orderBy=reflectionName' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

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

Example Request with orderBy Query Parameter (Descending Order)

curl -X GET 'https://{hostname}/api/v3/reflection-summary?orderBy=-reflectionName' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

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

limit and offset Query Parameters

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 Request for First 10 Results with Limit Query Parameter

curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=10' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

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 5000 results. The Job API allows you to retrieve a maximum of 500 results per request. To retrieve all 5000 results, start by adding ?limit=500 to the request URL to retrieve the first 500:

Example Request for First 500 Results with Limit Query Parameter

curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=500' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

In the next request, to retrieve the next 500 results (rows 501-1000), add &offset=500 to the request URL:

Example Request for Results 501-1000 with limit and offset Query Parameters

curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=500&offset=500' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

To retrieve the next 500 results (rows 1001-1500), increment the offset parameter to 1000 in the next request:

Example Request for Results 1001-1500 with limit and offset Query Parameters

curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=500&offset=1000' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Continue incrementing the offset parameter in requests until you have retrieved all 5000 results.

Read the documentation for each API to learn about endpoint-specific support for the limit and offset query parameters.

type Query Parameter

Use the type query parameter to limit your request so that the response includes only results for the type you specify.

For example, if an endpoint supports the type query parameter, and the endpoint's list of valid values includes SOURCE, you can limit the response so that it includes only results for sources. Append ?type=SOURCE to the request URL:

Example Request with type Query Parameter

curl -X GET 'https://{hostname}/api/v3/catalog/privileges?type=SOURCE' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Read the documentation for each API to learn about endpoint-specific support for the type query parameter, including lists of valid values.

include and exclude Query Parameters

Some APIs exclude non-default attributes or include lengthy attributes in the default GET responses. These APIs support the include and exclude query parameters, which you can use to include or exclude certain attributes in the responses for GET endpoints.

The include query parameter allows you to include non-default attributes in the response. For example, in the Catalog API, you can include a catalog object's permissions array in the response:

Example Request with include Query Parameter

curl -X GET 'https://{hostname}/api/v3/catalog/ffbe8c1d-1db7-48d1-9c58-f452838fedc0?include=permissions' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

The exclude query parameter allows you to exclude supported attributes from the response. For example, this Catalog API request excludes the object's children attribute from the response:

Example Request with exclude Query Parameter

curl -X GET 'https://{hostname}/api/v3/catalog/ffbe8c1d-1db7-48d1-9c58-f452838fedc0?exclude=children' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Read the documentation for each API to learn about endpoint-specific support for the include and exclude query parameters, including information about supported values.

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.
Cache-Control	no-cache, no-store	Caching instructions for browsers and shared caches.
Content-Length	2188	Size of the response body, in bytes.
Content-Type	application/json	MIME type of the object.
Date	Fri, 14 Apr 2023 19:39:53 GMT	Date and time when the response originated.
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-xss-protection	1; mode=block	Instructions used to stop pages from loading when a browser detects reflected cross-site scripting attacks.