Skip to content
QuantCDN

Chat with AI Agent

POST
/api/v3/organizations/{organisation}/ai/agents/{agentId}/chat
curl --request POST \
  --url https://dashboard.quantcdn.io/api/v3/organizations/example/ai/agents/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "message": "example", "sessionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "userId": "example", "stream": false, "async": false, "system": "example", "longContext": false, "maxToolIterations": 1, "allowedCollections": [ "example" ] }'

Initiates a chat session with a specific AI agent. The agent’s configuration (system prompt, temperature, model, allowed tools) is automatically applied. * * Key Features: * - Session Management: Automatic session creation and state tracking * - Multi-turn Conversations: Full conversation history maintained server-side * - Agent’s system prompt is prepended to conversation * - Only agent’s allowed tools are available * - All tools are auto-executed on cloud (no client confirmation needed) * - Temperature and model from agent config * - Supports sync, streaming, and async modes * * Execution Modes: * - Sync Mode (default): Standard JSON response, waits for completion * - Streaming Mode: Set stream: true for SSE token-by-token responses * - Async Mode: Set async: true for long-running tasks with polling * * Async/Durable Mode (async: true): * - Returns immediately with requestId and pollUrl (HTTP 202) * - Uses AWS Lambda Durable Functions for long-running agent tasks * - All tools are auto-executed on cloud (no waiting_callback state) * - Poll /ai/chat/executions/{requestId} for status * - Ideal for agents with slow tools (image generation, web search, etc.) * * Session Support: * - Omit sessionId to create a new session automatically * - Include sessionId to continue an existing conversation * - Sessions expire after 60 minutes of inactivity * - Sessions work in all modes (sync, streaming, async) * - Use /sessions/{sessionId} to retrieve full conversation history

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organisation
required
string

The organisation ID

agentId
required
string format: uuid

The agent ID

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
message
required

The user’s message to the agent

string
sessionId

Optional session ID to continue a conversation

string format: uuid
userId

Optional user identifier for session isolation

string
stream

Whether to stream the response (SSE)

boolean
async

Enable async/durable execution mode. When true, returns 202 with pollUrl. Use for long-running agent tasks.

boolean
system

Optional additional system prompt (appended to agent’s configured prompt)

string
longContext

Per-request override to force 1M context window routing

boolean
maxToolIterations

Maximum tool auto-execution iterations for this request

integer
>= 1 <= 1000
allowedCollections

Per-request override for vector DB collections the agent can query

Array<string>

Responses

Section titled “Responses”

200

Section titled “200”

Agent response generated successfully (sync mode)

Media typeapplication/json
object
sessionId
string format: uuid
response
object
text
string
stopReason
string
usage
object
inputTokens
integer
outputTokens
integer
totalTokens
integer
costCents

Cost of this inference call in US cents

number format: float
toolResults
Array<object>
object
Examplegenerated
{
  "sessionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "response": {
    "text": "example",
    "stopReason": "example",
    "usage": {
      "inputTokens": 1,
      "outputTokens": 1,
      "totalTokens": 1,
      "costCents": 1
    },
    "toolResults": [
      {}
    ]
  }
}

202

Section titled “202”

Async execution started (when async: true in request)

Media typeapplication/json
object
requestId
required

Unique request identifier for polling

string
agentId
required

The agent processing the request

string format: uuid
agentName

Human-readable agent name

string
sessionId

Session ID (if provided)

string
status
required

Initial status

string
Allowed values: queued
message
string
pollUrl
required

URL to poll for execution status

string
Example
{
  "requestId": "90fe0c53-a41b-4b28-b19e-5e900b3df959",
  "agentName": "Weather Assistant",
  "status": "queued",
  "message": "Agent execution started. Poll the status endpoint for updates.",
  "pollUrl": "/ai/chat/executions/90fe0c53-a41b-4b28-b19e-5e900b3df959"
}

400

Section titled “400”

Invalid request parameters

403

Section titled “403”

Access denied

404

Section titled “404”

Agent not found

500

Section titled “500”

Failed to chat with agent