SIsignificant-gravitas
v2
chat
chat

Create Session

Changed on

Create (or get-or-create) a chat session.

Four modes, selected by the request body:

  • Default: create a fresh session for the user. dry_run=True forces run_capability and run_agent calls to use dry-run simulation.
  • Builder-bound: when builder_graph_id is set, get-or-create keyed on (user_id, builder_graph_id). Returns the existing session for that graph or creates one locked to it. Graph ownership is validated inside :func:get_or_create_builder_session; raises 404 on unauthorized access. Write-side scope is enforced per-tool (edit_agent / run_agent reject any agent_id other than the bound graph) and a small blacklist hides tools that conflict with the panel's scope (see :data:BUILDER_BLOCKED_TOOLS).
  • Expert kickoff: atomically create or adopt the canonical first session for (user_id, expert_id).
  • Client-named: when session_id is set, a plain or expert create adopts the session that id already names, so a retry after a lost response never leaves an empty session behind.

Args: user_id: The authenticated user ID parsed from the JWT (required). request: Optional request body with dry_run, builder_graph_id, expert_id, expert_kickoff and/or session_id.

Returns: CreateSessionResponse: Details of the resulting session.

post/api/chat/sessions

Request

  • The document declares no server URL.
  • Auth
    HTTP bearer

Request body

dry_runboolean
builder_graph_idstring nullable
llm_auth_provider'platform' | 'codex' | 'microsoft_365_copilot'
llm_credential_idstring nullable
expert_idstring nullable
expert_kickoffboolean
session_idstring uuid nullable
autopilot_mode'ask_first' | 'auto' | 'unsupervised' nullable

Response

Successful Response

idstring required
created_atstring required
user_idstring nullable required
expert_idstring nullable

Changes