---
canonical_url: "https://docs.composio.dev/toolkits/hitl"
markdown_url: "https://docs.composio.dev/toolkits/hitl.md"
product: "platform"
version: null
last_updated: null
---

# Human Approval - HITL Platform

HITL.sh adds human approval and review workflows to AI agents and automations through loops and structured requests.

- **Category:** ai agents
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 10
- **Triggers:** 0
- **Slug:** `HITL`
- **Version:** 00000000_00

## Tools

### Cancel Approval Request

**Slug:** `HITL_CANCEL_APPROVAL_REQUEST`

Irreversibly cancel a pending approval request so reviewers can no longer complete it. The request remains in history with cancelled status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | 24-character hexadecimal ID of the pending approval request to cancel. Completed, timed-out, or already-cancelled requests cannot be cancelled. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Approval Request

**Slug:** `HITL_CREATE_APPROVAL_REQUEST`

Create and broadcast one human approval request to active members of an owned loop, consuming one provider request allowance.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Content attached to the request, selected by its type field. |
| `context` | object | No | Optional JSON object with task context for the approver and response correlation. |
| `loop_id` | string | Yes | 24-character hexadecimal ID of the owned loop whose active members should receive the request. |
| `priority` | string ("low" | "medium" | "high" | "critical") | No | Urgency shown to reviewers. |
| `response` | string | Yes | Expected human response, type-specific configuration, and compatible fallback value. |
| `callback_url` | string | No | Optional HTTPS endpoint for completed, timeout, or cancelled events. Validate and deduplicate events because HITL documents no webhook signature. |
| `request_text` | string | Yes | Question or review instructions shown to the human approver (1-2000 characters). |
| `processing_type` | string ("deferred" | "time-sensitive") | No | Use deferred for a long-lived request or time-sensitive with an explicit timeout. |
| `timeout_seconds` | integer | No | Required for time-sensitive requests and optional for deferred requests; seconds before timeout (60-86400). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Loop

**Slug:** `HITL_CREATE_LOOP`

Create an approval loop and return its loop ID and human invitation links; the connected account is added as an active member.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `icon` | string | Yes | HITL icon identifier or emoji displayed for the loop (maximum 100 characters). |
| `name` | string | Yes | Loop name shown to reviewers (1-100 characters). |
| `description` | string | No | Optional purpose or instructions for the loop (maximum 500 characters). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Loop

**Slug:** `HITL_DELETE_LOOP`

Permanently delete an owned loop and all of its memberships, approval requests, responses, feedback, and analytics. This cascading deletion erases the loop's entire history and cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | 24-character hexadecimal ID of the loop to permanently delete. Use only for a loop whose memberships, approval requests, responses, feedback, analytics, and entire history may be erased. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account Status

**Slug:** `HITL_GET_ACCOUNT_STATUS`

Return the connected HITL account identity, status, permissions, and provider-reported request allowance before creating an approval request.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Approval Request

**Slug:** `HITL_GET_APPROVAL_REQUEST`

Get the current status, configuration, and human response for one approval request; use for deliberate polling after creation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | 24-character hexadecimal ID of the approval request to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Approval Requests

**Slug:** `HITL_LIST_APPROVAL_REQUESTS`

Return approval requests created by the connected API key, optionally restricted to one loop; pagination controls are omitted because the live API currently ignores them.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | No | Optional 24-character hexadecimal loop ID. When provided, list only that loop's requests using the dedicated loop endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Loop Members

**Slug:** `HITL_LIST_LOOP_MEMBERS`

Return a loop's active and pending human reviewers so an agent can verify readiness before broadcasting an approval request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | 24-character hexadecimal ID of the loop whose members to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Loops

**Slug:** `HITL_LIST_LOOPS`

Return all approval loops owned by the connected account, including embedded members and membership counts.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Loop

**Slug:** `HITL_UPDATE_LOOP`

Update one or more display fields of an owned approval loop without changing its members or requests.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `icon` | string | No | New HITL icon identifier or emoji (maximum 100 characters). |
| `name` | string | No | New loop name (1-100 characters). |
| `loop_id` | string | Yes | 24-character hexadecimal ID of the loop to update. |
| `description` | string | No | New loop description (maximum 500 characters); pass an empty string to clear it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |