Approvals & Human Tasks

Put humans in the loop at any point in an AI workflow. Approvals let a person review and authorise an AI decision before it takes effect. Human Tasks present structured forms that collect input from a user and feed the response into downstream workflow nodes.

Overview

Both Approvals and Human Tasks are backed by the same ApprovalRequest model. The distinction is in how they are created and completed:

• Approvals — generated automatically by the platform when an action requires human sign-off. A reviewer approves or rejects the request.
• Human Tasks — generated by a workflow human_task node. A form schema defines the fields the user must fill in. The submitted data is passed as input to downstream nodes.

When Approvals are Required

Approvals are triggered in the following scenarios:

• Experiment AwaitingApproval state — when an experiment transitions to AwaitingApproval, execution is halted until a team member approves the plan. On approval the experiment advances to Approved and then to Executing. On rejection it returns to Planning.
• Outbound delivery — certain outbound connectors can be configured to require approval before messages are sent, preventing automated sending without human review.
• Workflow human_task nodes — a node of this type pauses the workflow graph and creates a Human Task for a designated user or role.
• Budget threshold alerts — when spending approaches plan limits the platform may pause an experiment and request manual review before continuing.

Approval Inbox

The Approval Inbox is available at /approvals. It lists all pending requests for the current team, ordered by creation time.

• Each request shows the context payload — what the AI was about to do and why approval is needed.
• Inline Approve and Reject buttons act immediately without a page reload.
• For Human Tasks, an Open Form button opens the HumanTaskForm Livewire component in a slide-over panel.
• A status filter lets you review historical decisions (approved, rejected, expired).

Approval Statuses

Every ApprovalRequest moves through the following statuses:

The approvals:expire-stale scheduled command runs every hour and moves overdue pending requests to expired.

Human Tasks

A Human Task is an ApprovalRequest that carries a form_schema JSON Schema. The schema defines the fields that must be completed before the workflow can continue.

When a workflow reaches a human_task node:

1. The platform creates an ApprovalRequest linked to the node, with the node's form_schema and the assigned user or role.
2. The workflow execution pauses — no downstream nodes run.
3. The assigned user sees the task in the Approval Inbox and opens the HumanTaskForm Livewire slide-over.
4. On submission the form data is validated against form_schema and stored on the request.
5. The workflow resumes, and the next node receives the submitted data as its input payload.

Example form_schema

{
  "type": "object",
  "required": ["decision", "notes"],
  "properties": {
    "decision": {
      "type": "string",
      "title": "Decision",
      "enum": ["approve", "revise", "discard"],
      "description": "Select the outcome for this campaign draft."
    },
    "notes": {
      "type": "string",
      "title": "Notes",
      "description": "Provide feedback for the AI agent.",
      "minLength": 10
    },
    "budget_override": {
      "type": "number",
      "title": "Budget Override (€)",
      "description": "Optional: override the proposed budget ceiling."
    }
  }
}

SLA Enforcement

Human Tasks can carry an SLA deadline. If the task is not completed by that deadline, the platform escalates or expires it automatically.

The human-tasks:check-sla scheduled command runs every 5 minutes and performs two checks:

• Escalation — if the task is approaching its deadline (configurable warning window), team admins and the assigned user receive a notification.
• Expiry — if the deadline has passed, the task is marked expired and the blocked workflow node is failed, allowing the workflow to continue along its error path.

Webhook Notifications

You can configure a webhook URL to receive real-time events whenever an approval is created, approved, rejected, or expires. This is useful for integrating approval state into external tools such as Slack, Jira, or a custom dashboard.

Events are sent as POST requests with a JSON body:

{
  "event": "approval.approved",
  "approval_request_id": "019501de-...",
  "status": "approved",
  "decided_by": "user@example.com",
  "decided_at": "2026-03-21T14:05:00Z",
  "context": { ... }
}

Configure the webhook endpoint using the approval_webhook_config MCP tool or via the Team Settings page.

MCP Tools

All approval and human-task operations are available to AI agents via the FleetQ MCP server.

API Endpoints

All endpoints are under /api/v1/approvals and require a Sanctum bearer token.

Integration with Workflows

Human Task nodes are first-class citizens of the workflow graph. See the Workflows documentation for full details on building visual DAGs.

Key points when using Human Tasks inside a workflow:

• A human_task node pauses workflow execution. No nodes downstream of it will run until the task is completed or expires.
• The form_schema is defined on the workflow node configuration and may reference upstream node outputs using template variables.
• Once the task is completed, the submitted form_data object becomes the output of the node and is available to all downstream nodes via the standard {{ node_id.field_name }} template syntax.
• Add an error edge from every human_task node to handle the case where the task expires without a response.

{
  "id": "review-copy",
  "type": "human_task",
  "label": "Review campaign copy",
  "config": {
    "assigned_role": "admin",
    "sla_hours": 24,
    "form_schema": {
      "type": "object",
      "required": ["approved"],
      "properties": {
        "approved": { "type": "boolean", "title": "Approve this copy?" },
        "feedback": { "type": "string", "title": "Feedback for the writer" }
      }
    }
  }
}