---
title: "Create Session"
method: POST
path: "/api/chat/sessions"
tags: ["v2", "chat", "chat"]
---

# Create Session

`POST /api/chat/sessions`

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

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.

## Request body

- CreateSessionRequest — Request model for creating (or get-or-creating) a chat session. Two modes, selected by the body: - Default: create a fresh session. ``dry_run`` is a **top-level** field — do not nest it inside ``metadata``. - Builder-bound: when ``builder_graph_id`` is set, the endpoint switches to **get-or-create** keyed on ``(user_id, builder_graph_id)``. The builder panel calls this on mount so the chat persists across refreshes. Graph ownership is validated inside :func:`get_or_create_builder_session`. 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 (``create_agent`` / ``customize_agent`` / ``get_agent_building_guide`` — see :data:`BUILDER_BLOCKED_TOOLS`). Read-side lookups (``find_block``, ``find_agent``, ``search_docs``, …) stay open. ``expert_id`` scopes the session to a hired expert. It must reference an expert owned by the caller that is neither a template nor archived, otherwise the request is rejected with 404. It is mutually exclusive with ``builder_graph_id`` (422) — builder-bound sessions are never expert-scoped. Extra/unknown fields are rejected (422) to prevent silent mis-use.
  - `dry_run` boolean
  - `builder_graph_id` string, nullable
  - `expert_id` string, nullable

## Response `200`

Successful Response

- CreateSessionResponse — Response model containing information on a newly created chat session.
  - `id` string, required
  - `created_at` string, required
  - `user_id` string, nullable, required
  - `metadata` ChatSessionMetadata — Typed metadata stored in the ``metadata`` JSON column of ChatSession. Add new session-level flags here instead of adding DB columns — no migration required for new fields as long as a default is provided.
    - `dry_run` boolean
    - `builder_graph_id` string, nullable
    - `source_platform` string, nullable
    - `kind` string
    - `dream_pass_id` string, nullable
  - `expert_id` string, nullable

## Other responses

- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/significant-gravitas/autogpt-agent-server/versions/382041c7ecb2/schema)