API Reference

Beta

ChatKit

Sessions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create ChatKit session

ChatSession beta().chatkit().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/chatkit/sessions

Create a ChatKit session

ParametersExpand Collapse

SessionCreateParams params

String user

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

minLength1

ChatSessionWorkflowParam workflow

Workflow that powers the session.

Optional<ChatSessionChatKitConfigurationParam> chatkitConfiguration

Optional overrides for ChatKit runtime configuration features

Optional<ChatSessionExpiresAfterParam> expiresAfter

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

Optional<ChatSessionRateLimitsParam> rateLimits

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

ReturnsExpand Collapse

class ChatSession:

Represents a ChatKit session and its resolved configuration.

String id

Identifier for the ChatKit session.

ChatSessionChatKitConfiguration chatkitConfiguration

Resolved ChatKit feature configuration for the session.

ChatSessionAutomaticThreadTitling automaticThreadTitling

Automatic thread titling preferences.

boolean enabled

Whether automatic thread titling is enabled.

ChatSessionFileUpload fileUpload

Upload settings for the session.

boolean enabled

Indicates if uploads are enabled for the session.

Optional<Long> maxFileSize

Maximum upload size in megabytes.

Optional<Long> maxFiles

Maximum number of uploads allowed during the session.

ChatSessionHistory history

History retention configuration.

boolean enabled

Indicates if chat history is persisted for the session.

Optional<Long> recentThreads

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

String clientSecret

Ephemeral client secret that authenticates session requests.

long expiresAt

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

long maxRequestsPer1Minute

Convenience copy of the per-minute request limit.

JsonValue; object_ "chatkit.session"constant"chatkit.session"constant

Type discriminator that is always chatkit.session.

ChatSessionRateLimits rateLimits

Resolved rate limit values.

long maxRequestsPer1Minute

Maximum allowed requests per one-minute window.

ChatSessionStatus status

Current lifecycle state of the session.

Accepts one of the following:

ACTIVE("active")

EXPIRED("expired")

CANCELLED("cancelled")

String user

User identifier associated with the session.

ChatKitWorkflow workflow

Workflow metadata for the session.

String id

Identifier of the workflow backing the session.

Optional<StateVariables> stateVariables

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

Accepts one of the following:

String

boolean

double

Tracing tracing

Tracing settings applied to the workflow.

boolean enabled

Indicates whether tracing is enabled.

Optional<String> version

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

Create ChatKit session

Java

HTTP

TypeScript

Python

Java

Go

Ruby

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.SessionCreateParams;
import com.openai.models.beta.chatkit.threads.ChatSession;
import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionCreateParams params = SessionCreateParams.builder()
            .user("x")
            .workflow(ChatSessionWorkflowParam.builder()
                .id("id")
                .build())
            .build();
        ChatSession chatSession = client.beta().chatkit().sessions().create(params);
    }
}

200 example

{
  "id": "id",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 0,
      "max_files": 0
    },
    "history": {
      "enabled": true,
      "recent_threads": 0
    }
  },
  "client_secret": "client_secret",
  "expires_at": 0,
  "max_requests_per_1_minute": 0,
  "object": "chatkit.session",
  "rate_limits": {
    "max_requests_per_1_minute": 0
  },
  "status": "active",
  "user": "user",
  "workflow": {
    "id": "id",
    "state_variables": {
      "foo": "string"
    },
    "tracing": {
      "enabled": true
    },
    "version": "version"
  }
}

Returns Examples

200 example

{
  "id": "id",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 0,
      "max_files": 0
    },
    "history": {
      "enabled": true,
      "recent_threads": 0
    }
  },
  "client_secret": "client_secret",
  "expires_at": 0,
  "max_requests_per_1_minute": 0,
  "object": "chatkit.session",
  "rate_limits": {
    "max_requests_per_1_minute": 0
  },
  "status": "active",
  "user": "user",
  "workflow": {
    "id": "id",
    "state_variables": {
      "foo": "string"
    },
    "tracing": {
      "enabled": true
    },
    "version": "version"
  }
}