> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool approvals

> Pause an agent run for approval and continue it with the public API

When tool approvals are enabled, `POST /v1/agent/invoke` can finish with `status: "awaiting_approval"`.

`run_id` is the public request id. `thread_id` is the value you sent, or `null`. `pending_tool_approvals` is present only while the run is waiting. Each item includes `approval_id`, `tool_name`, `summary`, `arguments`, `expires_at`, and `review_url`. `review_url` opens the approval in the dashboard. It is not an email token. `denied_tool_calls` is present only when a tool was denied, with `reason: "policy_deny"`. The response text also includes `[Waiting for approval: …]`.

A streaming invoke puts the same fields on the final `usage` event.

## Continue the run

Send the same `thread_id` with `decided_tool_approvals`:

```json theme={null}
{
  "agent": "YOUR_AGENT_ID",
  "thread_id": "ticket-42",
  "message": "",
  "decided_tool_approvals": [{ "approval_id": "APPROVAL_ID" }]
}
```

If you omit `decided_tool_approvals` and reuse the thread, Fetch Hive loads the approvals from that thread.

## Decide with an API key

```bash theme={null}
curl 'https://api.fetchhive.com/v1/public/workspaces/WORKSPACE_ID/tool_action_approvals/APPROVAL_ID/decide' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{ "decision": "allow_once" }'
```

`decision` is `allow_once` or `deny`. `always_allow` returns `422` with `always_allow_requires_dashboard`. A second decision returns `409`. An expired approval returns `410`. An approval outside the API key's workspace returns `404`.

List pending approvals:

```bash theme={null}
curl 'https://api.fetchhive.com/v1/public/workspaces/WORKSPACE_ID/tool_action_approvals' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

`status` defaults to `pending`. You can filter with `agent_id`, `run_id`, and `request_id`. Pages use `cursor` and return at most 50 rows.

## Webhooks

A webhook-sourced run sends `agent.awaiting_approval` when it pauses. The payload includes `pending_tool_approvals`. After the run continues, `agent.completed` includes `resumed_from_run_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.