On this page

    API Reference

    note:

    Configuring S3 and Glue Catalog sources via REST is not currently supported.

    For information on the relationship of the Dremio Cloud entities, see the object model topic.

    API Endpoint

    To use Dremio Cloud APIs, use the endpoint for your control plane.

    US Control Plane
    https://api.dremio.cloud/v0/
    
    EU Control Plane
    https://api.eu.dremio.cloud/v0/
    

    Authentication

    The Dremio API requires authentication with a personal access token (PAT). 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 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://api.dremio.cloud/v0/projects/48ca6975-39ad-47cb-9bb5-de73060380f6/catalog' \
    --header 'Authorization: Bearer dJhGBUDAVv+9Wlsp/I/o/87Vq+omuvpC/YEy6U25S79i74KhD2W6q2sr44emKy==' \
    --header 'Content-Type: application/json'
    

    Idempotent Requests

    Idempotence is an operation or a service call that produces the same result when it is called multiple times.

    API endpoints support idempotency to safely retry user requests without performing a duplicate operation. This is helpful when an API request is interrupted in transit and a response is not received. In such cases, you can retry that request with the same idempotency key to ensure that there is no duplicate request.

    To create an idempotent request, add a requestId parameter to the request. The value is a unique generated UUID. The server uses the idempotency key to identify consequent retries of the same API request.

    Only POST operations accept the idempotency key.

    warning:

    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 creates no impact as they are idempotent.

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

    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.

    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://api.dremio.cloud/v0/api/projects/{project-id}/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://api.dremio.cloud/v0/api/projects/{project-id}/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://api.dremio.cloud/v0/api/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' \
    --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.

    view Query Parameter

    Use the view query parameter to specify the level of detail to include in the response.

    For example, the Arctic Catalog endpoint for retrieving all jobs supports retrieving SUMMARY or FULL level of detail in the response. To retrieve jobs with FULL detail:

    Example Request With orderBy Query Parameter (Ascending Order)
    curl -X GET 'https://api.dremio.cloud/v0/api/arctic/catalogs/{catalogId}/jobs?view=FULL' \
    --header 'Authorization: Bearer <PersonalAccessToken>' \
    --header 'Content-Type: application/json'
    

    Read the endpoint-specific documentation to learn which attributes each endpoint supports for the view 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://api.dremio.cloud/v0/projects/{project-id}/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://api.dremio.cloud/v0/projects/{project-id}/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 Rows 501-1000 with Limit and Offset Query Parameters
    curl -X GET 'https://api.dremio.cloud/v0/projects/{project-id}/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 Rows 1001-1500 with Limit and Offset Query Parameters
    curl -X GET 'https://api.dremio.cloud/v0/projects/{project-id}/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.

    Include and Exclude Query Parameters

    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 Request Using include=permissions
    curl -X GET 'https://api.dremio.cloud/v0/projects/{project-id}/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 the children field from the response.

    Example Request Using exclude=children
    curl -X GET 'https://api.dremio.cloud/v0/projects/{project-id}/catalog/ffbe8c1d-1db7-48d1-9c58-f452838fedc0?exclude=children' \
    --header 'Authorization: Bearer <PersonalAccessToken>' \
    --header 'Content-Type: application/json'
    

    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://api.dremio.cloud/v0/api/projects/{project-id}/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://api.dremio.cloud/v0/api/projects/{project-id}/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.

    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.