Automate clusters, catalogs, schedules, and policies

Manage clusters, catalogs, scheduled refreshes, and access policies over the e6data Management API, with recipes for scaling, suspending, and refreshing.

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

1. Scale up: POST /api/v1/queryservices/<CLUSTER>/scale with your target executor bounds.
2. Wait: poll GET /api/v1/queryservices/<CLUSTER> until status is running.
3. 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.