Documentation / Reference
Reference · v0.0.1 API & automation Automate ClusterPilot with scoped machine identities, idempotent writes, stable errors, and durable OperationRuns.
Audience Integration engineers, platform developersReading time 16 minCommands in context 6 guided stepsReviewed source fcc5871 · 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.
Headless contract principles ✓ Use a service_principal and scoped API key for machine calls; do not automate with a copied browser session.
✓ Send and retain an idempotency key for write endpoints that require one.
✓ Treat HTTP status plus ProblemDetails error_code and extensions as the diagnostic contract.
✓ Use returned resource/run IDs and correlation IDs; never infer success from a closed connection.
✓ Poll or stream bounded read endpoints and handle rate limits, cursor gaps, expiry, and terminal states.
✓ Feature availability and authorization are independent; callers must handle disabled/gated capabilities.
Authentication and request envelope Illustrative request Copy
curl --request POST \
--url https://clusterpilot.example.com/api/v1/clusters/<cluster-id>/conformance/runs \
--header "Authorization: Bearer $CLUSTERPILOT_API_KEY" \
--header "Idempotency-Key: 7ea97a3e-<unique-request-id>" \
--header "Content-Type: application/json" \
--data '{"mode":"quick"}'Inject the API key from the caller’s secret manager. Do not paste a real key into shell history, CI logs, example files, or tickets. Confirm the exact request/response schema in the OpenAPI document shipped by your release.
Commands for this step Prepare a secret-safe API shell Load credentials through the approved environment boundary and confirm the target before any API workflow.
Run in order Complete each step successfully before continuing.
01
Read-only HTTP API
Prepare a secret-safe API shell Set the endpoint and inject a scoped machine key without writing it into scripts or examples.
Before you run it Scoped service-principal API key curl jq HTTP API · api-shell Copy
export CP_URL=https://clusterpilot.example.com
read -rsp 'ClusterPilot API key: ' CLUSTERPILOT_API_KEY && echo
export CLUSTERPILOT_API_KEY
curl --fail-with-body -sS \
-H "Authorization: Bearer $CLUSTERPILOT_API_KEY" \
$CP_URL/api/v1/auth/me | jq .✓ Expected result The current machine identity is returned; the key was not echoed.
Reviewed source docs/api/headless-integrations-contract-v1.mdEndpoint families Family Representative operations /api/v1/providers Provider account CRUD, validation, rotation/reset, SSH keys, provider-specific discovery. /api/v1/clusters List/detail, quotas, ingress/HA, nodes, infrastructure, create, scale, upgrade, replace, delete, inventory purge. /api/v1/clusters/{id}/addons Catalog, plans, DNS/preflight, install, installed state, Harbor promotion; upgrade/uninstall remain gated stubs. /api/v1/clusters/{id}/custom-addons List/create/update, bundle upload, validate, promote, install. /api/v1/clusters/{id}/conformance Admission preview, start/list, result, artifact download/raw, purge, cancel, retry. /api/v1/runs List/detail, cancel, retry, events/logs/commands, plan diff/export, artifacts. /api/v1/agent Heartbeat, active fleet, compatible work polling, ordered execution ingest. /api/v1/admin Build, agents, users/teams/roles, configuration, diagnostics and protected administration.
ProblemDetails and error codes Illustrative failure Copy
{
"type": "https://clusterpilot.example/errors/runs-retry-conflict",
"title": "Retry conflicts with active work",
"status": 409,
"error_code": "RUNS_RETRY_CONFLICT",
"nextAction": "wait_for_active_run",
"correlationId": "c-...",
"runId": "r-..."
}HTTP Typical interpretation 400 Schema/input invalid; correct the request. 401 / 403 Identity invalid or scope/role insufficient; do not retry unchanged. 404 Resource absent or not visible in the caller scope. 409 State, revision, idempotency, active-run, or compatibility conflict. 412 / 422 Admission, policy, compatibility, or semantic validation blocked the request. 429 Caller/platform/provider limit; honor retry guidance and reduce concurrency. 5xx Dependency or internal failure; preserve correlation ID and determine replay safety.
Idempotency and polling Reuse an idempotency key only for the identical semantic request. A payload mismatch must fail instead of creating ambiguous work. After a timeout, query by the returned resource/run ID or retry the identical request with the same key before generating a new key.
Do not treat retries as a substitute for reconciliation. A provider call may have succeeded before a network timeout; the run, provider IDs, and cleanup ownership must be inspected first.
Commands for this step Choose the headless CI operation that matches the job Use the single run command for the normal CI path. Use individual commands only when the pipeline deliberately separates creation, start, waiting, or evidence export.
Choose one path Run only the command that matches your situation.
01
Changes state PowerShell
Create, wait and export in one CI command Use this when Recommended: create, wait, and export evidence in one bounded CI operation.
Execute the complete admission-to-terminal-state workflow and optionally retain its evidence bundle.
Before you run it Reviewed payload Sufficient run and artifact permissions Protected BaseUrl/API-key environment PowerShell · headless-run Copy
pwsh -NoProfile -File ./scripts/clusterpilot-headless-ci.ps1 run `
-PayloadPath ./examples/ci/run-create.payload.sample.json `
-OutputPath ./artifacts/run-evidence.zip `
-IdempotencyKey "<stable-idempotency-key>" `
-PollIntervalSeconds 5 `
-TimeoutSeconds 1800 `
-MaxRetries 4✓ Expected result One JSON result binds run ID, status, exit code, create idempotency key and—when requested—bundle path, SHA-256 and export job.
Reviewed source scripts/clusterpilot-headless-ci.ps102
Changes state PowerShell
Create a run with the headless CI client Use this when Use when creation and execution are intentionally separated.
Submit a schema-reviewed run payload with bounded retries and a durable idempotency key.
Before you run it CLUSTERPILOT_BASE_URL and CLUSTERPILOT_API_KEY set in the protected environment Optional CLUSTERPILOT_TENANT_ID Reviewed payload file PowerShell · headless-create Copy
pwsh -NoProfile -File ./scripts/clusterpilot-headless-ci.ps1 create `
-PayloadPath ./examples/ci/run-create.payload.sample.json `
-IdempotencyKey "<stable-idempotency-key>"✓ Expected result JSON returns runId and the effective idempotencyKey; exit code 0 means admission succeeded.
Reviewed source scripts/clusterpilot-headless-ci.ps103
Changes state PowerShell
Start a run with the compatibility command Use this when Use only for a previously created compatible run.
Use the headless client's start command, which preserves the create/admission contract used by existing CI pipelines.
Before you run it Same protected environment and payload requirements as headless-create PowerShell · headless-start Copy
pwsh -NoProfile -File ./scripts/clusterpilot-headless-ci.ps1 start `
-PayloadPath ./examples/ci/run-create.payload.sample.json `
-IdempotencyKey "<stable-idempotency-key>"✓ Expected result JSON returns the admitted run ID and idempotency key without waiting for completion.
Stop conditions and operator notes create and start both admit a run in v0.0.1; retain start only for pipeline compatibility. Reviewed source scripts/clusterpilot-headless-ci.ps104
Read-only PowerShell
Wait for a run terminal state Use this when Use when another job created or started the run.
Poll durable run state with bounded retry/backoff and map terminal state to a CI exit code.
Before you run it Known run ID Protected BaseUrl/API-key environment PowerShell · headless-wait Copy
pwsh -NoProfile -File ./scripts/clusterpilot-headless-ci.ps1 wait `
-RunId "<run-id>" `
-PollIntervalSeconds 5 `
-TimeoutSeconds 1800 `
-MaxRetries 4✓ Expected result Exit 0 for success, 1 for failed, 2 for canceled or 3 for API-contract failure; JSON reports final state unless -Quiet is set.
Reviewed source scripts/clusterpilot-headless-ci.ps105
Changes state PowerShell
Export a run evidence bundle Use this when Use when only the evidence bundle must be exported.
Create an asynchronous export job, wait for readiness and download the immutable run bundle.
Before you run it Completed or export-eligible run runs/artifacts export permission Protected output directory PowerShell · headless-export-bundle Copy
pwsh -NoProfile -File ./scripts/clusterpilot-headless-ci.ps1 export-bundle `
-RunId "<run-id>" `
-OutputPath ./artifacts/run-evidence.zip `
-IdempotencyKey "<stable-export-idempotency-key>" `
-PollIntervalSeconds 5 `
-TimeoutSeconds 1800 `
-MaxRetries 4✓ Expected result JSON returns runId, export job, local path, SHA-256 and idempotency key.
Reviewed source scripts/clusterpilot-headless-ci.ps1Versioning and compatibility The path is versioned as /api/v1, while run and agent contracts have their own negotiated versions. Clients should ignore additive unknown response fields, preserve stable codes, and test against the target release’s OpenAPI and compatibility manifest before rollout.
