Automate clusters, catalogs, schedules, and policies

All management endpoints share a standard JSON response envelope and the error codes below.

Quickstart - list and scale a cluster

HOST="https://<HOST>"
TOKEN="e6sa_…"           # service account key

# List your clusters
curl -s -H "Authorization: Bearer $TOKEN" "$HOST/api/v1/queryservices" | jq

# Scale one up
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"minExecutors": 5, "maxExecutors": 20}' \
  "$HOST/api/v1/queryservices/<CLUSTER>/scale" | jq

Clusters

Method	Path	Purpose
`GET`	`/api/v1/queryservices`	List clusters
`GET`	`/api/v1/queryservices/{name}`	Get one cluster (including status)
`POST`	`/api/v1/queryservices`	Create a cluster
`PUT`	`/api/v1/queryservices/{name}`	Update a cluster
`DELETE`	`/api/v1/queryservices/{name}`	Delete a cluster
`POST`	`/api/v1/queryservices/{name}/suspend`	Suspend (scale to zero)
`POST`	`/api/v1/queryservices/{name}/resume`	Resume
`POST`	`/api/v1/queryservices/{name}/scale`	Set executor count or bounds

A create or update rolls out as a background update - it’s transparent to clients, and you can watch it settle by polling GET /api/v1/queryservices/{name}. A suspended cluster auto-resumes on the next query.

Catalogs

Method	Path	Purpose
`GET` / `POST`	`/api/v1/catalogs`	List / create catalogs
`GET` / `PUT` / `DELETE`	`/api/v1/catalogs/{name}`	Get / update / delete a catalog
`POST`	`/api/v1/catalogs/{name}/refresh`	Trigger a metadata refresh
`GET`	`/api/v1/catalogs/{name}/refresh[/{refreshName}]`	List / inspect refresh runs
`GET`	`/api/v1/catalogs/{name}/schemas`	List schemas of a created catalog
`POST`	`/api/v1/catalogs/schemas`	Discover schemas before creating a catalog
`GET`	`/api/v1/catalogs/{name}/diagnostics`	Catalog diagnostics

Scheduled refresh (cron-based) is managed via GET|POST|PUT|DELETE /api/v1/catalogrefreshschedules[/{name}].

Schema and data browsing

GET /api/v1/storage/{catalog}/schemas, …/{schema}/tables, …/{schema}/columns, and …/{schema}/{table}/columns - all governance-filtered to the caller’s permissions.

Access policies

Workspace-local RBAC is managed through /api/v1/governances, /api/v1/policies/{catalog}, /api/v1/roles, /api/v1/rolebindings (+/batch), /api/v1/groups, and /api/v1/service-accounts (+/keys). Use POST /api/v1/check-permission to verify an effective grant.

Query history and system catalog

GET /api/v1/query-history[/{query_id}[/plan]] (needs history:read), plus the system-catalog status and execute endpoints (read vs execute permission).

Error handling

Branch on the standardized error code, not just the HTTP status:

HTTP	Codes
4xx	`BAD_REQUEST`, `VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`, `RESOURCE_EXISTS`, `PREREQUISITE_NOT_MET`, `CONFLICT`, `DELETION_BLOCKED`, `UNAUTHORIZED`, `FORBIDDEN`
5xx	`INTERNAL_ERROR`, `KUBERNETES_ERROR`, `TIMEOUT`, `SERVICE_UNAVAILABLE`, `UPSTREAM_ERROR`

A 403 on a token-authenticated call names the permission the request needs. Management operations are asynchronous. Don’t assume the first response is final - poll the resource’s status until it reaches a terminal or ready state.

Recipe: scale before a batch job, then suspend

Scale up: POST /api/v1/queryservices/<CLUSTER>/scale with your target executor bounds.
Wait: poll GET /api/v1/queryservices/<CLUSTER> until status is running.
Suspend: POST /api/v1/queryservices/<CLUSTER>/suspend. Re-issuing scale or suspend is safe (state-based and idempotent). Set client timeouts longer than the auto-resume window for the first query after a suspend.

Recipe: scheduled catalog refresh

API-managed schedule: POST /api/v1/catalogrefreshschedules with a cron expression and an optional database filter (needs catalog:refresh).
Driven by your own scheduler: POST /api/v1/catalogs/<CATALOG>/refresh, then poll GET /api/v1/catalogs/<CATALOG>/refresh/<refreshName> until Succeeded, PartialSuccess, or Failed. Treat PartialSuccess as a real outcome (some sources unreachable) and alert on Failed.

Platform

Get started

Deploy a workspace

Manage workspaces

Identity and access

Tokens and support access

Operate

Automate

Security and trust

Reference

Automate clusters, catalogs, schedules, and policies

Quickstart - list and scale a cluster

Clusters

Catalogs

Schema and data browsing

Access policies

Query history and system catalog

Error handling

Recipe: scale before a batch job, then suspend

Recipe: scheduled catalog refresh

​Quickstart - list and scale a cluster

​Clusters

​Catalogs

​Schema and data browsing

​Access policies

​Query history and system catalog

​Error handling

​Recipe: scale before a batch job, then suspend

​Recipe: scheduled catalog refresh

Quickstart - list and scale a cluster

Clusters

Catalogs

Schema and data browsing

Access policies

Query history and system catalog

Error handling

Recipe: scale before a batch job, then suspend

Recipe: scheduled catalog refresh