Skip to content
API Reference
Beta

ChatKit

ModelsExpand Collapse
class ChatKitWorkflow { id, state_variables, tracing, version }

Workflow metadata and state returned for the session.

id: String

Identifier of the workflow backing the session.

state_variables: Hash[Symbol, String | bool | Float]

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

Accepts one of the following:
String
bool
Float
tracing: { enabled}

Tracing settings applied to the workflow.

enabled: bool

Indicates whether tracing is enabled.

version: String

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

ChatKitSessions

Cancel chat session
beta.chatkit.sessions.cancel(session_id) -> ChatSession { id, chatkit_configuration, client_secret, 7 more }
POST/chatkit/sessions/{session_id}/cancel
Create ChatKit session
beta.chatkit.sessions.create(**kwargs) -> ChatSession { id, chatkit_configuration, client_secret, 7 more }
POST/chatkit/sessions

ChatKitThreads

List ChatKit thread items
beta.chatkit.threads.list_items(thread_id, **kwargs) -> ConversationCursorPage<ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more>
GET/chatkit/threads/{thread_id}/items
Retrieve ChatKit thread
beta.chatkit.threads.retrieve(thread_id) -> ChatKitThread { id, created_at, object, 3 more }
GET/chatkit/threads/{thread_id}
Delete ChatKit thread
beta.chatkit.threads.delete(thread_id) -> ThreadDeleteResponse { id, deleted, object }
DELETE/chatkit/threads/{thread_id}
List ChatKit threads
beta.chatkit.threads.list(**kwargs) -> ConversationCursorPage<ChatKitThread { id, created_at, object, 3 more } >
GET/chatkit/threads
ModelsExpand 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.

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.

class ChatSessionAutomaticThreadTitling { enabled }

Automatic thread title preferences for the session.

enabled: bool

Whether automatic thread titling is enabled.

class ChatSessionChatKitConfiguration { automatic_thread_titling, file_upload, history }

ChatKit configuration for the session.

automatic_thread_titling: ChatSessionAutomaticThreadTitling { enabled }

Automatic thread titling preferences.

file_upload: ChatSessionFileUpload { enabled, max_file_size, max_files }

Upload settings for the session.

history: ChatSessionHistory { enabled, recent_threads }

History retention configuration.

class ChatSessionChatKitConfigurationParam { automatic_thread_titling, file_upload, history }

Optional per-session configuration settings for ChatKit behavior.

automatic_thread_titling: { enabled}

Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.

enabled: bool

Enable automatic thread title generation. Defaults to true.

file_upload: { enabled, max_file_size, max_files}

Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).

enabled: bool

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.

maximum512
minimum1
max_files: Integer

Maximum number of files that can be uploaded to the session. Defaults to 10.

minimum1
history: { enabled, recent_threads}

Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null).

enabled: bool

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.

minimum1
class ChatSessionExpiresAfterParam { anchor, seconds }

Controls when the session expires relative to an anchor timestamp.

anchor: :created_at

Base timestamp used to calculate expiration. Currently fixed to created_at.

seconds: Integer

Number of seconds after the anchor when the session expires.

maximum600
minimum1
class ChatSessionFileUpload { enabled, max_file_size, max_files }

Upload permissions and limits applied to the session.

enabled: bool

Indicates if uploads are enabled for the session.

max_file_size: Integer

Maximum upload size in megabytes.

max_files: Integer

Maximum number of uploads allowed during the session.

class ChatSessionHistory { enabled, recent_threads }

History retention preferences returned for the session.

enabled: bool

Indicates if chat history is persisted for the session.

recent_threads: Integer

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

class ChatSessionRateLimits { max_requests_per_1_minute }

Active per-minute request limit for the session.

max_requests_per_1_minute: Integer

Maximum allowed requests per one-minute window.

class ChatSessionRateLimitsParam { max_requests_per_1_minute }

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.

minimum1
ChatSessionStatus = :active | :expired | :cancelled
Accepts one of the following:
:active
:expired
:cancelled
class ChatSessionWorkflowParam { id, state_variables, tracing, version }

Workflow reference and overrides applied to the chat session.

id: String

Identifier for the workflow invoked by the session.

state_variables: Hash[Symbol, String | bool | Float]

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.

Accepts one of the following:
String
bool
Float
tracing: { enabled}

Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default.

enabled: bool

Whether tracing is enabled during the session. Defaults to true.

version: String

Specific workflow version to run. Defaults to the latest deployed version.

class ChatKitAttachment { id, mime_type, name, 2 more }

Attachment metadata included on thread items.

id: String

Identifier for the attachment.

mime_type: String

MIME type of the attachment.

name: String

Original display name for the attachment.

preview_url: String

Preview URL for rendering the attachment inline.

type: :image | :file

Attachment discriminator.

Accepts one of the following:
:image
:file
class ChatKitResponseOutputText { annotations, text, type }

Assistant response text accompanied by optional annotations.

annotations: Array[{ source, type} | { source, type}]

Ordered list of annotations attached to the response text.

Accepts one of the following:
class File { source, type }

Annotation that references an uploaded file.

source: { filename, type}

File attachment referenced by the annotation.

filename: String

Filename referenced by the annotation.

type: :file

Type discriminator that is always file.

type: :file

Type discriminator that is always file for this annotation.

class URL { source, type }

Annotation that references a URL.

source: { type, url}

URL referenced by the annotation.

type: :url

Type discriminator that is always url.

url: String

URL referenced by the annotation.

type: :url

Type discriminator that is always url for this annotation.

text: String

Assistant generated text.

type: :output_text

Type discriminator that is always output_text.

class ChatKitThread { id, created_at, object, 3 more }

Represents a ChatKit thread and its current status.

id: String

Identifier of the thread.

created_at: Integer

Unix timestamp (in seconds) for when the thread was created.

object: :"chatkit.thread"

Type discriminator that is always chatkit.thread.

status: { type} | { reason, type} | { reason, type}

Current status for the thread. Defaults to active for newly created threads.

Accepts one of the following:
class Active { type }

Indicates that a thread is active.

type: :active

Status discriminator that is always active.

class Locked { reason, type }

Indicates that a thread is locked and cannot accept new input.

reason: String

Reason that the thread was locked. Defaults to null when no reason is recorded.

type: :locked

Status discriminator that is always locked.

class Closed { reason, type }

Indicates that a thread has been closed.

reason: String

Reason that the thread was closed. Defaults to null when no reason is recorded.

type: :closed

Status discriminator that is always closed.

title: String

Optional human-readable title for the thread. Defaults to null when no title has been generated.

user: String

Free-form string that identifies your end user who owns the thread.

class ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more }

Assistant-authored message within a thread.

id: String

Identifier of the thread item.

content: Array[ChatKitResponseOutputText { annotations, text, type } ]

Ordered assistant response segments.

annotations: Array[{ source, type} | { source, type}]

Ordered list of annotations attached to the response text.

Accepts one of the following:
class File { source, type }

Annotation that references an uploaded file.

source: { filename, type}

File attachment referenced by the annotation.

filename: String

Filename referenced by the annotation.

type: :file

Type discriminator that is always file.

type: :file

Type discriminator that is always file for this annotation.

class URL { source, type }

Annotation that references a URL.

source: { type, url}

URL referenced by the annotation.

type: :url

Type discriminator that is always url.

url: String

URL referenced by the annotation.

type: :url

Type discriminator that is always url for this annotation.

text: String

Assistant generated text.

type: :output_text

Type discriminator that is always output_text.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.assistant_message"

Type discriminator that is always chatkit.assistant_message.

class ChatKitThreadItemList { data, first_id, has_more, 2 more }

A paginated list of thread items rendered for the ChatKit API.

data: Array[ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more]

A list of items

Accepts one of the following:
class ChatKitThreadUserMessageItem { id, attachments, content, 5 more }

User-authored messages within a thread.

id: String

Identifier of the thread item.

attachments: Array[ChatKitAttachment { id, mime_type, name, 2 more } ]

Attachments associated with the user message. Defaults to an empty list.

id: String

Identifier for the attachment.

mime_type: String

MIME type of the attachment.

name: String

Original display name for the attachment.

preview_url: String

Preview URL for rendering the attachment inline.

type: :image | :file

Attachment discriminator.

Accepts one of the following:
:image
:file
content: Array[{ text, type} | { text, type}]

Ordered content elements supplied by the user.

Accepts one of the following:
class InputText { text, type }

Text block that a user contributed to the thread.

text: String

Plain-text content supplied by the user.

type: :input_text

Type discriminator that is always input_text.

class QuotedText { text, type }

Quoted snippet that the user referenced in their message.

text: String

Quoted text content.

type: :quoted_text

Type discriminator that is always quoted_text.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

inference_options: { model, tool_choice}

Inference overrides applied to the message. Defaults to null when unset.

model: String

Model name that generated the response. Defaults to null when using the session default.

tool_choice: { id}

Preferred tool to invoke. Defaults to null when ChatKit should auto-select.

id: String

Identifier of the requested tool.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.user_message"
class ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more }

Assistant-authored message within a thread.

id: String

Identifier of the thread item.

content: Array[ChatKitResponseOutputText { annotations, text, type } ]

Ordered assistant response segments.

annotations: Array[{ source, type} | { source, type}]

Ordered list of annotations attached to the response text.

Accepts one of the following:
class File { source, type }

Annotation that references an uploaded file.

source: { filename, type}

File attachment referenced by the annotation.

filename: String

Filename referenced by the annotation.

type: :file

Type discriminator that is always file.

type: :file

Type discriminator that is always file for this annotation.

class URL { source, type }

Annotation that references a URL.

source: { type, url}

URL referenced by the annotation.

type: :url

Type discriminator that is always url.

url: String

URL referenced by the annotation.

type: :url

Type discriminator that is always url for this annotation.

text: String

Assistant generated text.

type: :output_text

Type discriminator that is always output_text.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.assistant_message"

Type discriminator that is always chatkit.assistant_message.

class ChatKitWidgetItem { id, created_at, object, 3 more }

Thread item that renders a widget payload.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.widget"

Type discriminator that is always chatkit.widget.

widget: String

Serialized widget payload rendered in the UI.

class ChatKitClientToolCall { id, arguments, call_id, 7 more }

Record of a client side tool invocation initiated by the assistant.

id: String

Identifier of the thread item.

arguments: String

JSON-encoded arguments that were sent to the tool.

call_id: String

Identifier for the client tool call.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

name: String

Tool name that was invoked.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

output: String

JSON-encoded output captured from the tool. Defaults to null while execution is in progress.

status: :in_progress | :completed

Execution status for the tool call.

Accepts one of the following:
:in_progress
:completed
thread_id: String

Identifier of the parent thread.

type: :"chatkit.client_tool_call"

Type discriminator that is always chatkit.client_tool_call.

class ChatKitTask { id, created_at, heading, 5 more }

Task emitted by the workflow to show progress and status updates.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

heading: String

Optional heading for the task. Defaults to null when not provided.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

summary: String

Optional summary that describes the task. Defaults to null when omitted.

task_type: :custom | :thought

Subtype for the task.

Accepts one of the following:
:custom
:thought
thread_id: String

Identifier of the parent thread.

type: :"chatkit.task"

Type discriminator that is always chatkit.task.

class ChatKitTaskGroup { id, created_at, object, 3 more }

Collection of workflow tasks grouped together in the thread.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

tasks: Array[{ heading, summary, type}]

Tasks included in the group.

heading: String

Optional heading for the grouped task. Defaults to null when not provided.

summary: String

Optional summary that describes the grouped task. Defaults to null when omitted.

type: :custom | :thought

Subtype for the grouped task.

Accepts one of the following:
:custom
:thought
thread_id: String

Identifier of the parent thread.

type: :"chatkit.task_group"

Type discriminator that is always chatkit.task_group.

first_id: String

The ID of the first item in the list.

has_more: bool

Whether there are more items available.

last_id: String

The ID of the last item in the list.

object: :list

The type of object returned, must be list.

class ChatKitThreadUserMessageItem { id, attachments, content, 5 more }

User-authored messages within a thread.

id: String

Identifier of the thread item.

attachments: Array[ChatKitAttachment { id, mime_type, name, 2 more } ]

Attachments associated with the user message. Defaults to an empty list.

id: String

Identifier for the attachment.

mime_type: String

MIME type of the attachment.

name: String

Original display name for the attachment.

preview_url: String

Preview URL for rendering the attachment inline.

type: :image | :file

Attachment discriminator.

Accepts one of the following:
:image
:file
content: Array[{ text, type} | { text, type}]

Ordered content elements supplied by the user.

Accepts one of the following:
class InputText { text, type }

Text block that a user contributed to the thread.

text: String

Plain-text content supplied by the user.

type: :input_text

Type discriminator that is always input_text.

class QuotedText { text, type }

Quoted snippet that the user referenced in their message.

text: String

Quoted text content.

type: :quoted_text

Type discriminator that is always quoted_text.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

inference_options: { model, tool_choice}

Inference overrides applied to the message. Defaults to null when unset.

model: String

Model name that generated the response. Defaults to null when using the session default.

tool_choice: { id}

Preferred tool to invoke. Defaults to null when ChatKit should auto-select.

id: String

Identifier of the requested tool.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.user_message"
class ChatKitWidgetItem { id, created_at, object, 3 more }

Thread item that renders a widget payload.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.widget"

Type discriminator that is always chatkit.widget.

widget: String

Serialized widget payload rendered in the UI.