Queue UI Designer

Personal API keys and personal MCP OAuth are separate authorization choices. An OAuth grant can include Planner promotion even though a personal API key cannot. Neither allows queue_ui:approve. Check the grant and workflow permissions for the credential you actually use; do not infer them from another key or connection.

System approval is an automated organization decision, not human review and not approval by the person who created the key. Publication cannot create approval. Keep approval authority separate from design authoring unless your automation is explicitly authorized for both; giving a personal key more scopes cannot turn it into a system key.

With the required scopes and workflow permissions, a personal key or MCP connection can open and continue your own public designs and public designs created by your organization's system identity. This does not expose another person's private design sessions. A system-created design can also be reviewed by an authorized person in the web app; approval and publication still require their separate permissions.

Personal or SYSTEM Planner keys with planner:write can bind a known, eligible service-owned public credential reference without credentials:read. Binding does not grant credential management or return secret values, and user-created UI vault entries are not automatically public references. Review the separate credential ownership boundary before designing a workflow that needs a saved password or API token.

Personal author, human review

Use personal read/write access to generate the design. Open the review link and approve the exact version in the web app. A personal or system key with publish authority can then publish the approved version.

Personal author, system release

Use personal read/write access for design work. Give the authorized organization automation the session and design version IDs. Its system key needs read, approve, and publish scopes to inspect the version, approve its exact hash, and publish in separate calls.

System-managed design and release

Use a system key explicitly granted all four Queue UI scopes. Generate, inspect, approve, and publish as separate stages. Creating and promoting a prerequisite Planner workflow additionally needs the relevant Planner scopes; Queue UI scopes do not grant them.

1. An authorized administrator enables Queue UI Designer and API-key or interactive MCP access for the organization and grants the user the relevant scopes in the organization's access management UI. API-key access and MCP OAuth access have separate scope grants. The user also needs access to the Queue UI Designer feature.
2. For REST, the user opens Organization settings, API Keys, chooses Personal, and selects a subset of their granted scopes. For MCP OAuth, the user connects tohttps://mcp.xy.ai/mcp, signs in, and consents to the organization and effective scopes. Granting API-key scopes does not automatically extend an OAuth grant.
3. The user must also have explicit workflow access and configure permission on the selected target when using personal access. XY checks current membership, effective scope authority, and workflow permissions on requests. Removing access can make an existing key or session unusable.

For organization automation, an authorized administrator creates a System key in API Keys and selects explicitly granted scopes. A delegated administrator also needsapi_keys:manage_service and authority to issue the selected scopes. System requests use the organization's access to eligible workflows, not the key creator's personal workflow permissions. The organization must have Queue UI Designer and API-key access enabled. To use this system key through MCP, configure API-key authentication; signing in through personal OAuth does not create system access.

1. Find the workflow with queue_ui_list_targets and start a session with queue_ui_start_design.
2. Poll queue_ui_get_design and queue_ui_get_events using the returned session and run identifiers.
3. Compare immutable versions with queue_ui_list_versions and queue_ui_get_version. Open the selected version's preview and inspect its validation.
4. Send specific feedback with queue_ui_send_message to generate another version. Each revision needs its own review.
5. For human review, open /queue-designs/qds_<cuid>?version=<design_version> in the web app and approve that exact version and hash. For authorized automation, use the separate system-only queue_ui_approve operation described below.
6. After approval, call queue_ui_publish with that design version ID and the current publication receipt ID you expect to replace, or explicit null initially. Read the result, retain the new live receipt ID, and open the returned live link.
7. When the session is finished, call queue_ui_cleanup_previews. This closes the session before removing previews. Further messages and publishing require a new design session; rollback to a previous publication remains available.

: "${WORKFLOW_DEFINITION_ID:?Choose an eligible workflow from targets}"
: "${QUEUE_DESIGN_ATTEMPT_ID:?Keep a stable unique key for this design request}"


if ! DESIGN="$(jq -n --arg workflow_definition_id "${WORKFLOW_DEFINITION_ID}" \
  '{workflow_definition_id: $workflow_definition_id,
    prompt: "Show record ID, status, and updated time. Put the newest records first and keep the detail view compact."}' |
  curl --fail-with-body --request POST \
    --header "Authorization: Bearer ${XY_API_KEY}" \
    --header "Idempotency-Key: ${QUEUE_DESIGN_ATTEMPT_ID}" \
    --header "Content-Type: application/json" \
    --data-binary @- \
    "${XY_API_BASE}/queue-designs")"; then
  printf '%s\n' "${DESIGN}" >&2
  exit 1
fi
printf '%s\n' "${DESIGN}"
# Retain this public ID and the response's run ID and review_url.
QUEUE_DESIGN_ID="$(printf '%s' "${DESIGN}" | jq -er '.id')"

: "${QUEUE_DESIGN_ID:?Use the returned qds_ session ID}"


# Read the current durable state. Repeat reads at a bounded polling interval.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/queue-designs/${QUEUE_DESIGN_ID}"


# Start at zero; persist the last processed event seq before reconnecting.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/queue-designs/${QUEUE_DESIGN_ID}/events?after_seq=${LAST_EVENT_SEQ:-0}&limit=100"


curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/queue-designs/${QUEUE_DESIGN_ID}/versions"

: "${QUEUE_DESIGN_ID:?Use the returned public design ID}"
: "${QUEUE_MESSAGE_ATTEMPT_ID:?Use a new stable key for this revision request}"
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: ${QUEUE_MESSAGE_ATTEMPT_ID}" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/queue-designs/${QUEUE_DESIGN_ID}/messages" \
  --data '{"prompt":"Rename the Updated column to Last activity and move it next to Status."}'

Make daily work easier to scan

"For our promoted reconciliation workflow, show record ID, status, and last updated time. Put the newest records first and make the detail view compact. Give me a preview to review."

Refine a saved preview

"In this design session, move Status next to Record ID and rename Updated to Last activity. Keep the existing status meanings. Generate a new version and send me the review link."

Publish after web review

"I approved design B in the web review page. Publish that exact design, provided the live publication receipt is still P1. Stop and report a conflict if someone has changed the live queue."

Release through authorized system automation

"Inspect design B and its validation. If it meets our release policy, use our authorized system approval operation for B and its returned hash while P1 is still live. Then publish B with the same expected receipt. Record this as a system decision, not human review. Stop on a conflict."

Restore an earlier operator screen

"Restore the configuration saved in publication receipt P1, replacing P2 only if P2 is still live. Return the new live receipt and keep workflow records and execution state intact."

Restore the original queue

"Restore the baseline captured before our first Queue UI publication. Use its baseline receipt as the rollback target and stop if the live receipt has changed."

Complete the design session

"We are finished with this session. Close it and remove its temporary previews. Preserve the saved versions, publication history, and live workflow. I will start a new session for future design changes."

B is a design label; P1 and P2 are publication receipt labels. Use actual returned IDs in tool arguments. The server verifies approval even when the person says they have approved a version.

Cancel with queue_ui_cancel_run when generation should stop; specify the run ID to avoid cancelling a newer run. Cancellation retains saved versions and previews.