1. Create a plan
POST /api/v1/plans describes the intended resource and steps. Each step has exactly one requirement specifying resource class, external account and capability; these must match the plan's resource. Include a stable idempotency key.
A 202 response returns the plan ID, status, intent_hash, resource ID and outcome. Planning records intent; it does not execute a provider operation. A workload must already be bound to the resource and have planning permission.
2. Queue and inspect an operation
POST /api/v1/operations takes plan_id, the matching plan_intent_hash, approved: true and an idempotency key. It checks execution scopes and resource binding, then registers or replays a job for the worker.
A queued response is not provider success. The worker must still process the job; provider capability, ownership and safety gates can block it. Do not treat HTTP 202 as proof of certificate issuance, activation or delivery.
Use GET /api/v1/operations/{id} to inspect the operation, plan, steps and visible evidence. Workload reads require organization/resource binding and read permission.
3. Control queued work
POST /api/v1/operations/{id} supports approval, approval revocation and cancellation of queued work. It requires organization write access and the relevant plan/resource scopes. Cancellation is not available after execution starts and does not undo a completed provider effect.
Check the current status before acting. For exact control payloads, approval identifiers and conflict responses, use the OpenAPI reference.
4. Record consumer evidence
POST /api/v1/receipts records a registered consumer's observed version. Supply organization/resource IDs, consumer kind/reference, version and an idempotency key; include the operation ID when linking to a job.
Workload callers need change:receipt and a matching GitHub consumer. Stale or mismatched observations may be recorded as historical rather than accepted. Inspect the receipt result; storing evidence alone does not establish current acceptance or payment success.
Keep retries tied to the same intent using the idempotency rules.