> ## 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.
</Warning>

## Request Example

<CodeGroup>
  ```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);
  ```
</CodeGroup>

## Response

The resumed run is returned in the same shape as [Ask the Agent](/api-reference/endpoint/v2/agent/ask#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](/api-reference/endpoint/v2/agent/ask#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](/api-reference/oauth-apps#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"
}
```