Admin API surface#
This is the operator index. Authoritative contract lives in the admin API
OpenAPI document — rendered interactively at the
Admin API viewer; raw bytes at
/openapi.yaml.
All paths are relative to the /admin/v1 prefix on the gateway port. Auth: SigV4
or the strata_session cookie issued by POST /auth/login. The Full schema
column links to the interactive viewer with a Redoc operation anchor
(#operation/<operationId>) — the anchor is auto-generated from the
operationId field on each path’s method entry.
The Audit verb column reflects the audit override stamped by each handler.
GET/HEAD/OPTIONS requests skip the
audit middleware — those rows show —.
Write operations (POST/PUT/DELETE) always emit one audit row.
Session#
| Method | Path | Audit verb | Summary | Full schema |
|---|
POST | /auth/login | — | Issue a 24h session cookie from IAM credentials. | authLogin |
POST | /auth/logout | — | Clear the session cookie. | authLogout |
GET | /auth/whoami | — | Probe current session; 401 when expired. | authWhoami |
Cluster status#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /cluster/status | — | Cluster-wide status hero (version, uptime, node counts, meta + data backend). | getClusterStatus |
GET | /cluster/nodes | — | Heartbeat table — one row per replica with workers + leader-for chips. | getClusterNodes |
Cluster lifecycle#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /clusters | — | List data-backend clusters with persisted drain / weight state (rows missing → live). | listClusters |
POST | /clusters/{id}/drain | admin:DrainCluster | Flip cluster_state to draining_readonly or evacuating. Body {mode} required. | drainCluster |
POST | /clusters/{id}/undrain | admin:UndrainCluster | Clear draining state — drops the row. Works from draining_readonly or evacuating. | undrainCluster |
POST | /clusters/{id}/activate | admin:ActivateCluster | Promote a pending cluster to live with the supplied default-routing weight. | activateCluster |
PUT | /clusters/{id}/weight | admin:UpdateClusterWeight | Adjust default-routing weight [0, 100] on a live cluster. Cache invalidates synchronously. | updateClusterWeight |
GET | /clusters/{id}/bucket-references | — | Buckets whose Placement[<id>] > 0, joined with bucket-usage stats (paginated). | getClusterBucketReferences |
Drain & rebalance#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /clusters/{id}/rebalance-progress | — | Per-destination cluster rebalance counters + 1h sparkline. Degrades when Prom is unset. | getClusterRebalanceProgress |
GET | /clusters/{id}/drain-progress | — | In-process drain-progress cache (chunks remaining, ETA, deregister_ready). 503 when no rebalance worker on this replica. | getClusterDrainProgress |
GET | /clusters/{id}/drain-impact | — | Synchronous bucket scan — migratable / stuck_single_policy / stuck_no_policy categorisation. 5-min cache. | getClusterDrainImpact |
GET | /gc-config | — | Resolved STRATA_GC_* tunables snapshot (grace, interval, batch_size, concurrency, shards). | getGCConfig |
GET | /rebalance-config | — | Resolved STRATA_REBALANCE_* tunables + live replica count. | getRebalanceConfig |
GET | /rebalance-bandwidth | — | Cluster-wide 1m rebalance bandwidth + chunks/sec roll-up. | getRebalanceBandwidth |
Placement#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /buckets/{bucket}/placement | — | Get per-bucket placement policy + mode (weighted / strict). | getBucketPlacement |
PUT | /buckets/{bucket}/placement | admin:PutBucketPlacement (or admin:UpdateBucketPlacementMode when body carries mode) | Replace placement policy. Weights [0, 100], sum > 0. Optional mode flips weighted ↔ strict. | putBucketPlacement |
DELETE | /buckets/{bucket}/placement | admin:DeleteBucketPlacement | Idempotent — 204 even when no policy was configured. | deleteBucketPlacement |
Buckets#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /buckets | — | List buckets (search, sort, paginate). total is unpaginated row count. | listBuckets |
GET | /buckets/top | — | Top buckets by size or 24h request count. | getBucketsTop |
GET | /buckets/{bucket} | — | Bucket detail — metadata + size + object count (bounded ListObjects walk). | getBucket |
GET | /buckets/{bucket}/distribution | — | Per-shard byte / object distribution + skew banner trigger. | getBucketDistribution |
GET | /buckets/{bucket}/replication-lag | — | Per-bucket replication_queue_age_seconds time-series (recharts shape). | getBucketReplicationLag |
GET | /buckets/{bucket}/objects | — | Read-only object browser. marker-paginated, delimiter default /. | listObjects |
GET | /buckets/{bucket}/usage | — | Per-bucket daily usage history from usage_aggregates (default 30-day window). | getBucketUsage |
GET | /buckets/{bucket}/quota | — | Get bucket quota. | getBucketQuota |
PUT | /buckets/{bucket}/quota | admin:PutBucketQuota | Replace bucket quota. Zero on any field means unlimited. | putBucketQuota |
DELETE | /buckets/{bucket}/quota | admin:DeleteBucketQuota | Idempotent quota removal. | deleteBucketQuota |
IAM#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /iam/users/{userName}/quota | — | Get user quota. | getUserQuota |
PUT | /iam/users/{userName}/quota | admin:PutUserQuota | Replace user quota. | putUserQuota |
DELETE | /iam/users/{userName}/quota | admin:DeleteUserQuota | Idempotent quota removal. | deleteUserQuota |
GET | /iam/users/{userName}/usage | — | Per-user daily usage rolled across owned buckets + cross-row totals. | getUserUsage |
Consumers & metrics#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /consumers/top | — | Top consumers by 24h requests or bytes. | getConsumersTop |
GET | /metrics/timeseries | — | Cluster-wide Prometheus-backed time-series (request rate, latency p50/p95/p99, error rate, bytes in/out). | getMetricsTimeseries |
Diagnostics#
| Method | Path | Audit verb | Summary | Full schema |
|---|
GET | /diagnostics/traces | — | List recently-captured traces from the in-process OTel ring buffer (LRU; filter by method / status / path / duration). 503 when ring buffer is disabled. | getDiagnosticsTraces |
Scope note#
The admin API router registers additional /admin/v1/* routes that are not
yet documented in the OpenAPI contract — bucket lifecycle / CORS / policy /
inventory / logging / ACL / object actions / multipart admin / IAM users +
access keys + managed policies / audit log / diagnostics extras (hot buckets,
hot shards, slow queries, node detail, trace by request id) / storage probes
/ settings. Stamping those endpoints into the YAML is tracked as a separate
doc follow-up and not in scope for this reference page.