Ask the Agent

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:

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

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

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

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

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

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

event: <event_type>
data: <JSON object>

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:

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

Ask

Call this endpoint with your prompt. Keep the returned session_id.

Continue

Send follow-up messages to POST /v2/agent/conversations/{session_id}/messages. The agent keeps the earlier context.

Answer approvals

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

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

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.

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

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

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

Endpoint

Authentication

Query Parameters

Request Body

Request Example

Response

Success Response (`stream=false`)

Response Fields

Pending Approval Object

Streaming Response (default)

Conversation Lifecycle

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

​Endpoint

​Authentication

​Query Parameters

​Request Body

​Request Example

​Response

​Success Response (stream=false)

​Response Fields

​Pending Approval Object

​Streaming Response (default)

​Conversation Lifecycle

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

Endpoint

Authentication

Query Parameters

Request Body

Request Example

Response

Success Response (`stream=false`)

Response Fields

Pending Approval Object

Streaming Response (default)

Conversation Lifecycle

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes