---
title: "Create a ChatKit session"
method: POST
path: "/chatkit/sessions"
---

# Create a ChatKit session

`POST /chatkit/sessions`

## Request

- Base URL: `https://api.openai.com/v1`
- URL: `https://api.openai.com/v1/chatkit/sessions`
- Auth: HTTP bearer

Create a ChatKit session.

## Request body

- CreateChatSessionBody: Parameters for provisioning a new ChatKit session.
  - `workflow` WorkflowParam, required: Workflow reference and overrides applied to the chat session.
    - `id` string, required: Identifier for the workflow invoked by the session.
    - `version` string: Specific workflow version to run. Defaults to the latest deployed version.
    - `state_variables` object: State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object.
    - `tracing` WorkflowTracingParam: Controls diagnostic tracing during the session.
      - `enabled` boolean: Whether tracing is enabled during the session. Defaults to true.
  - `user` string, required: A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.
  - `expires_after` ExpiresAfterParam: Controls when the session expires relative to an anchor timestamp.
    - `anchor` 'created_at', required: Base timestamp used to calculate expiration. Currently fixed to `created_at`.
    - `seconds` integer, required: Number of seconds after the anchor when the session expires.
  - `rate_limits` RateLimitsParam: Controls request rate limits for the session.
    - `max_requests_per_1_minute` integer: Maximum number of requests allowed per minute for the session. Defaults to 10.
  - `chatkit_configuration` ChatkitConfigurationParam: Optional per-session configuration settings for ChatKit behavior.
    - `automatic_thread_titling` AutomaticThreadTitlingParam: Controls whether ChatKit automatically generates thread titles.
      - `enabled` boolean: Enable automatic thread title generation. Defaults to true.
    - `file_upload` FileUploadParam: Controls whether users can upload files.
      - `enabled` boolean: Enable uploads for this session. Defaults to false.
      - `max_file_size` integer: Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.
      - `max_files` integer: Maximum number of files that can be uploaded to the session. Defaults to 10.
    - `history` HistoryParam: Controls how much historical context is retained for the session.
      - `enabled` boolean: Enables chat users to access previous ChatKit threads. Defaults to true.
      - `recent_threads` integer: Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.

## Response `200`

Success

- ChatSessionResource: Represents a ChatKit session and its resolved configuration.
  - `id` string, required: Identifier for the ChatKit session.
  - `object` 'chatkit.session', required: Type discriminator that is always `chatkit.session`.
  - `expires_at` integer, required: Unix timestamp (in seconds) for when the session expires.
  - `client_secret` string, required: Ephemeral client secret that authenticates session requests.
  - `workflow` ChatkitWorkflow, required: Workflow metadata and state returned for the session.
    - `id` string, required: Identifier of the workflow backing the session.
    - `version` string, nullable, required: Specific workflow version used for the session. Defaults to null when using the latest deployment.
    - `state_variables` object, nullable, required: State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
    - `tracing` ChatkitWorkflowTracing, required: Controls diagnostic tracing during the session.
      - `enabled` boolean, required: Indicates whether tracing is enabled.
  - `user` string, required: User identifier associated with the session.
  - `rate_limits` ChatSessionRateLimits, required: Active per-minute request limit for the session.
    - `max_requests_per_1_minute` integer, required: Maximum allowed requests per one-minute window.
  - `max_requests_per_1_minute` integer, required: Convenience copy of the per-minute request limit.
  - `status` 'active' | 'expired' | 'cancelled', required
  - `chatkit_configuration` ChatSessionChatkitConfiguration, required: ChatKit configuration for the session.
    - `automatic_thread_titling` ChatSessionAutomaticThreadTitling, required: Automatic thread title preferences for the session.
      - `enabled` boolean, required: Whether automatic thread titling is enabled.
    - `file_upload` ChatSessionFileUpload, required: Upload permissions and limits applied to the session.
      - `enabled` boolean, required: Indicates if uploads are enabled for the session.
      - `max_file_size` integer, nullable, required: Maximum upload size in megabytes.
      - `max_files` integer, nullable, required: Maximum number of uploads allowed during the session.
    - `history` ChatSessionHistory, required: History retention preferences returned for the session.
      - `enabled` boolean, required: Indicates if chat history is persisted for the session.
      - `recent_threads` integer, nullable, required: Number of prior threads surfaced in history views. Defaults to null when all history is retained.

## Other responses

- `400`: The request is invalid or the required ChatKit beta header is missing or invalid.
- `404`: The requested workflow or workflow version was not found or is not accessible.
- `429`: The request rate limit has been exceeded.

## Changes

- **2026-10-06** `487892d3954e`: 3 info
  - added the optional property `error/misalignment/review_target` to the response with the `400` status
  - added the optional property `error/misalignment/review_target` to the response with the `404` status
  - added the optional property `error/misalignment/review_target` to the response with the `429` status
- **2026-10-05** `7f654af7f94f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/chatkit/sessions/post.md)

---

[API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)