Describe the work. Test the reality. Promote deliberately.

1. 1Queue the buildCopy

   # Use an exact Password Vault credential ID visible to this API identity.
   # The example works with personal or organization-service planner:write access.
   curl --fail-with-body --request POST \
     --header "Authorization: Bearer ${XY_API_KEY}" \
     --header "Idempotency-Key: portal-reconciliation-v1" \
     --header "Content-Type: application/json" \
     "${XY_API_BASE}/planner/builds" \
     --data '{
       "request": "Sign in, collect open records, normalize them, and return a per-record result.",
       "context": {
         "portal_url": "https://portal.example.com/open-records",
         "credential_id": "cred_REPLACE",
         "recorded_task_id": "portal-open-records-v1",
         "inputs": [{"name": "cutoff_date", "type": "string"}],
         "outputs": [{"name": "results", "type": "array"}]
       }
     }'

2. 2Read the existing buildCopy

   # Inspect the same build after a reload or interrupted command.
   : "${BUILD_ID:?Use the existing public build ID}"
   curl --fail-with-body --max-time 30 \
     --header "Authorization: Bearer ${XY_API_KEY}" \
     "${XY_API_BASE}/planner/builds/${BUILD_ID}"

Read GET /api/v1/planner/builds/{build_id} with planner:read. Plan review is required when status is awaiting_input and planner_state.awaiting_plan_approval is true. Other input gates also use awaiting_input, so check both fields. Inspect the proposed steps, inputs, outputs, and constraints, keeping the returned state_version for the plan you reviewed.

# Use the build ID returned by build creation. Requires planner:read.
if ! BUILD="$(curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/planner/builds/${BUILD_ID}")"; then
  exit 1
fi
printf '%s\n' "${BUILD}" | jq '{build_id, status, state_version, planner_state}'
if ! STATE_VERSION="$(printf '%s' "${BUILD}" | jq -er '
  select(.status == "awaiting_input" and .planner_state.awaiting_plan_approval == true)
  | .state_version | select(type == "number" and . > 0 and . == floor)
')"; then
  printf 'No whole plan is awaiting approval with a positive state version.\n' >&2
  exit 1
fi
# Stop here and review the proposed plan. Keep this STATE_VERSION for the decision.

Send POST /api/v1/planner/builds/{build_id}/plan/actionswith action set to APPROVE or REJECT, a positive integer expected_state_version, and an Idempotency-Key header. A nonblank comment is required for rejection and optional for approval. Personal or SYSTEM keys with planner:write can decide a plan for a build they can access. Approval allows step generation and testing to begin; it grants no workflow promotion, catalog publication, or Queue UI approval/publication authority.

# Requires planner:write.
: "${STATE_VERSION:?Use the state_version of the plan you just reviewed}"
: "${PLAN_DECISION_ID:?Set a unique ID for this logical plan decision; retain it with the body}"
if ! PLAN_BODY="$(jq -en --argjson version "${STATE_VERSION}" '
  $version | select(type == "number" and . > 0 and . == floor)
  | {action: "APPROVE", expected_state_version: .}
')"; then
  exit 1
fi
if ! curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: ${PLAN_DECISION_ID}" \
  --header "Content-Type: application/json" \
  --data "${PLAN_BODY}" \
  "${XY_API_BASE}/planner/builds/${BUILD_ID}/plan/actions"; then
  printf 'Read the existing build and events before any further decision; do not retry this POST after ambiguous output.\n' >&2
  exit 1
fi
# 202 queues a durable command. Poll the existing build and events for its outcome.

To request a revised plan, use the same route with the rejection body below instead of sending approval. Replace 7 with the version you reviewed and use a new decision key. Read and review the revised plan before deciding again.

{
  "action": "REJECT",
  "comment": "Collect only open records and exclude archived records from the plan.",
  "expected_state_version": 7
}

For MCP, read with planner_get_build, then call planner_respond_to_plan with state_versionset to the version you reviewed; the tool maps it to REST expected_state_version. Replace the illustrative ID, version, and key below. To reject, change action to REJECT and include a nonblank comment in the arguments.

{
  "tool": "planner_respond_to_plan",
  "arguments": {
    "build_id": "pbld_REPLACE",
    "action": "APPROVE",
    "state_version": 7,
    "idempotency_key": "plan-decision-REPLACE"
  }
}

Queue UI Designer creates a durable design session with immutable versions and previews. A person approves an exact version and hash in the web review page, or an authorized system key records system approval through the separate approval operation. A publish call can then make it live. Publish takes the design version ID and compares the expected live publication receipt ID. Rollback takes a retained publication or captured baseline receipt ID, and each activation returns a fresh live receipt. Personal keys and personal MCP OAuth require Queue UI scopes and explicit workflow access/configure permission. System keys use authorized organization access; only they can hold queue_ui:approve. Custom React, new backend actions, and live editing of Git-managed queues are outside this surface.

1. 1Promote the completed buildCopy

   : "${XY_API_KEY:?Use an authorized key with planner:read to read the build and ETag}"
   : "${XY_PROMOTION_SERVICE_KEY:?Use an organization service key with planner:promote}"
   BUILD_HEADERS="$(mktemp)"
   BUILD="$(curl --fail-with-body --dump-header "${BUILD_HEADERS}" \
     --header "Authorization: Bearer ${XY_API_KEY}" \
     "${XY_API_BASE}/planner/builds/${BUILD_ID}")"
   BUILD_ETAG="$(awk 'tolower($1) == "etag:" {print $2; exit}' "${BUILD_HEADERS}" | tr -d '\r')"
   rm -f "${BUILD_HEADERS}"
   : "${BUILD_ETAG:?The Planner agent build response did not include ETag}"
   printf '%s\n' "${BUILD}" | jq '{id, status, state_version}'
   
   
   curl --fail-with-body --request POST \
     --header "Authorization: Bearer ${XY_PROMOTION_SERVICE_KEY}" \
     --header "Idempotency-Key: ${BUILD_ID}-promote-v1" \
     --header "If-Match: ${BUILD_ETAG}" \
     --header "Content-Type: application/json" \
     "${XY_API_BASE}/planner/builds/${BUILD_ID}/promote" \
     --data '{
       "name": "Portal record reconciliation",
       "description": "Collects and normalizes open records."
     }'

2. 2Run the definition onceCopy

   # No schedule is required. Use the ID returned by promotion.
   : "${BUSINESS_ATTEMPT_ID:?Set a stable unique ID for this logical run}"
   RESPONSE_HEADERS="$(mktemp)"
   trap 'rm -f "${RESPONSE_HEADERS}"' EXIT
   if ! RUN_RESPONSE="$(curl --fail-with-body --request POST \
     --dump-header "${RESPONSE_HEADERS}" \
     --header "Authorization: Bearer ${XY_API_KEY}" \
     --header "Idempotency-Key: portal-reconciliation-${BUSINESS_ATTEMPT_ID}" \
     --header "Content-Type: application/json" \
     "${XY_API_BASE}/workflow-definitions/${WORKFLOW_DEFINITION_ID}/executions" \
     --data '{
       "input": {"region": "west"}
     }')"; then
     printf '%s\n' "${RUN_RESPONSE}" >&2
     exit 1
   fi
   printf '%s\n' "${RUN_RESPONSE}"
   
   
   # 202 Accepted
   # {
   #   "workflow_definition_id": "...",
   #   "workflow_instance_id": "...",
   #   "status": "running",
   #   "status_url": "/api/v1/workflow-runs/.../phases"
   # }
   
   
   # Follow the relative status_url returned above without duplicating /api/v1.
   STATUS_URL="$(printf '%s' "${RUN_RESPONSE}" | jq -r '.status_url')"
   STATUS_PATH="${STATUS_URL#/api/v1}"
   POLL_SECONDS="$(awk 'tolower($1) == "retry-after:" {gsub("\r", "", $2); print $2}' "${RESPONSE_HEADERS}")"
   POLL_SECONDS="${POLL_SECONDS:-2}"
   case "${POLL_SECONDS}" in
     *[!0-9]*|"") POLL_SECONDS=2 ;;
   esac
   if [ "${POLL_SECONDS}" -lt 1 ]; then
     POLL_SECONDS=1
   fi
   
   
   # A newly accepted run can return 404 until its projection is created.
   # Poll until the documented runtime status is terminal, or fail after 5 minutes.
   TERMINAL_STATUS=""
   DEADLINE=$(( $(date +%s) + 300 ))
   while :; do
     REMAINING=$(( DEADLINE - $(date +%s) ))
     if [ "${REMAINING}" -le 0 ]; then
       break
     fi
   
   
     if PHASE_RESULT="$(curl --silent --show-error \
       --max-time "${REMAINING}" \
       --write-out '\n%{http_code}' \
       --header "Authorization: Bearer ${XY_API_KEY}" \
       "${XY_API_BASE}${STATUS_PATH}")"; then
       HTTP_STATUS="${PHASE_RESULT##*$'\n'}"
       PHASE_RESPONSE="${PHASE_RESULT%$'\n'*}"
   
   
       if [ "${HTTP_STATUS}" -ge 400 ] && [ "${HTTP_STATUS}" != "404" ]; then
         printf '%s\n' "${PHASE_RESPONSE}" >&2
         exit 1
       fi
   
   
       if [ "${HTTP_STATUS}" != "404" ]; then
         EXECUTION_STATUS="$(printf '%s' "${PHASE_RESPONSE}" | jq -r '.execution_status // .workflow_status // ""')"
         case "${EXECUTION_STATUS}" in
           COMPLETED|COMPLETED_WITH_FAILURES|FAILED|TIMED_OUT|CANCELED|CANCELLED|TERMINATED)
             TERMINAL_STATUS="${EXECUTION_STATUS}"
             printf '%s\n' "${PHASE_RESPONSE}"
             break
             ;;
         esac
       fi
     fi
   
   
     REMAINING=$(( DEADLINE - $(date +%s) ))
     if [ "${REMAINING}" -le 0 ]; then
       break
     fi
     SLEEP_SECONDS="${POLL_SECONDS}"
     if [ "${SLEEP_SECONDS}" -gt "${REMAINING}" ]; then
       SLEEP_SECONDS="${REMAINING}"
     fi
     sleep "${SLEEP_SECONDS}"
   done
   
   
   if [ -z "${TERMINAL_STATUS}" ]; then
     printf 'Run did not reach a terminal state within 5 minutes.\n' >&2
     exit 1
   fi

3. 3Create and trigger a scheduleCopy

   : "${SCHEDULE_TRIGGER_ATTEMPT_ID:?Set a stable unique ID for this logical trigger}"
   curl --fail-with-body --request POST \
     --header "Authorization: Bearer ${XY_API_KEY}" \
     --header "Content-Type: application/json" \
     "${XY_API_BASE}/workflow-definitions/${WORKFLOW_DEFINITION_ID}/schedule" \
     --data '{
       "cron_expression": "0 9 * * 1-5",
       "input": {"region": "west"},
       "overlap_policy": "SKIP",
       "note": "Weekday run"
     }'
   
   
   # Trigger that existing schedule now.
   curl --fail-with-body --request POST \
     --header "Authorization: Bearer ${XY_API_KEY}" \
     --header "Idempotency-Key: schedule-trigger-${SCHEDULE_TRIGGER_ATTEMPT_ID}" \
     --header "Content-Type: application/json" \
     "${XY_API_BASE}/workflow-definitions/${WORKFLOW_DEFINITION_ID}/schedule/trigger" \
     --data '{}'

# XY first grants this API identity analytics-only view access to the exact
# production workflow definition. No catalog agent or installation is required.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/workflow-definitions/${WORKFLOW_DEFINITION_ID}/metrics/dashboards"


# Render one approved view as presentation-ready JSON for your own UI.
# FROM_DATE and TO_DATE are YYYY-MM-DD dates and must be supplied together.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/workflow-definitions/${WORKFLOW_DEFINITION_ID}/metrics/dashboards/operations?from=${FROM_DATE}&to=${TO_DATE}"