Answer an Approval

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:

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

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

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"
  }'

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())

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: 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

{
  "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 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.

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "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.

{
  "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.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

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

{
  "detail": "Failed to answer the approval"
}

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

Endpoint

Authentication

Path Parameters

Query Parameters

Request Body

Request Example

Response

Success Response (`stream=false`)

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Request Body

​Request Example

​Response

​Success Response (stream=false)

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

Endpoint

Authentication

Path Parameters

Query Parameters

Request Body

Request Example

Response

Success Response (`stream=false`)

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error