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 subject to change without version bumps.
In this documentation, curly braces ({}) are used to indicate sections of URLs where you have to supply a value. For example:
/api/v3/source/{id}
Authentication
The Dremio REST API uses a token based authentication system.
To generate an authentication token, send a POST request to (note the different base URL, we are using an older API right now for logging in):
{hostname}/apiv2/login
with the following input body:
Input body for authentication token request{
"userName": "dremio",
"password": "dremio123"
}
note:
For passwords that include 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.
This will return a JSON user structure which contains a token property:
{
...,
"token": "tokenstring"
}
When calling REST API endpoints, the request needs to have an Authorization header set to _dremio{tokenstring}.
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:
curl -X GET 'https://{hostname}/api/v3/reflection-summary?pageToken=BhQxNjc0MjhlYi03OTM2LTRlYTItYTFmYi0yM2IxYWM2ZTk0NTQSAA==' \
--header 'Authorization: _dremio{tokenstring}' \
--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:
curl -X GET 'https://{hostname}/api/v3/reflection-summary?maxResults=25' \
--header 'Authorization: _dremio{tokenstring}' \
--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:
{
"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:
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: _dremio{tokenstring}' \
--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: _dremio{tokenstring}' \
--header 'Content-Type: application/json'
To organize the response in descending order, add a - before the attribute name:
curl -X GET 'https://{hostname}/api/v3/reflection-summary?orderBy=-reflectionName' \
--header 'Authorization: _dremio{tokenstring}' \
--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:
curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=10' \
--header 'Authorization: _dremio{tokenstring}' \
--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:
curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=500' \
--header 'Authorization: _dremio{tokenstring}' \
--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:
curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=500&offset=500' \
--header 'Authorization: _dremio{tokenstring}' \
--header 'Content-Type: application/json'
To retrieve the next 500 results (rows 1001-1500), increment the offset parameter to 1000 in the next request:
curl -X GET 'https://{hostname}/api/v3/job/{id}/results?limit=500&offset=1000' \
--header 'Authorization: _dremio{tokenstring}' \
--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.