---
title: "Get Or Create Session"
method: POST
path: "/v3/workspaces/{workspace_id}/sessions"
tags: ["sessions"]
---

# Get Or Create Session

`POST /v3/workspaces/{workspace_id}/sessions`

Get a Session by ID or create a new Session with the given ID.

If Session ID is provided as a parameter, it verifies the Session is in the Workspace.
Otherwise, it uses the session_id from the JWT for verification.

## Path parameters

- `workspace_id` string, required

## Request body

- SessionCreate
  - `id` string, required
  - `metadata` object, nullable
  - `peers` object, nullable
  - `configuration` SessionConfiguration — The set of options that can be in a session DB-level configuration dictionary. All fields are optional. Session-level configuration overrides workspace-level configuration, which overrides global configuration.
    - `reasoning` ReasoningConfiguration
      - `enabled` boolean, nullable — Whether to enable reasoning functionality.
      - `custom_instructions` string, nullable — Optional custom instructions for the reasoning system on this workspace/session/message. Rejected if they exceed the deriver custom-instruction token cap.
    - `peer_card` PeerCardConfiguration
      - `use` boolean, nullable — Whether to use peer card related to this peer during reasoning process.
      - `create` boolean, nullable — Whether to generate peer card based on content.
    - `summary` SummaryConfiguration
      - `enabled` boolean, nullable — Whether to enable summary functionality.
      - `messages_per_short_summary` integer, nullable — Number of messages per short summary. Must be positive, greater than or equal to 10, and less than messages_per_long_summary.
      - `messages_per_long_summary` integer, nullable — Number of messages per long summary. Must be positive, greater than or equal to 20, and greater than messages_per_short_summary.
    - `dream` DreamConfiguration
      - `enabled` boolean, nullable — Whether to enable dream functionality. If reasoning is disabled, dreams will also be disabled and this setting will be ignored.
  - `scopes` string[], nullable — Optional list of (unprefixed) scope names to add this session to. Each scope is created if it does not exist yet. If the session already has messages, its existing documents are backfilled into the scope asynchronously.

## Response `200`

Successful Response

- Session
  - `id` string, required
  - `is_active` boolean, required
  - `workspace_id` string, required
  - `metadata` object
  - `configuration` object
  - `created_at` string, date-time, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-27** (v3) `63b701d883c9` — 1 info
  - added the new optional request property `scopes`
- **2026-05-21** (v3) `fb8bc7682a0f` — 1 info
  - the `id` request property's maxLength was increased from `100` to `512`
- **2026-02-26** (v3) `0730be052dc9` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status

[Change history](https://skmtc.dev/plastic-labs/apis/honcho-api/changes/v3/workspaces/:workspace_id/sessions/post.md)

---

[API](https://skmtc.dev/plastic-labs/apis/honcho-api.md) · [All operations](https://skmtc.dev/plastic-labs/apis/honcho-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plastic-labs/honcho-api/revisions/63b701d883c9/schema)