> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    autonumber
    participant A as Your automation
    participant E as e6data API
    A->>E: POST /queryservices/{name}/scale
    E-->>A: 2xx accepted (state: updating)
    loop poll until ready
        A->>E: GET /queryservices/{name}
        E-->>A: status
    end
    E-->>A: state: running
```

**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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.