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 control > 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 token. Then follow these steps:

1. 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.

2. The following cURL example shows an -X POST request. If you omit the token_format parameter, the default format is oauth2.

    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?token_format=oauth2
   

   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.

Legacy token response format #

When you create an access token using the token_format=legacy parameter, responses are in the legacy format.

For example:

  $ 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?token_format=legacy
  {"oauthTokenData":{"tokenType":"Bearer","expiresIn":600,"scope":"","accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJqdGkiO..."}}

The legacy format does not conform to the token response format specified in RFC 6749. Do not use legacy format access tokens in new applications.

Endpoints #

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. Each cluster exposes the Trino API for query processing.

Instead of using the Trino API for executing queries, 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.