> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/rest-api/scaleai-rest-api/chat.md).

# Chat

## Chat Stream Endpoint

> Streaming conversational Q\&A chat endpoint.\
> \
> This endpoint provides interactive, tool-calling chat responses where the agent:\
> \- Dynamically selects tools based on user questions\
> \- Answers specific questions about portfolio data\
> \- Uses session caching to avoid redundant API calls\
> \- Supports multi-turn conversations\
> \
> Chunk Types:\
> \- text: Response text chunks\
> \- source: Anthropic web citation (id, title, url). Absent when globe is off or the provider sent no cites.\
> \- tool\_use: Agent is calling a tool\
> \- tool\_result: Result from tool execution\
> \- done: Conversation complete (includes conversation\_history)\
> \- usage: Token usage statistics

```json
{"openapi":"3.1.0","info":{"title":"ScaleAI r16 API","version":"2.0.0"},"servers":[{"url":"https://agent-backend.r16.app"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ChatRequest":{"properties":{"message":{"type":"string","title":"Message","description":"User's message"},"conversation_history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Conversation History","description":"Previous conversation messages"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"LLM model to use","default":"claude-opus-4-5-20251101"},"jwt_token":{"type":"string","minLength":1,"description":"Downstream user JWT, separate from the service bearer token."},"strategy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strategy Id","description":"Strategy/sub-control-centre ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID for admin access"},"mentions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Mentions","description":"Chips the broker attached in the composer, each {kind, id, label}. kind is one of client | strategy | team | agent | artefact | doc | file | task | note | meeting | calendar | property | ai-review. Rendered into the system prompt as the scope of the turn so the model uses the ids with tools instead of searching by name."},"environment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Environment","description":"Environment: 'local', 'dev', or 'prod'","default":"dev"},"context_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Type","description":"Chat context type: 'broker_brain', 'client_assistant', 'client_review', 'support', 'simulator'. Picks the AgentSpec and persona overlay."},"web_access":{"type":"boolean","title":"Web Access","description":"When true, attach Anthropic web_search for this turn if AgentSpec.web_access allows it. Globe off / omitted means no web tool.","default":false},"chat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chat Id","description":"scale-backend ai_chat.id for this thread, when the caller has one. Stamped as sourceRef on memories the post-turn extractor suggests; omitted means no sourceRef."},"tool_call":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Call","description":"A tool the browser asks to run before the model turn: {name, input}. Today only the write gate's approval card posts {name: 'confirm_writes', input: {set_key, item_keys?}}. Runs first, streams as tool_status/tool_result, and its report is folded into the message as context for the model."},"timezone":{"type":"string","title":"Timezone","description":"The broker's IANA timezone, read from the browser with Intl.DateTimeFormat().resolvedOptions().timeZone. Every date the prompt states and every calendar write the turn drafts is stamped with it.","default":"Australia/Sydney"},"attachments":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Attachments","description":"Files the broker attached in the composer for this turn, each {filename, media_type, data} with data as base64. Extracted to text and read for this message only — nothing is stored or indexed, so a later turn cannot see it unless the broker re-attaches it. Supports PDF, plain text, Word (.docx) and Excel (.xlsx)."}},"type":"object","required":["message","jwt_token"],"title":"ChatRequest","description":"Request model for chat endpoints."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/chat/stream":{"post":{"tags":["Chat"],"summary":"Chat Stream Endpoint","description":"Streaming conversational Q&A chat endpoint.\n\nThis endpoint provides interactive, tool-calling chat responses where the agent:\n- Dynamically selects tools based on user questions\n- Answers specific questions about portfolio data\n- Uses session caching to avoid redundant API calls\n- Supports multi-turn conversations\n\nChunk Types:\n- text: Response text chunks\n- source: Anthropic web citation (id, title, url). Absent when globe is off or the provider sent no cites.\n- tool_use: Agent is calling a tool\n- tool_result: Result from tool execution\n- done: Conversation complete (includes conversation_history)\n- usage: Token usage statistics","operationId":"chat_stream_endpoint_chat_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/event-stream":{"schema":{"type":"string","description":"SSE chunk. See the operation description for chunk types."}}}},"401":{"description":"Missing or invalid service bearer token, or missing downstream jwt_token in the request body.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Handler failed","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"503":{"description":"AI features temporarily disabled","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}}}}}}}
```

## Chat Endpoint

> Non-streaming chat endpoint.\
> \
> Returns the complete response in a single JSON object.

```json
{"openapi":"3.1.0","info":{"title":"ScaleAI r16 API","version":"2.0.0"},"servers":[{"url":"https://agent-backend.r16.app"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ChatRequest":{"properties":{"message":{"type":"string","title":"Message","description":"User's message"},"conversation_history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Conversation History","description":"Previous conversation messages"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"LLM model to use","default":"claude-opus-4-5-20251101"},"jwt_token":{"type":"string","minLength":1,"description":"Downstream user JWT, separate from the service bearer token."},"strategy_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strategy Id","description":"Strategy/sub-control-centre ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID for admin access"},"mentions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Mentions","description":"Chips the broker attached in the composer, each {kind, id, label}. kind is one of client | strategy | team | agent | artefact | doc | file | task | note | meeting | calendar | property | ai-review. Rendered into the system prompt as the scope of the turn so the model uses the ids with tools instead of searching by name."},"environment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Environment","description":"Environment: 'local', 'dev', or 'prod'","default":"dev"},"context_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Type","description":"Chat context type: 'broker_brain', 'client_assistant', 'client_review', 'support', 'simulator'. Picks the AgentSpec and persona overlay."},"web_access":{"type":"boolean","title":"Web Access","description":"When true, attach Anthropic web_search for this turn if AgentSpec.web_access allows it. Globe off / omitted means no web tool.","default":false},"chat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chat Id","description":"scale-backend ai_chat.id for this thread, when the caller has one. Stamped as sourceRef on memories the post-turn extractor suggests; omitted means no sourceRef."},"tool_call":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Call","description":"A tool the browser asks to run before the model turn: {name, input}. Today only the write gate's approval card posts {name: 'confirm_writes', input: {set_key, item_keys?}}. Runs first, streams as tool_status/tool_result, and its report is folded into the message as context for the model."},"timezone":{"type":"string","title":"Timezone","description":"The broker's IANA timezone, read from the browser with Intl.DateTimeFormat().resolvedOptions().timeZone. Every date the prompt states and every calendar write the turn drafts is stamped with it.","default":"Australia/Sydney"},"attachments":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Attachments","description":"Files the broker attached in the composer for this turn, each {filename, media_type, data} with data as base64. Extracted to text and read for this message only — nothing is stored or indexed, so a later turn cannot see it unless the broker re-attaches it. Supports PDF, plain text, Word (.docx) and Excel (.xlsx)."}},"type":"object","required":["message","jwt_token"],"title":"ChatRequest","description":"Request model for chat endpoints."},"ChatResponse":{"properties":{"response":{"type":"string","title":"Response","description":"AI response text"},"conversation_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","description":"Updated conversation history"},"usage":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Usage","description":"Token usage statistics"}},"type":"object","required":["response","conversation_history"],"title":"ChatResponse","description":"Response model for non-streaming chat."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/chat/":{"post":{"tags":["Chat"],"summary":"Chat Endpoint","description":"Non-streaming chat endpoint.\n\nReturns the complete response in a single JSON object.","operationId":"chat_endpoint_chat__post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"401":{"description":"Missing or invalid service bearer token, or missing downstream jwt_token in the request body.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Handler failed","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}},"503":{"description":"AI features temporarily disabled","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/rest-api/scaleai-rest-api/chat.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.