---
title: "Create session"
method: POST
path: "/v2/workspaces/{workspace_id}/sessions"
tags: ["Sessions"]
---

# Create session

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

## Request

- Base URL: `https://api.app.layer.ai/api`
- URL: `https://api.app.layer.ai/api/v2/workspaces/{workspace_id}/sessions`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.app.layer.ai/authorize`, token URL `https://auth.app.layer.ai/oauth/token`)
  - OAuth 2 (client credentials, token URL `https://api.app.layer.ai/api/oauth/token`, scopes: `sessions:write`)

Create an empty session. Names need not be unique: a client that means to resume a session should keep its `session_id` rather than look it up by name.

## Path parameters

- `workspace_id` string, uuid, required: Id of the workspace that owns the resource.

## Headers

- `Idempotency-Key` string

## Request body

- CreateSessionBody
  - `name` string, required: The session's display name.

## Response `201`

Successful Response

- SessionSummary
  - `session_id` string, uuid, required: The session's unique identifier.
  - `name` string, required: The session's display name.
  - `project_id` string, uuid, nullable: The project the session is filed under, if any.
  - `created_at` string, date-time, required: When the session was created.
  - `last_interacted_at` string, date-time, nullable: When anyone last worked in the session, or null if nobody has yet.

## Other responses

- `401`: Unauthenticated — missing or invalid Bearer token.
- `403`: Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.
- `404`: Resource not found.
- `409`: The outcome of the request with this `Idempotency-Key` is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in `Retry-After`.
- `422`: Invalid input parameters, or an `Idempotency-Key` reused for a different request.
- `429`: Rate limited — retry after the number of seconds in `Retry-After`.
- `500`: Internal server error.

## Changes

- **2026-10-20** `326f3bcdabcc`: 7 info
  - added the required property `error_code` to the response with the `401` status
  - added the required property `error_code` to the response with the `403` status
  - added the required property `error_code` to the response with the `404` status
  - added the required property `error_code` to the response with the `409` status
  - …3 more
- **2026-10-11** `2d86d473cda6`: 2 info
  - the endpoint scheme security `serviceAccount` was added to the API
  - the security scope `sessions:write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-10** `9425712a1f7e`: 2 info
  - the endpoint scheme security `bearerAuth` was added to the API
  - the endpoint scheme security `oauth2` was added to the API
- **2026-09-23** `2cd5ca1ff4c0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/layer/apis/layer-rest-api/changes/v2/workspaces/:workspace_id/sessions/post.md)

---

[API](https://skmtc.dev/layer/apis/layer-rest-api.md) · [All operations](https://skmtc.dev/layer/apis/layer-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layer/apis/layer-rest-api/revisions/326f3bcdabcc?raw)