Skip to main content

Documentation Index

Fetch the complete documentation index at: https://colossal.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

An approval step pauses the workflow until a workspace user approves or denies it. Approve continues to the next step. Deny ends the run with CANCELLED and the next step never executes. Use it before high-stakes actions: refunds, large discounts, bulk price changes, sending to many customers, anything you want a human to confirm before it runs.

​
Configuration

FieldTypeDescription
titlestringShort headline shown to the approver. Templates allowed.
messagestring (optional)Multi-line body shown alongside the title. Templates allowed. Put detail here, not in the title.
The step also inherits description from the base step type — that’s a plain-English meta description of what the step does (used in summaries), not approver-facing text.

​
Example

{
  "id": "approve_refund",
  "type": "approval",
  "description": "Pause for human review before issuing the refund.",
  "title": "Approve refund?",
  "message": "Customer: {{customer.email}}\nOrder: {{order_uid}}\nRefund amount: {{currency}} {{steps.compute.amount}}\nReason: {{steps.compute.reason}}",
  "next": "send_refund"
}

​
How it appears in the dashboard

When the workflow reaches an approval step:
  • The run status flips to Paused
  • The step appears in the activity log with status Awaiting approval
  • Clicking the step opens a panel with the rendered title, message, and Approve / Deny buttons
  • Anyone with workspace write access can decide
After a decision:
  • Approve → the run resumes and continues to next
  • Deny → the run ends with status CANCELLED. The next step does not run.
The decision (approved / denied), who decided, and when are recorded on the activity row.

​
Title and message guidance

Keep the title short and scannable — it’s a heading the approver reads at a glance. Put the data they need to decide in message as labelled lines. Good: 
{
  "title": "Send refund email?",
  "message": "Customer: {{customer.email}}\nOrder: {{order_uid}}\nTotal: {{currency}} {{total_amount}}"
}
Avoid stuffing IDs and totals into title: 
{
  "title": "Approve order {{order_uid}} ({{currency}} {{total_amount}}) for {{customer.email}}?"
}

​
Behavior

  • The workflow waits indefinitely. There is no automatic timeout in v1.
  • Decisions are idempotent — submitting twice for the same approval is rejected at the service layer.
  • Denial cancels the workflow run cleanly. No retries, no error.

​
Use cases

  • Manual review of refunds before they are issued
  • Approval before sending price-change emails to all customers
  • Confirm bulk product archive actions
  • Review AI-generated content before it is published

​
Next steps

  • App action. Run an action only after approval
  • Choice step. Branch on prior step output before requesting approval
  • Data access. Reference trigger and step data in title and message templates