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

# Approvals

> Actions that wait for a person to say yes.

Every tool call goes through one gate. The gate decides to allow it, ask a person or deny it. A call that needs a yes does not run. It waits as an approval until a person answers.

This holds for agents, for workflows and for the MCP server. A tool call from an assistant over [MCP](https://docs.impellabs.tech/connect/apps.md) acts as your Chief of Staff and follows the same rules.

## What waits by default

Each tool has a risk class: `read`, `write`, `send`, `money` or `live`. `live` is the class for publishing or pausing an agent.

| Class | Default |
| - | - |
| `read` | Runs. |
| `write` | Waits for a yes. |
| `send` | Waits for a yes. |
| `money` | Waits for a yes. |
| `live` | The person says yes on a card first. |

Some tools have their own default. For example, a published agent answers its customers by itself, but a document it sends waits for a yes. A workspace can add its own rules for a tool, a risk class, an agent kind or one agent. A rule says `allow`, `ask` or `deny`. A rule for a department or a person can only make a call stricter.

## What you see

When a call waits, the MCP result says so and does not run the action:

```json theme={null}
{
  "status": "waiting_for_approval",
  "approval_id": "APPROVAL_ID",
  "note": "This action did not run. It waits for a person's yes ..."
}
```

An approval has a `status`: `waiting`, `approved`, `changed`, `declined` or `expired`. It also has `tool`, `risk`, `title`, `summary`, `terms`, `agent_id`, `requester`, `approver_id` and times.

## Answer through the API

List what waits for you:

```bash theme={null}
curl "https://api.impellabs.tech/api/v1/approvals?state=pending" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

You can filter with `state` (`pending` or `answered`), `tool`, `agent`, `risk` and `escalated`. You see approvals where you are the approver, where they were escalated to you, or where you answered.

Answer with one of three calls:

| Call | Meaning |
| - | - |
| `POST /api/v1/approvals/{approval_id}/approve` | Yes. Run it. |
| `POST /api/v1/approvals/{approval_id}/change` | Do not run it. Send `{"note": "..."}` with what to change. The agent asks again. |
| `POST /api/v1/approvals/{approval_id}/decline` | No. |

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/approvals/APPROVAL_ID/approve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"terms": "TERMS_FROM_THE_APPROVAL"}'
```

`terms` is a hash of the tool and its arguments. If you send it, it must match the card. If the action changed since, the answer is refused and the action needs a new approval. Only the approver, or the person it was escalated to, can answer.

## Timing

A waiting approval is reminded after 30 minutes. After 2 hours it is escalated: the approver's manager, or an admin, can answer too. A card ends after 24 hours as `expired`. An approval step in a workflow ends with its own wait.

## Allow it from now on

When you approve, send `"always": true` to make a standing permission. It lets that tool through without asking, within limits you set: `per_day` and `max_items`, each a whole number above 0. A permission is for you, or for the team when an owner or an admin gives it. Manage them at `/api/v1/approvals/permissions`. An owner or an admin can make a tool always ask with `PUT /api/v1/approvals/always-ask` and `{"tool": "...", "on": true}`. This turns its standing permissions off.

Each member can also ask to approve every message their agents send, with `PUT /api/v1/approvals/preferences` and `{"ask_before_sending": true}`. It is off by default.

## Rule changes

A change to a rule is also an approval. A person who cannot change a rule asks for the change, and the request waits for their manager and the owner.


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