API & integration guide

API boundary

The OpenAPI 3.1 contract in openapi.json is an implementation starting point. Its example server uses the reserved .invalid domain. It does not describe the existing website contact form or turn the browser simulation into a real control service.

All endpoints require authenticated operator identity and action-specific authorization. The chosen identity integration must validate token issuer, audience, signature, expiry, and configured authentication assurance. A bearer token alone is not proof of MFA or permission to operate every workload. Resolve environment and workload scope from trusted policy, not a caller-supplied tenant header.

Proposed endpoints

The first product API does not accept arbitrary AWS account IDs, task ARNs, role ARNs, policy documents, or connector URLs in these requests. Enrollment and provisioning are operator-controlled deployment procedures for the sandbox.

Identity and state contracts

Workload IDs, operation IDs, and review IDs are UUIDs. Generation numbers are positive integers. The current workload state is ENROLLING, ARMED, QUARANTINED, RECOVERING, or RETIRED. Keep per-generation quarantine records when the current generation changes.

Stop operations use ACCEPTED, ENFORCING, VERIFYING, VERIFIED_STOPPED, PARTIAL, FAILED, or UNKNOWN. Per-check results are PENDING, PASSED, FAILED, or UNKNOWN; each required check has provenance and an observation timestamp when a result exists. An API success response is not a verification result.

Recovery reviews use REQUESTED, APPROVED, REJECTED, EXPIRED, or CONSUMED. Only the trusted provisioner consumes the approval. The review and next-generation launch must bind to the same workload and incident. A later stop or generation change invalidates an outstanding permit.

Mutation behavior and concurrency

Every POST requires an Idempotency-Key UUID. Scope the durable key to the authenticated environment, action, and target. The same key and semantic payload resolve to the same resource ID; conflicting reuse returns 409. Replays do not create a fresh workflow, review, or permit. An authorized repeat stop for an already quarantined generation returns the existing stop operation rather than silently starting a competing operation.

Retain application idempotency mappings for a proposed seven-day sandbox window. A database or provider token's shorter retention cannot replace this contract. Quarantine records do not expire with an idempotency key.

The stop body includes expectedGeneration and a bounded reason. A generation mismatch returns 409 with a scoped refresh instruction. The response is 202 and a Location pointing to the operation. It means the fence and operation record are durable, not that task stopping is complete. A replay may refer to an already completed operation; GET returns its latest assessment.

Use the registry/outbox transaction described in the architecture. A workflow-start timeout is reconciled by operation identity. Each connector action must handle retries and uncertain provider results without releasing the quarantine latch.

Error and observation behavior

Errors return a stable code, safe message, and requestId. Never include credentials, internal policy bodies, or another customer's identifiers. A client uncertain whether a POST was accepted must retry with the same key and body. It must not infer rejection merely from a lost response.

An unavailable observation endpoint must not leave the operator looking at an apparently current verified result. Show the observation time, current coverage, and a connection/staleness notice. An operation can be incomplete even while some controls succeeded.

Enrollment prerequisites

Validate the designated accounts, Region, cluster, exact launch definition, per-generation identity, launcher exclusivity, network paths, gateway mapping, and diagnostic probe. Record root/child ownership and required check types. Treat evidence-store and control-identity protections as prerequisites, not agent-editable runtime settings.

The sandbox task role includes only the enrolled tool API and one harmless diagnostic-object read. A trusted probe using the same generation role tests effective identity denial independently of the agent. Keep provider keys, privileged credentials, and probe credentials out of agent outputs and evidence documents.

Operator implementation notes

Require one deliberate, scope-specific human stop action. The dashboard must display the selected workload and generation and then track individual outcomes rather than animate a guaranteed success sequence. The existing website demo remains illustrative until a separate authenticated implementation exists.

Recovery approval and runtime restoration are different actions. Use the runbook to consume a single-use approval and prepare a new generation. API, audit, identity, and connector behavior must pass the validation matrix before the UI can make a verified-stop claim.

Explore the proposed API contract

This is a read-only contract reference. The example server is non-operational; these controls do not send requests.

GET/v1/workloads

List authorized workloads

Returns only workloads in the caller's policy scope. No cross-environment enumeration.

Required action: killswitch:Read

Response codes: 200, 400, 401, 403, 404, 409, 429, 503

GET/v1/workloads/{workloadId}

Read current workload coverage

Coverage is an observation of the enrolled boundary, not a claim of permanent containment.

Required action: killswitch:Read

Response codes: 200, 400, 401, 403, 404, 409, 429, 503

POST/v1/workloads/{workloadId}/stop-requests

Latch quarantine and accept a stop operation

Atomically persists quarantine, the stop operation, and its dispatch outbox. Does not assert stopped execution. A same-generation repeat resolves to the existing stop operation. GET the operation for its current assessment.

Required action: killswitch:Stop

Required request fields:

• expectedGeneration
• reason

Also requires an Idempotency-Key UUID. Additional request fields are rejected in this contract.

Response codes: 202, 400, 401, 403, 404, 409, 429, 503

GET/v1/operations/{operationId}

Read independently observed stop results

VERIFIED_STOPPED requires every required check key to be present once and PASSED with attributable fresh observations. Later contradictory evidence appends another verification attempt.

Required action: killswitch:Read

Response codes: 200, 400, 401, 403, 404, 409, 429, 503

POST/v1/workloads/{workloadId}/recovery-reviews

Request human review of a verified stop

Requires the current quarantined generation and its verified stop operation. Creates a review only; does not restart or restore access.

Required action: killswitch:RequestRecovery

Required request fields:

• expectedGeneration
• stopOperationId
• reason

Also requires an Idempotency-Key UUID. Additional request fields are rejected in this contract.

Response codes: 202, 400, 401, 403, 404, 409, 429, 503

GET/v1/recovery-reviews/{reviewId}

Read a generation-bound recovery review

Approval is not restoration. Only the trusted provisioner can consume the single-use permission for the specified next generation.

Required action: killswitch:Read

Response codes: 200, 400, 401, 403, 404, 409, 429, 503

POST/v1/recovery-reviews/{reviewId}/approvals

Record an authorized human recovery decision

Requires REQUESTED state, matching revision, current generation, fresh required verification, and configured human authentication assurance. Approval creates a short-lived single-use provisioning permission; it cannot clear the old generation's deny or latch.

Required action: killswitch:ApproveRecovery

Required request fields:

• expectedRevision
• reason

Also requires an Idempotency-Key UUID. Additional request fields are rejected in this contract.

Response codes: 202, 400, 401, 403, 404, 409, 429, 503

Download the OpenAPI 3.1 JSON contract