API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

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.

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

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.

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.

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.

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.

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.

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

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.

One of the following:

:image

:file

content: Array[{ text, type} | { text, type}]

Ordered content elements supplied by the user.

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.

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.

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.

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.

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.

One of the following:

:image

:file

content: Array[{ text, type} | { text, type}]

Ordered content elements supplied by the user.

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.