Sign in
chat

Chat Main Agent

Receives and processes a streaming chat request via the AgentService.

This endpoint streams the agent's response in real-time using Server-Sent Events.

Args: request: The chat request data containing message and project_id (pre-validated). agent_service: The AgentService instance (dependency).

Returns: StreamingResponse with Server-Sent Events containing streaming chat data.

Raises: HTTPException: 400 for validation errors. HTTPException: 404 if project not found or user doesn't own it. HTTPException: 500 for unexpected errors.

post/api/v1/chat/stream

Request body

messagestring required
message_idstring nullable

Client-minted identity for this message (UUID string). The same value rides the optimistic bubble, the stream echo, and the persisted history metadata, so every surface dedupes by one key. Server mints one when absent or malformed.

project_idstring uuid required
current_focused_layer_idstring uuid nullable
action_type'new_enrichment' | 'new_layer' | 'analyze_row' | 'invoke_skill'

Enum for different action types in the system.

action_subtypestring nullable

Optional preset identifier that disambiguates actions sharing an action_type. For detail-panel presets, matches the client-side noteSource (e.g. 'environment', 'zoning', 'summary').

hidden_contextobject nullable
current_view_idstring nullable
iterate_over_rowsboolean
selected_modelstring nullable

Model-picker selection for this chat (a curated picker key, see GET /chat/models). Persisted on the chat; honored only when the workspace's model-picker feature toggle is on.

selected_thinking'auto' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

Provider-native thinking choices exposed by the main-agent picker.

continue_turnboolean

Continue a terminally-failed turn from its persisted partial without a new prompt. The FE sends an empty message and the endpoint runs a promptless turn on the persisted history (the same no-user-bubble shape as a tool approval, minus the approval payload) so the agent resumes where it left off.

attachment_idstring uuid nullable

A document previously uploaded to this project's chat via POST /chat/{project_id}/attachment. The agent receives it as a native document alongside message; the turn's persisted history keeps only a reference, so a later turn can read the same document without re-uploading it.

Example request

{
  "project_id": "00000000-0000-0000-0000-000000000001",
  "current_focused_layer_id": "00000000-0000-0000-0000-000000000000"
}

Response

Successful Response

{"stackTrail":"paths:/api/v1/chat/stream:post:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}

Changes