# API and integration guide

Version 0.1 | Proposed contract, no running product API | October 27, 2026

## 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

| Method and path | Meaning |
| --- | --- |
| GET /v1/workloads | List workloads visible to the caller, with cursor pagination. |
| GET /v1/workloads/{workloadId} | Read the current generation, enrollment state, and coverage assessment. |
| POST /v1/workloads/{workloadId}/stop-requests | Durably quarantine the specified current generation and accept a stop operation. |
| GET /v1/operations/{operationId} | Read operation status and independent check observations. |
| POST /v1/workloads/{workloadId}/recovery-reviews | Request a human review of a verified stop. Does not restart execution. |
| GET /v1/recovery-reviews/{reviewId} | Read the review state and its incident/generation binding. |
| POST /v1/recovery-reviews/{reviewId}/approvals | Approve the specific next-generation provisioning permit. Does not restore the old generation. |

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

| Status | Contract |
| --- | --- |
| 400 | Invalid JSON, extra mutation fields, missing required values, or invalid identifiers. |
| 401 | Missing, invalid, expired, or unacceptable authentication. |
| 403 | Authenticated caller lacks the requested action or authentication assurance. |
| 404 | Resource is absent or not visible in the caller's scope. |
| 409 | Generation, review revision, review state, or idempotency conflict. |
| 429 | Rate limit; bounded Retry-After. |
| 503 | Acceptance could not be established or a required service is unavailable. |

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.