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

# Answer an Approval

> Allow or refuse a tool the Chamelio Agent is waiting on, and resume its run.

## Endpoint

```
POST /v2/agent/conversations/{session_id}/approvals
```

Some agent tools need a person to approve them before they run. When that happens, the run stops
and reports itself as **parked**: the `stream=false` response has `status: "parked"` and a
`pending_approval` object. The run makes no further progress until you answer it here, and there is
no other way to resume it.

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `agent:write`

The agent runs as the access token's user and inherits exactly that user's access.

## Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `session_id` | string (UUID) | Yes | The parked conversation |

## Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `stream` | boolean | No | Stream the resumed run as Server-Sent Events. Set `false` to wait for it to finish and get one JSON body. Defaults to `true` |

## Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `source_interaction_id` | string (UUID) | Yes | The `pending_approval.source_interaction_id` from the response that reported the run as parked |
| `decision` | string | Yes | Whether to allow the agent to use the tool it is waiting on. One of `approved` or `rejected` |
| `reason` | string or null | No | Optional explanation shown to the agent |

> [!WARNING]
>
> The agent stopped because a person should decide. If you build this into an integration, show the
> user `pending_approval.tool` and `pending_approval.description` and use their answer - do not
> approve automatically.

## Request Example

```bash cURL theme={null}
curl -X POST "https://platform.chamelio.ai/v2/agent/conversations/3f6c2a8e-1b4d-4e7a-9c21-5d8f0e6b7a90/approvals?stream=false" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "source_interaction_id": "c4a1e7d2-6f38-4b90-8e15-2a7d9b3c0f61",
    "decision": "approved"
  }'
```

```python Python theme={null}
import requests

session_id = "3f6c2a8e-1b4d-4e7a-9c21-5d8f0e6b7a90"
url = f"https://platform.chamelio.ai/v2/agent/conversations/{session_id}/approvals"
headers = {
    "Authorization": "Bearer your_access_token",
    "Content-Type": "application/json"
}

payload = {
    "source_interaction_id": "c4a1e7d2-6f38-4b90-8e15-2a7d9b3c0f61",
    "decision": "approved"
}

response = requests.post(url, params={"stream": "false"}, json=payload, headers=headers, timeout=300)
print(response.json())
```

```javascript JavaScript theme={null}
const sessionId = '3f6c2a8e-1b4d-4e7a-9c21-5d8f0e6b7a90';
const response = await fetch(`https://platform.chamelio.ai/v2/agent/conversations/${sessionId}/approvals?stream=false`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_interaction_id: 'c4a1e7d2-6f38-4b90-8e15-2a7d9b3c0f61',
    decision: 'approved'
  })
});

const data = await response.json();
console.log(data);
```

## Response

The resumed run is returned in the same shape as [Ask the Agent](https://docs.chamelio.ai/api-reference/endpoint/v2/agent/ask.md#response):
a Server-Sent Events stream by default, or a single JSON body with `stream=false`. The resumed run
can park again on another tool - check `status` each time.

### Success Response (`stream=false`)

**Status Code:** `200 OK`

```json theme={null}
{
  "session_id": "3f6c2a8e-1b4d-4e7a-9c21-5d8f0e6b7a90",
  "answer": "Done. I started the Vendor Contract Review workflow for Acme.",
  "status": "completed",
  "pending_approval": null
}
```

See [Response Fields](https://docs.chamelio.ai/api-reference/endpoint/v2/agent/ask.md#response-fields) for every field.

## Error Responses

### 400 Bad Request

Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](https://docs.chamelio.ai/api-reference/oauth-apps.md#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token does not carry the required scope.

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: agent:write"
}
```

### 404 Not Found

Returned when the conversation or the interaction does not exist. Make sure you pass
`pending_approval.source_interaction_id` exactly as returned.

```json theme={null}
{
  "detail": "Not found"
}
```

### 409 Conflict

Returned when the approval was already answered, or a run is active on the conversation. The
`detail` is passed through from the agent service.

### 422 Validation Error

Returned when the request is invalid, for example a `decision` other than `approved` or `rejected`,
or an ID that is not a UUID.

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when the run could not be resumed or failed before producing an answer.

```json theme={null}
{
  "detail": "Failed to answer the approval"
}
```
