---
title: "Create a new app session"
method: POST
path: "/app-sessions"
tags: ["apps"]
---

# Create a new app session

`POST /app-sessions`

## Request

- Base URL: `https://{tenant_name}.benchling.com/api/v2`
- URL: `https://{tenant_name}.benchling.com/api/v2/app-sessions`
- Auth: HTTP bearer

Create a new app session. Sessions cannot be archived once created.

## Request body

- AppSessionCreate
  - `appId` string, required
  - `messages` AppSessionMessageCreate[]: An array of `SessionMessage` describing the current session state.
    - `content` string, required: A message string, to be rendered as plain text with Benchling chips. References to Benchling items (up to 10 per msg) will be rendered as chips in the Benchling UX. A valid reference is a Benchling API id, prefixed with "id:" and contained by braces. For example: "{id:ent_a0SApq3}."
    - `style` 'ERROR' | 'INFO' | 'NONE' | 'SUCCESS' | 'WARNING'
  - `name` string, required: The name of the session. Length must be between 3-100 chars. Value is required and immutable once set.
  - `timeoutSeconds` integer, required: Timeout in seconds, a value between 1 second and 30 days. Once set, it can only be increased, not decreased.

## Response `201`

Created

- AppSession
  - `app` AppSessionApp
    - `id` string: The id of the Benchling app.
  - `createdAt` string, date-time
  - `id` string
  - `messages` AppSessionMessage[], nullable: An array of `SessionMessage` describing the current session state.
    - `content` string, required: A message string, to be rendered as plain text with Benchling chips. References to Benchling items (up to 10 per msg) will be rendered as chips in the Benchling UX. A valid reference is a Benchling API id, prefixed with "id:" and contained by braces. For example: "{id:ent_a0SApq3}."
    - `style` 'ERROR' | 'INFO' | 'NONE' | 'SUCCESS' | 'WARNING'
  - `modifiedAt` string, date-time
  - `name` string: A brief description of the app's actions for users. Length must be between 3-100 chars. It becomes immutable once a value is set.
  - `status` 'COMPLETED_WITH_WARNINGS' | 'FAILED' | 'RUNNING' | 'SUCCEEDED' | 'TIMEOUT': All possible values of a Session's status, including system-updated and user-updated values.
  - `timeoutSeconds` integer: Timeout in seconds, a value between 1 second and 30 days. Once set, it can only be increased, not decreased.

## Other responses

- `400`: Bad Request
- `403`: Forbidden

---

[API](https://skmtc.dev/benchling/apis/benchling-api-2.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api-2/revisions/01d2fa8523cd?raw)