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:
-
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
andSECRET_KEY
with the client ID and secret key. For example:echo -n uTwiAPLiCZnTjIid:2BCgfvDbJP6o61H5REt9P2FMkEw39chd | base64
Running this command returns the
CLIENT_ID
andSECRET_KEY
encoded in base64. -
The following
cURL
example shows an-X POST
request. If you omit thetoken_format
parameter, the default format isoauth2
.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 theAuthorization: Basic
header.b. Replace
ACCOUNT_DOMAIN
with youryouraccount.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.
Is the information on this page helpful?
Yes
No
Is the information on this page helpful?
Yes
No