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

# Create a ChatKit session.

`POST /chatkit/sessions`

## 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.

---

[API](https://skmtc.net/openai/apis/openai-api-3.md) · [All operations](https://skmtc.net/openai/apis/openai-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openai/openai-api-3/versions/74cbcf73838f/schema)