Skip to content
Primary navigation

Suggested
API Dashboard
API Reference
Beta
ChatKit
Sessions

Create ChatKit session

$ openai beta:chatkit:sessions create
POST/chatkit/sessions

Create a ChatKit session.

ParametersExpand Collapse
--user: string

A free-form string that identifies your end user; ensures this Session can access other objects that have the same user scope.

--workflow: object { id, state_variables, tracing, version }

Workflow that powers the session.

--chatkit-configuration: optional object { automatic_thread_titling, file_upload, history }

Optional overrides for ChatKit runtime configuration features

--expires-after: optional object { anchor, seconds }

Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.

--rate-limits: optional object { max_requests_per_1_minute }

Optional override for per-minute request limits. When omitted, defaults to 10.

ReturnsExpand Collapse
chat_session: object { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

id: string

Identifier for the ChatKit session.

chatkit_configuration: object { automatic_thread_titling, file_upload, history }

Resolved ChatKit feature configuration for the session.

automatic_thread_titling: object { enabled }

Automatic thread titling preferences.

enabled: boolean

Whether automatic thread titling is enabled.

file_upload: object { enabled, max_file_size, max_files }

Upload settings for the session.

enabled: boolean

Indicates if uploads are enabled for the session.

max_file_size: number

Maximum upload size in megabytes.

max_files: number

Maximum number of uploads allowed during the session.

history: object { enabled, recent_threads }

History retention configuration.

enabled: boolean

Indicates if chat history is persisted for the session.

recent_threads: number

Number of prior threads surfaced in history views. Defaults to null when all history is retained.

client_secret: string

Ephemeral client secret that authenticates session requests.

expires_at: number

Unix timestamp (in seconds) for when the session expires.

max_requests_per_1_minute: number

Convenience copy of the per-minute request limit.

object: "chatkit.session"

Type discriminator that is always chatkit.session.

rate_limits: object { max_requests_per_1_minute }

Resolved rate limit values.

max_requests_per_1_minute: number

Maximum allowed requests per one-minute window.

status: "active" or "expired" or "cancelled"

Current lifecycle state of the session.

"active"
"expired"
"cancelled"
user: string

User identifier associated with the session.

workflow: object { id, state_variables, tracing, version }

Workflow metadata for the session.

id: string

Identifier of the workflow backing the session.

state_variables: map[string or boolean or number]

State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.

union_member_0: string
union_member_1: boolean
union_member_2: number
tracing: object { enabled }

Tracing settings applied to the workflow.

enabled: boolean

Indicates whether tracing is enabled.

version: string

Specific workflow version used for the session. Defaults to null when using the latest deployment.

Create ChatKit session

openai beta:chatkit:sessions create \
  --api-key 'My API Key' \
  --user x \
  --workflow '{id: id}'
{
  "client_secret": "chatkit_token_123",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": "2024-10-01"
  },
  "scope": {
    "project": "alpha",
    "environment": "staging"
  },
  "max_requests_per_1_minute": 60,
  "max_requests_per_session": 500,
  "status": "active"
}
Returns Examples
{
  "client_secret": "chatkit_token_123",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": "2024-10-01"
  },
  "scope": {
    "project": "alpha",
    "environment": "staging"
  },
  "max_requests_per_1_minute": 60,
  "max_requests_per_session": 500,
  "status": "active"
}