> ## 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.
# Ask the Agent
> Start a new conversation with the Chamelio agent and get its answer as a stream or a single JSON body.
## Endpoint
```
POST /v2/agent/conversations
```
Use the agent for questions the structured endpoints cannot answer on their own: questions that span
several documents, need judgement, or need work done in steps. The agent reasons over your
organization's workflows, tasks, and documents, and may run its own tools to answer.
## 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. It inherits exactly that user's access to workflows,
tasks, and documents, and cannot see more than they can.
## Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `stream` | boolean | No | Stream the run as Server-Sent Events. Set `false` to wait for the run to finish and get one JSON body. Defaults to `true` |
## Request Body
| Field | Type | Required | Description |
| --------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `prompt` | string | Yes | The question or task for the agent, in plain language. Must not be empty |
| `use_web` | boolean | No | Allow the agent to search the public internet as well as your organization's own documents. Defaults to `false` |
## Request Example
```bash cURL theme={null}
curl -X POST "https://platform.chamelio.ai/v2/agent/conversations?stream=false" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Which of our active MSAs renew automatically in the next 90 days?"
}'
```
```python Python theme={null}
import requests
url = "https://platform.chamelio.ai/v2/agent/conversations"
headers = {
"Authorization": "Bearer your_access_token",
"Content-Type": "application/json"
}
payload = {
"prompt": "Which of our active MSAs renew automatically in the next 90 days?"
}
# Agent runs often take a minute or more - allow a generous timeout
response = requests.post(url, params={"stream": "false"}, json=payload, headers=headers, timeout=300)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch('https://platform.chamelio.ai/v2/agent/conversations?stream=false', {
method: 'POST',
headers: {
'Authorization': 'Bearer your_access_token',
'Content-Type': 'application/json'
},
body: JSON.stringify({
prompt: 'Which of our active MSAs renew automatically in the next 90 days?'
})
});
const data = await response.json();
console.log(data);
```
## Response
### Success Response (`stream=false`)
**Status Code:** `200 OK`
```json theme={null}
{
"session_id": "3f6c2a8e-1b4d-4e7a-9c21-5d8f0e6b7a90",
"answer": "Two active MSAs renew automatically in the next 90 days: ...",
"status": "completed",
"pending_approval": null
}
```
### Response Fields
| Field | Type | Description |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id` | string (UUID) or null | The conversation. Pass it to [Continue a Conversation](/api-reference/endpoint/v2/agent/follow-up) to keep talking |
| `answer` | string | The agent's response. Defaults to `""` |
| `status` | string | How the run ended. `completed` is the whole answer; `parked` means the run needs an approval to continue; `interrupted` means a person stopped it |
| `pending_approval` | object or null | Set only when `status` is `parked`. See [Pending Approval Object](#pending-approval-object) |
Check `status` before treating `answer` as the whole answer. A `parked` or `interrupted` run stopped
rather than finished, and `answer` holds only what it produced before stopping - for an interrupted
run, often nothing at all.
### Pending Approval Object
| Field | Type | Description |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `source_interaction_id` | string (UUID) | Pass back to [Answer an Approval](/api-reference/endpoint/v2/agent/approvals) to resume the run |
| `tool` | string | The agent tool awaiting approval (`"unknown"` if the agent did not name it) |
| `description` | string or null | What the agent intends to do, if it said |
### Streaming Response (default)
With `stream=true` (the default), the response is `text/event-stream`. Each frame has the form:
```text theme={null}
event:
data:
```
A typical run sends a `session_id` event first, then one or more `value` events carrying the
agent's output, then `end`. Every `data` object carries its own `event_type`. Abridged example:
```text theme={null}
event: session_id
data: {"event_type": "session_id", "session_id": "3f6c2a8e-1b4d-4e7a-9c21-5d8f0e6b7a90"}
event: value
data: {"event_type": "value", "interaction_id": "8b1d...", "component": {"component_type": "raw_text", "content": "Two active MSAs renew automatically...", ...}, ...}
event: end
data: {"event_type": "end", ...}
```
| Event | Meaning |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id` | The conversation ID. Save it to continue the conversation |
| `value` | A piece of agent output. The text answer is in `component.content` for components of type `raw_text` or `raw_text_with_refs`. A component with `requires_approval` set means the run is parked (see below) |
| `end` | The run finished |
| `interrupted_by_user` | A person stopped the run |
| `error` | The run failed. If the failure happens after streaming has started, it arrives as a final `error` frame: `{"event_type": "error", "detail": "The agent run ended unexpectedly"}` |
Event payloads are passed through from the agent service as-is and are **not** a stable contract.
Other event types (for example `heartbeat` or `loading`) also appear and should be ignored. For
scripts and integrations, prefer `stream=false` and the documented JSON body.
## Conversation Lifecycle
Call this endpoint with your `prompt`. Keep the returned `session_id`.
Send follow-up messages to [`POST /v2/agent/conversations/{session_id}/messages`](/api-reference/endpoint/v2/agent/follow-up). The agent keeps the earlier context.
If a run comes back with `status: "parked"`, it is waiting for a person to allow or refuse a tool. Answer it with [`POST /v2/agent/conversations/{session_id}/approvals`](/api-reference/endpoint/v2/agent/approvals) - there is no other way to resume the run.
## 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"
}
```
### 422 Validation Error
Returned when the request body is invalid, for example an empty `prompt`.
### 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 agent run could not be started or failed before producing an answer. With
`stream=false`, a run that fails partway returns this error and any partial answer is discarded.
```json theme={null}
{
"detail": "Failed to ask the agent"
}
```
## Notes
Agent runs routinely take a minute or more. Set a generous client timeout. The connection cannot be
rejoined once it closes: if your client disconnects or times out, the answer is lost even though the
run may continue on the server.
For a question a structured endpoint can answer directly - such as listing tasks or reading one
document - call that endpoint instead. It is much faster than the agent.