chat

Create Session

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

Two 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).

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

Returns: CreateSessionResponse: Details of the resulting session.

post/api/chat/sessions

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

Response

Successful Response

idstring required

created_atstring required

user_idstring nullable required

expert_idstring nullable

Changes

Changed in 9 of the 165 revisions of this API.422

Sep 17, 2026f70abc24c4041See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Sep 12, 202695db58ee813813See the full diff
- ●
  added the new microsoft_365_copilot enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the new microsoft_365_copilot enum value to the request property /
  request-property-enum-value-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  the response's property default value changed from {"dry_run":false,"llm_auth_provider":"platform","kind":"normal"} to {"dry_run":false,"llm_auth_provider":"platform","llm_provider_session_ids":{},"kind":"normal"} for the status
  response-property-default-value-changed
Aug 23, 20269f56862bbc8a5See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Aug 16, 20267164d7f366801See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
Aug 12, 2026316dc59847545See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  the response's property default value changed from {"dry_run":false,"kind":"normal"} to {"dry_run":false,"llm_auth_provider":"platform","kind":"normal"} for the status
  response-property-default-value-changed
Jul 29, 20263840642ede612See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jun 11, 2026ab66703bd0043See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  the response's property default value changed from {"dry_run":false} to {"dry_run":false,"kind":"normal"} for the status
  response-property-default-value-changed
May 20, 20264954735722151See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Apr 30, 20268c84efcb3afb31See the full diff
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ○
  the response's property default value changed from {"dry_run":false,"kind":"normal"} to {"dry_run":false} for the status
  response-property-default-value-changed
This revision also has 96 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history