API flow examples

The examples use https://api.example.test as a placeholder. Replace it with the public API base URL and use an access token obtained from login or a scoped API key. IDs are illustrative UUIDs.

Login and inspect the tenant

API=https://api.example.test

curl -sS -X POST "$API/api/v1/auth/login" \
  -H 'content-type: application/json' \
  -d '{"email":"operator@example.com","password":"use-a-real-password"}'

curl -sS "$API/api/v1/me" \
  -H "authorization: Bearer $ACCESS_TOKEN"

The response identifies memberships and role. Do not send an organization ID to select a tenant; the API resolves it from the authenticated context.

Enroll a mock account and sync

curl -sS -X POST "$API/api/v1/cloud/accounts" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"provider":"aws","name":"demo-aws","mode":"MOCK","credentials":{},"region":"us-east-1"}'

curl -sS -X POST "$API/api/v1/cloud/accounts/$ACCOUNT_ID/sync" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: sync-demo-aws-2026-08-05'

curl -sS "$API/api/v1/resources?provider=aws&limit=50" \
  -H "authorization: Bearer $ACCESS_TOKEN"

Mock sync returns deterministic resources. It does not prove that an AWS account was contacted.

Plan, approve and apply

curl -sS -X POST "$API/api/v1/provisioning/plans" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: plan-demo-vpc-001' \
  -d '{"workspaceId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000002","inputs":{"name":"demo-vpc"}}'

curl -sS -X POST "$API/api/v1/provisioning/runs/$RUN_ID/approve" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"reason":"Reviewed the plan, policy result and monthly estimate."}'

curl -sS -X POST "$API/api/v1/provisioning/runs/$RUN_ID/apply" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: apply-demo-vpc-001'

Apply is safe to retry with the same idempotency key. A changed plan digest, expired approval, stale snapshot or missing entitlement must produce a hard failure instead of a second or mis-targeted apply.

Read and approve an AI tool proposal

curl -sS "$API/api/v1/ai/approvals" \
  -H "authorization: Bearer $ACCESS_TOKEN"

curl -sS -X POST "$API/api/v1/ai/approvals/$APPROVAL_ID/approve" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"reason":"Approved the reviewed restart target."}'

Risk 3 additionally requires secondConfirmation: true and the server still re-checks permissions, entitlement and policy. Approval is for the exact typed proposal, not for future similar requests.

Error handling

{
  "error": {
    "code": "ENTITLEMENT_MISSING",
    "message": "Entitlement provisioning.apply is not enabled for this organization",
    "details": { "key": "provisioning.apply" },
    "requestId": "req_01J..."
  }
}

Log the request ID, not credentials. Retry 429, network failures and transient 5xx only when the operation is documented as idempotent. Never blindly retry risk 3 actions or create a new idempotency key for the same intent.