API Reference

Beta

ChatKit

Sessions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create ChatKit session

beta.chatkit.sessions.create(**kwargs) -> ChatSession { id, chatkit_configuration, client_secret, 7 more }

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.

minLength1

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

Workflow that powers the session.

chatkit_configuration: ChatSessionChatKitConfigurationParam { automatic_thread_titling, file_upload, history }

Optional overrides for ChatKit runtime configuration features

expires_after: ChatSessionExpiresAfterParam { anchor, seconds }

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

rate_limits: ChatSessionRateLimitsParam { max_requests_per_1_minute }

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

ReturnsExpand Collapse

class ChatSession { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

id: String

Identifier for the ChatKit session.

chatkit_configuration: ChatSessionChatKitConfiguration { automatic_thread_titling, file_upload, history }

Resolved ChatKit feature configuration for the session.

client_secret: String

Ephemeral client secret that authenticates session requests.

expires_at: Integer

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

formatunixtime

max_requests_per_1_minute: Integer

Convenience copy of the per-minute request limit.

object: :"chatkit.session"

Type discriminator that is always chatkit.session.

rate_limits: ChatSessionRateLimits { max_requests_per_1_minute }

Resolved rate limit values.

status: ChatSessionStatus

Current lifecycle state of the session.

user: String

User identifier associated with the session.

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

Workflow metadata for the session.

Create ChatKit session

Ruby

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

require "openai"

openai = OpenAI::Client.new

chat_session = openai.beta.chatkit.sessions.create(user: "user", workflow: {id: "id"})

puts(chat_session)

{
  "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"
}