DETalk to us →
ClusterPilot Docs
v0.0.1 RC · fcc5871
Start with:EvaluateInstallCreate a clusterOperateRecoverAutomate
Documentation/Reference
Reference · v0.0.1

API endpoint catalog

Search the customer-facing v0.0.1 route families, permissions, purposes and mutation posture.

AudienceIntegrators · automation engineers · security reviewersReading timeReferenceCommands in contextNo terminal requiredReviewed sourcefcc5871 · 30 July 2026
RC

Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.

Integration contract

Use the published OpenAPI document from the exact deployed release as the machine-readable authority. This catalog provides the operator-oriented map.

  • ✓
    Authenticate human workflows with sessions and machine workflows with scoped API keys
  • ✓
    Send Idempotency-Key for mutation admission; reuse only for exact replay
  • ✓
    Send If-Match where the resource exposes ETag concurrency
  • ✓
    Send X-Confirm-Destructive only after reviewing the plan and impact
  • ✓
    Treat RFC7807 HTTP status, error_code, nextAction and correlation fields as one diagnostic envelope

Endpoint explorer

84 of 84 documented endpoints

GET/api/v1/auth/bootstrap-state

Read first-run bootstrap state.

Authenticationpublicread
POST/api/v1/auth/bootstrap-admin

Create the first platform administrator.

Authenticationbootstrap gatemutation
POST/api/v1/auth/login

Create a human session.

Authenticationpublicmutation
POST/api/v1/auth/logout

End the current session.

Authenticationauthenticatedmutation
POST/api/v1/auth/refresh

Refresh an eligible session.

Authenticationauthenticatedmutation
GET/api/v1/auth/me

Read current actor, workspace and permissions.

Authenticationauthenticatedread
GET/api/v1/auth/permissions

Discover the stable permission matrix.

Authenticationauthenticatedread
GET/api/v1/auth/users

List users.

Identitysettings.readread
POST/api/v1/auth/users

Create a user.

Identitysettings.writemutation
GET/api/v1/auth/teams

List teams.

Identitysettings.readread
POST/api/v1/auth/teams

Create a team.

Identitysettings.writemutation
GET/api/v1/auth/sessions

List active sessions.

Identitysettings.readread
POST/api/v1/auth/sessions/{sessionId}/revoke

Revoke a session.

Identitysettings.writemutation
GET/api/v1/api-keys

List secret-safe API-key metadata.

Machine authapi_keys.readread
POST/api/v1/api-keys

Create a scoped API key.

Machine authapi_keys.writemutation
POST/api/v1/api-keys/{keyId}/rotate

Rotate a machine credential.

Machine authapi_keys.writemutation
POST/api/v1/api-keys/{keyId}/revoke

Revoke a machine credential.

Machine authapi_keys.writemutation
GET/api/v1/cloud-providers/capabilities

Read provider maturity and operation support.

Providerscloud_providers:readread
GET/api/v1/cloud-providers

List scoped provider accounts.

Providerscloud_providers:readread
POST/api/v1/cloud-providers

Create a provider account with write-only credentials.

Providerscloud_providers:createmutation
GET/api/v1/cloud-providers/{id}

Read secret-safe provider detail.

Providerscloud_providers:readread
PUT/api/v1/cloud-providers/{id}

Rename using If-Match concurrency.

Providerscloud_providers:updatemutation
DELETE/api/v1/cloud-providers/{id}

Soft-delete an unreferenced account.

Providerscloud_providers:deletemutation
POST/api/v1/cloud-providers/{id}/validate

Validate credentials through the provider adapter.

Providerscloud_providers:updatemutation
POST/api/v1/cloud-providers/{id}/credentials/rotate

Stage and atomically validate credential rotation.

Providerscloud_providers:updatemutation
POST/api/v1/cloud-providers/{id}/reset

Reset the circuit breaker and revalidate.

Providerscloud_providers:updatemutation
POST/api/v1/cluster-infrastructure/plans

Return a deterministic infrastructure plan without persistence.

Infrastructurecloud_providers:readmutation
POST/api/v1/cluster-infrastructure

Persist planned infrastructure.

Infrastructurecluster_operations.createmutation
GET/api/v1/cluster-infrastructure

List infrastructure records.

Infrastructureclusters.readread
GET/api/v1/cluster-infrastructure/{id}

Read topology, nodes, provider linkage and trust.

Infrastructureclusters.readread
POST/api/v1/cluster-infrastructure/{id}/provider-state/refresh

Refresh provider-backed evidence.

Infrastructurecloud_providers:updatemutation
POST/api/v1/cluster-infrastructure/{id}/provision

Queue deterministic VM provisioning.

Infrastructurecluster_operations.createmutation
DELETE/api/v1/cluster-infrastructure/{id}

Remove inventory after destructive confirmation; does not terminate VMs automatically.

Infrastructurecluster_operations.createmutation
GET/api/v1/clusters

List lifecycle cluster inventory.

Clusterscluster_lifecycle.readread
POST/api/v1/clusters

Admit create-cluster intent and return an OperationRun.

Clusterscluster_lifecycle.createmutation
GET/api/v1/clusters/{clusterId}

Read lifecycle detail.

Clusterscluster_lifecycle.readread
GET/api/v1/clusters/{clusterId}/nodes

Read lifecycle node inventory.

Clusterscluster_lifecycle.readread
GET/api/v1/clusters/{clusterId}/infrastructure

Read provider and infrastructure linkage.

Clusterscluster_lifecycle.readread
GET/api/v1/clusters/{clusterId}/preparation

Read node-preparation projection.

Clusterscluster_lifecycle.readread
POST/api/v1/clusters/{clusterId}/scale

Scale; scale-in requires destructive confirmation.

Clusterscluster_lifecycle.scalemutation
POST/api/v1/clusters/{clusterId}/upgrade

Upgrade one supported Kubernetes minor.

Clusterscluster_lifecycle.upgrademutation
POST/api/v1/clusters/{clusterId}/nodes/{nodeId}/replace

Replace a node with destructive confirmation.

Clusterscluster_lifecycle.replacemutation
POST/api/v1/clusters/{clusterId}/nodes/{nodeId}/prepare

Prepare one node.

Clusterscluster_lifecycle.preparemutation
POST/api/v1/clusters/{clusterId}/nodes/prepare-batch

Prepare a deterministic node batch.

Clusterscluster_lifecycle.preparemutation
DELETE/api/v1/clusters/{clusterId}

Delete through a confirmed lifecycle OperationRun.

Clusterscluster_lifecycle.deletemutation
POST/api/v1/clusters/airgap-readiness

Validate air-gap inputs and optional remediation.

Clusterscluster_lifecycle.createmutation
GET/api/v1/clusters/{clusterId}/desired-state

Read latest desired state.

State & driftclusters.readread
GET/api/v1/clusters/{clusterId}/observed-state

Read latest observed state.

State & driftclusters.readread
GET/api/v1/clusters/{clusterId}/drift

Read computed drift.

State & driftclusters.readread
POST/api/v1/clusters/{clusterId}/reconcile

Evaluate guardrails and queue reconciliation.

State & driftcluster_operations.createmutation
GET/api/v1/cluster-operations

List operation runs.

OperationRunscluster_operations:readread
GET/api/v1/cluster-operations/{id}

Read ordered run and step detail.

OperationRunscluster_operations:readread
GET/api/v1/cluster-operations/{id}/events/stream

Replay and stream ordered SSE events.

OperationRunscluster_operations:readread
POST/api/v1/cluster-operations/{id}/cancel

Request bounded cancellation.

OperationRunscluster_operations:createmutation
POST/api/v1/cluster-operations/{id}/steps/{stepId}/retry

Retry a classified retryable step.

OperationRunscluster_operations:createmutation
GET/api/v1/runs

List runs across supported run models.

Runs & evidenceruns.readread
GET/api/v1/runs/{id}

Read a run investigation payload.

Runs & evidenceruns.readread
GET/api/v1/runs/{id}/artifacts

List evidence artifacts.

Runs & evidenceruns.readread
GET/api/v1/runs/{id}/artifacts/{artifactId}/download

Download integrity-checked evidence.

Runs & evidenceruns.readread
POST/api/v1/runs/{id}/artifacts/export-jobs

Build a bounded export job.

Runs & evidenceruns.readmutation
PUT/api/v1/runs/{id}/artifacts/{artifactId}/hold

Place a retention hold.

Runs & evidenceruns.writemutation
GET/api/v1/clusters/{clusterId}/addons/catalog

List immutable built-in definitions.

Add-onscluster_lifecycle.readread
POST/api/v1/clusters/{clusterId}/addon-plans

Create a deterministic add-on plan.

Add-onscluster_lifecycle.createmutation
POST/api/v1/clusters/{clusterId}/addon-plans/{id}/preflight

Persist registry, image, artifact and readiness evidence.

Add-onscluster_lifecycle.createmutation
POST/api/v1/clusters/{clusterId}/addon-plans/{id}/install

Admit install or targeted reapply.

Add-onscluster_lifecycle.createmutation
GET/api/v1/clusters/{clusterId}/addons

List projected installations.

Add-onscluster_lifecycle.readread
POST/api/v1/clusters/{clusterId}/addons/{addonKey}/upgrade

v0.0.1 contract stub; no OperationRun.

Add-onscluster_lifecycle.createcontract
POST/api/v1/clusters/{clusterId}/addons/{addonKey}/uninstall

v0.0.1 contract stub; no OperationRun.

Add-onscluster_lifecycle.createcontract
POST/api/v1/clusters/{clusterId}/custom-addons/upload-bundle

Upload a bounded immutable bundle.

Custom add-onscluster_lifecycle.createmutation
POST/api/v1/clusters/{clusterId}/custom-addons/{id}/promote-to-harbor

Promote validated artifacts to Harbor.

Custom add-onscluster_lifecycle.createmutation
POST/api/v1/clusters/{clusterId}/conformance/admission-preview

Preview readiness, impact and policy blocks.

Conformanceconformance.readmutation
POST/api/v1/clusters/{clusterId}/conformance/runs

Admit pinned Sonobuoy validation.

Conformanceconformance.runmutation
GET/api/v1/clusters/{clusterId}/conformance/runs

List immutable conformance history.

Conformanceconformance.readread
GET/api/v1/clusters/{clusterId}/conformance/result

Read latest sanitized result.

Conformanceconformance.readread
GET/api/v1/clusters/{clusterId}/conformance/runs/{runId}/artifacts

List conformance artifact metadata.

Conformanceconformance.readread
POST/api/v1/clusters/{clusterId}/conformance/runs/{runId}/cancel

Cancel with mandatory cleanup.

Conformanceconformance.cancelmutation
GET/api/v1/guardrails

List scoped guardrail rules.

Guardrailsguardrails.readread
PUT/api/v1/guardrails/{id}

Update a rule with If-Match.

Guardrailsguardrails.updatemutation
POST/api/v1/guardrails/evaluate

Dry-run policy evaluation.

Guardrailsguardrails.readmutation
POST/api/v1/admin/backup/verify

Verify database, artifacts and protected-secret readability.

Operationsplatform_adminmutation
GET/health

Liveness health.

Operationspublic/internal policyread
GET/ready

Dependency-aware readiness.

Operationspublic/internal policyread
GET/health/clock

Clock posture.

Operationspublic/internal policyread
GET/metrics

Prometheus-format metrics.

Operationsobservability policyread

Mutation pattern

Request contract
POST /api/v1/clusters/{clusterId}/scale
Authorization: Bearer <scoped-api-key>
Content-Type: application/json
Idempotency-Key: <stable-exact-replay-key>
X-Confirm-Destructive: true   # scale-in only

{
  "idempotencyKey": "<same-key>",
  "workerCount": 5
}

Release boundary