Sign in
v2
chat
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_block 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'
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 7 of the 92 revisions of this API.318

  • 9f56862bbc8a5See the full diff
    • ○

      added the optional property metadata/delegated_by_expert_id to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property metadata/delegated_by_session_id to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property metadata/handed_off_from_expert_id to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property metadata/origin to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property metadata/pending_question to the response with the 200 status

      response-optional-property-added

  • 7164d7f366801See the full diff
    • ○

      added the new optional request property anyOf[subschema #1: CreateSessionRequest]/expert_kickoff

      new-optional-request-property

  • 316dc59847545See the full diff
    • ○

      added the new optional request property anyOf[subschema #1: CreateSessionRequest]/llm_auth_provider

      new-optional-request-property

    • ○

      added the new optional request property anyOf[subschema #1: CreateSessionRequest]/llm_credential_id

      new-optional-request-property

    • ○

      added the optional property metadata/llm_auth_provider to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property metadata/llm_credential_id to the response with the 200 status

      response-optional-property-added

    • ○

      the metadata 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 200

      response-property-default-value-changed

  • 3840642ede612See the full diff
    • ○

      added the new optional request property anyOf[subschema #1: CreateSessionRequest]/expert_id

      new-optional-request-property

    • ○

      added the optional property expert_id to the response with the 200 status

      response-optional-property-added

  • ab66703bd0043See the full diff
    • ○

      added the optional property metadata/dream_pass_id to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property metadata/kind to the response with the 200 status

      response-optional-property-added

    • ○

      the metadata response's property default value changed from {"dry_run":false} to {"dry_run":false,"kind":"normal"} for the status 200

      response-property-default-value-changed

  • 4954735722151See the full diff
    • ○

      added the optional property metadata/source_platform to the response with the 200 status

      response-optional-property-added

  • 8c84efcb3afb31See the full diff
    • ●

      removed the optional property metadata/dream_pass_id from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property metadata/kind from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property metadata/source_platform from the response with the 200 status

      response-optional-property-removed

    • ○

      the metadata response's property default value changed from {"dry_run":false,"kind":"normal"} to {"dry_run":false} for the status 200

      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