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.

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

Changed in 5 of the 30 revisions of this API.210

Sep 24, 20268beaac28e1951See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Sep 12, 2026604ea84d0ff726See the full diff
- ●
  the // request property's maxLength was set to 200
  request-property-max-length-set
- ●
  the /// request property's maxLength was set to 200
  request-property-max-length-set
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
Sep 2, 2026d0e2bf840dfc1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Aug 18, 2026fff2cd2dfbac1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Aug 13, 202618539ae8bf0a1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history