starburst galaxy > developer tools > api > Starburst Galaxy API

Starburst Galaxy API #

The Starburst Galaxy API allows you to automate processes that are otherwise performed with the user interface. This allows you to manage processes without user interaction, including outside business hours, and to integrate Starburst Galaxy in automated workflows in your overall data pipeline and other business processes.

The API is implemented as a REST API over TLS/HTTPS including the use of authentication tokens. Each token is associated with a role and its privileges that are fully integrated with Starburst Galaxy’s access control system.

API documentation #

View technical documentation for the Starburst Galaxy API at: https://ACCOUNT_DOMAIN.galaxy.starburst.io/public-api

This account-specific URL includes all API endpoints available to your Galaxy account, including any preview endpoints. If you don’t yet have an account, set up a free Starburst Galaxy account.

View general API documentation at: https://galaxy.starburst.io/public-api.

Each endpoint’s documentation includes the URL of the endpoint and details about its parameters, JSON results, and HTTP result codes for success or failure. See Endpoints for examples of API usage.

Authentication #

Use of the API requires an authentication token. Create and manage these tokens in the Starburst Galaxy UI at Access > API auth token. This menu option is only visible when a role in your active role set has the account-level MANAGE_SECURITY privilege.

Authorization #

Each API authentication token is assigned a role. Any operation with the API and a token is restricted and controlled by the access available to the role. Any API authentication that is assigned the accountadmin role can use all API endpoints.

For example, if a role assigned to an API token does not have the privileges to enable or disable a cluster, an API call with that token to perform these actions fails.

Access the API #

To access the API, you must first generate a new API authentication token. Then follow these steps:

Generate a base64 encoded string using the client ID and secret key values from the token you created.
```
 echo -n CLIENT_ID:SECRET_KEY | base64
```
Replace CLIENT_ID and SECRET_KEY with the client ID and secret key. For example:
```
 echo -n uTwiAPLiCZnTjIid:2BCgfvDbJP6o61H5REt9P2FMkEw39chd | base64
```
Running this command returns the CLIENT_ID and SECRET_KEY encoded in base64.
The following cURL example shows an -X POST request.
```
 curl -X POST \
   -H 'Authorization: Basic PSAIWHLSKDO06Pj34ZEltUW23RFdDS3nKEPUozOX432Szc0NkI1VFlYNXAwDw==' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -d 'grant_type=client_credentials' \
   https://ACCOUNT_DOMAIN/oauth/v2/token
```
a. Copy the generated base64 CLIENT_ID:SECRET_KEY string, such as PSAIWHLSKDO06Pj34ZEltUW23RFdDS3nKEPUozOX432Szc0NkI1VFlYNXAwDw==, to the Authorization: Basic header.

b. Replace ACCOUNT_DOMAIN with your youraccount.galaxy.starburst.io account domain.

The token response is a JSON object similar to the following:

  {"token_type":"Bearer","access_token":"eyJhbGciOiJIUzI1NiJ9.eyJqdGkiO...","expires_in":600,"scope":""}

You can use this access_token value from the response with the Authorization: Bearer ACCESS_TOKEN header and endpoints to make API calls.

Endpoints #

Starburst Galaxy provides endpoints for the following services:

Cluster service: The cluster service endpoints let you perform various tasks relating to a cluster such as creating, listing, enabling, disabling, and deleting a cluster.
User service: The user service provides endpoints that let you perform operations related to managing users. For example, you can use the user service endpoints to return a list of users or return a specific user.
Role service: The role service endpoints let you perform role-related operations. For example, you can use the endpoints to list entities assigned to a role, create a role, grant or revoke roles, delete a role, or return a list of all roles.
Privilege service: The privilege service endpoints let you perform operations related to role privileges. For example, you can grant or revoke a privilege to a role, or return a list of all privileges granted to a specified role.
Schema discovery service: The schema discovery endpoints let you perform operations related to discovering new object storage files. For example, you can return a list of schema discoveries from a particular catalog, execute SQL statements generated by a discovery, or run a new schema discovery on a specified URI.
Catalog service: The catalog service provides the listCatalog endpoint that returns all catalog identifiers and names in an account.
Discovery service: The discovery service endpoints let you perform operations that relate to Starburst Galaxy’s catalog explorer. As an example, you can return the tables of a schema along with any metadata referencing the tables.
Tag service: The tag service provides endpoints that can be used for functions involving tags. For example, you can create, update, and delete tags, or you can return a list of all tags in your account.
Row filter service: The row filter service includes endpoints that let you perform actions such as creating, updating and deleting row filters, or returning a list of row filters in your account.
Service account service: The service account endpoints let you execute functions related to service accounts. Some service account functions include creating, deleting, and updating service accounts, as well as creating and deleting service account passwords.
Column mask service: The column mask service includes endpoints that let you perform actions such as creating, updating, and deleting column masks, or returning a list of column masks in your account.
Policy service: The policy service provides endpoints to perform operations related to policies. For example, you can create, delete, and update policies, or return a list of all policies in your account.
Data product service: The data products service endpoints let you execute tasks that relate to a data product. You can list, create, delete, and edit data products in your account.

See the current API documentation for your Starburst Galaxy account for the endpoints available to your account and role.

The Starburst Galaxy API does not include endpoints for query processing. For more information, see Queries.

Example usage #

Set up to access the API. Use the access token with the listClusters endpoint and the Authorization: Bearer ACCESS_TOKEN header to view all clusters in your account:

  curl https://ACCOUNT_DOMAIN/public/api/v1/cluster
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiItekE0bUFsU1N3M0RHRE1DdmtOYVZEc1dXYms1djNaU2...

The following is the result of a successful request:

  {"nextPageToken":"","result":[{"syncToken":"2","clusterId":"w-3829737466","name":"sample"},{"syncToken":"3","clusterId":"w-9081218528","name":"demodocs"}]}

For easy viewing of the result, redirect the output to a file:

    curl https://{account-domain}/public/api/v1/cluster \
      -H 'Authorization: Bearer ACCESS_TOKEN' \
      > result.json

Open the file in an editor or a web browser to improve formatting:

    {
      "nextPageToken":""
      "result":[
        {
          "syncToken":"2",
          "clusterId":"w-3829737467",
          "name":"sample"
        }
      ]
    }
    {
        {
          "syncToken":"3",
          "clusterId":"w-9081218528",
          "name":"demodocs"
        }
      ]
    }

Queries #

The Starburst Galaxy API does not provide endpoints for query processing. Instead, use Trino SQL statements for query processing.

Use the recommended client tools and drivers:

The most convenient client is the query editor, which is a browser-based UI in Starburst Galaxy for running and managing SQL queries.
You can also use the available clients, wrapper libraries, and drivers for query processing with a variety of applications and tools, or for your custom development efforts.

March 2024 API syntax update #

In early March, 2024, a number of Starburst Galaxy endpoints changed to resolve some issues with standardization and usage. The new syntax is incompatible with the previous syntax. See the API breaking changes documentation for more details.

Is the information on this page helpful?

Yes

Cancel

Starburst Galaxy API