---
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`` and/or
        ``builder_graph_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. Extra/unknown fields are rejected (422) to prevent silent mis-use.
  - `dry_run` boolean
  - `builder_graph_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

## Other responses

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

## Changes

- **2026-04-30** `8c84efcb3afb` — 3 warning, 1 info
  - removed the optional property `metadata/dream_pass_id` from the response with the `200` status
  - removed the optional property `metadata/kind` from the response with the `200` status
  - removed the optional property `metadata/source_platform` from the response with the `200` status
  - the `metadata` response's property default value changed from `{"dry_run":false,"kind":"normal"}` to `{"dry_run":false}` for the status `200`

[Change history](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/changes/api/chat/sessions/post.md)

---

[API](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/revisions/72eaad2d41b3?raw)