---
title: "Create New Session"
method: POST
path: "/sessions"
tags: ["Sessions"]
---

# Create New Session

`POST /sessions`

Create a new empty session with optional configuration. Useful for pre-creating sessions with specific session_state, metadata, or other properties before running any agent/team/workflow interactions. The session can later be used by providing its session_id in run requests.

## Query parameters

- `type` 'agent' | 'team' | 'workflow'
- `db_id` string, nullable — Database ID to create session in

## Request body

- CreateSessionRequest
  - `session_id` string, nullable — Optional session ID (generated if not provided)
  - `session_name` string, nullable — Name for the session
  - `session_state` object, nullable — Initial session state
  - `metadata` object, nullable — Additional metadata
  - `user_id` string, nullable — User ID associated with the session
  - `agent_id` string, nullable — Agent ID if this is an agent session
  - `team_id` string, nullable — Team ID if this is a team session
  - `workflow_id` string, nullable — Workflow ID if this is a workflow session

## Response `201`

Session created successfully

- union
  - AgentSessionDetailSchema
    - `user_id` string, nullable — User ID associated with the session
    - `agent_session_id` string, required — Unique agent session identifier
    - `session_id` string, required — Session identifier
    - `session_name` string, required — Human-readable session name
    - `session_summary` object, nullable — Summary of session interactions
    - `session_state` object, nullable — Current state of the session
    - `agent_id` string, nullable — Agent ID used in this session
    - `total_tokens` integer, nullable — Total tokens used in this session
    - `agent_data` object, nullable — Agent-specific data
    - `metrics` object, nullable — Session metrics
    - `metadata` object, nullable — Additional metadata
    - `chat_history` object[], nullable — Complete chat history
    - `created_at` string, date-time, nullable — Session creation timestamp
    - `updated_at` string, date-time, nullable — Last update timestamp
  - TeamSessionDetailSchema
    - `session_id` string, required — Unique session identifier
    - `session_name` string, required — Human-readable session name
    - `user_id` string, nullable — User ID associated with the session
    - `team_id` string, nullable — Team ID used in this session
    - `session_summary` object, nullable — Summary of team interactions
    - `session_state` object, nullable — Current state of the session
    - `metrics` object, nullable — Session metrics
    - `team_data` object, nullable — Team-specific data
    - `metadata` object, nullable — Additional metadata
    - `chat_history` object[], nullable — Complete chat history
    - `created_at` string, date-time, nullable — Session creation timestamp
    - `updated_at` string, date-time, nullable — Last update timestamp
    - `total_tokens` integer, nullable — Total tokens used in this session
  - WorkflowSessionDetailSchema
    - `user_id` string, nullable — User ID associated with the session
    - `workflow_id` string, nullable — Workflow ID used in this session
    - `workflow_name` string, nullable — Name of the workflow
    - `session_id` string, required — Unique session identifier
    - `session_name` string, required — Human-readable session name
    - `session_data` object, nullable — Complete session data
    - `session_state` object, nullable — Current workflow state
    - `workflow_data` object, nullable — Workflow-specific data
    - `metadata` object, nullable — Additional metadata
    - `created_at` string, date-time, nullable — Session creation timestamp
    - `updated_at` string, date-time, nullable — Last update timestamp

## Other responses

- `400` — Invalid request parameters
- `401` — Unauthorized
- `404` — Not Found
- `422` — Validation error
- `500` — Failed to create session

---

[API](https://skmtc.net/agno/apis/agno-api-reference.md) · [All operations](https://skmtc.net/agno/apis/agno-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agno/agno-api-reference/versions/5f6149d395d0/schema)