API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

ChatKit

ModelsExpand Collapse

ChatKitWorkflow object { id, state_variables, tracing, version }

Workflow metadata and state returned 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.

One of the following:

string

boolean

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.

ChatKitSessions

Cancel chat session

POST/chatkit/sessions/{session_id}/cancel

Create ChatKit session

POST/chatkit/sessions

ChatKitThreads

List ChatKit thread items

GET/chatkit/threads/{thread_id}/items

Retrieve ChatKit thread

GET/chatkit/threads/{thread_id}

Delete ChatKit thread

DELETE/chatkit/threads/{thread_id}

List ChatKit threads

GET/chatkit/threads

ModelsExpand Collapse

ChatSession 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: 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: 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: 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.

ChatSessionAutomaticThreadTitling object { enabled }

Automatic thread title preferences for the session.

enabled: boolean

Whether automatic thread titling is enabled.

ChatSessionChatKitConfiguration object { 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.

ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }

Optional per-session configuration settings for ChatKit behavior.

automatic_thread_titling: optional object { enabled }

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

enabled: optional boolean

Enable automatic thread title generation. Defaults to true.

file_upload: optional object { 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: optional boolean

Enable uploads for this session. Defaults to false.

max_file_size: optional number

Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.

maximum512

minimum1

max_files: optional number

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

minimum1

history: optional object { enabled, recent_threads }

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

enabled: optional boolean

Enables chat users to access previous ChatKit threads. Defaults to true.

recent_threads: optional number

Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.

minimum1

ChatSessionExpiresAfterParam object { 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: number

Number of seconds after the anchor when the session expires.

maximum600

minimum1

ChatSessionFileUpload object { enabled, max_file_size, max_files }

Upload permissions and limits applied to 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.

ChatSessionHistory object { enabled, recent_threads }

History retention preferences returned for the session.

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.

ChatSessionRateLimits object { max_requests_per_1_minute }

Active per-minute request limit for the session.

max_requests_per_1_minute: number

Maximum allowed requests per one-minute window.

ChatSessionRateLimitsParam object { max_requests_per_1_minute }

Controls request rate limits for the session.

max_requests_per_1_minute: optional number

Maximum number of requests allowed per minute for the session. Defaults to 10.

minimum1

ChatSessionStatus = "active" or "expired" or "cancelled"

One of the following:

"active"

"expired"

"cancelled"

ChatSessionWorkflowParam object { 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: optional map[string or boolean or number]

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

boolean

number

tracing: optional object { enabled }

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

enabled: optional boolean

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

version: optional string

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

ChatKitAttachment object { 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" or "file"

Attachment discriminator.

One of the following:

"image"

"file"

ChatKitResponseOutputText object { annotations, text, type }

Assistant response text accompanied by optional annotations.

annotations: array of object { source, type } or object { source, type }

Ordered list of annotations attached to the response text.

One of the following:

File object { source, type }

Annotation that references an uploaded file.

source: object { 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.

URL object { source, type }

Annotation that references a URL.

source: object { 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.

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

Represents a ChatKit thread and its current status.

id: string

Identifier of the thread.

created_at: number

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

object: "chatkit.thread"

Type discriminator that is always chatkit.thread.

status: object { type } or object { reason, type } or object { reason, type }

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

One of the following:

Active object { type }

Indicates that a thread is active.

type: "active"

Status discriminator that is always active.

Locked object { 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.

Closed object { 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.

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

Assistant-authored message within a thread.

id: string

Identifier of the thread item.

content: array of ChatKitResponseOutputText { annotations, text, type }

Ordered assistant response segments.

annotations: array of object { source, type } or object { source, type }

Ordered list of annotations attached to the response text.

One of the following:

File object { source, type }

Annotation that references an uploaded file.

source: object { 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.

URL object { source, type }

Annotation that references a URL.

source: object { 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: number

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.

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

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

data: array of ChatKitThreadUserMessageItem { id, attachments, content, 5 more } or ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } or ChatKitWidgetItem { id, created_at, object, 3 more } or 3 more

A list of items

One of the following:

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

User-authored messages within a thread.

id: string

Identifier of the thread item.

attachments: array of 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" or "file"

Attachment discriminator.

One of the following:

"image"

"file"

content: array of object { text, type } or object { text, type }

Ordered content elements supplied by the user.

One of the following:

InputText object { 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.

QuotedText object { 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: number

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

inference_options: object { 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: object { 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"

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

Assistant-authored message within a thread.

id: string

Identifier of the thread item.

content: array of ChatKitResponseOutputText { annotations, text, type }

Ordered assistant response segments.

annotations: array of object { source, type } or object { source, type }

Ordered list of annotations attached to the response text.

One of the following:

File object { source, type }

Annotation that references an uploaded file.

source: object { 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.

URL object { source, type }

Annotation that references a URL.

source: object { 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: number

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.

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

Thread item that renders a widget payload.

id: string

Identifier of the thread item.

created_at: number

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.

ChatKitClientToolCall object { 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: number

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" or "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.

ChatKitTask object { 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: number

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" or "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.

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

Collection of workflow tasks grouped together in the thread.

id: string

Identifier of the thread item.

created_at: number

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

object: "chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

tasks: array of object { 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" or "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: boolean

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.

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

User-authored messages within a thread.

id: string

Identifier of the thread item.

attachments: array of 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" or "file"

Attachment discriminator.

One of the following:

"image"

"file"

content: array of object { text, type } or object { text, type }

Ordered content elements supplied by the user.

One of the following:

InputText object { 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.

QuotedText object { 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: number

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

inference_options: object { 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: object { 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"

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

Thread item that renders a widget payload.

id: string

Identifier of the thread item.

created_at: number

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.

ThreadDeleteResponse object { id, deleted, object }

Confirmation payload returned after deleting a thread.

id: string

Identifier of the deleted thread.

deleted: boolean

Indicates that the thread has been deleted.

object: "chatkit.thread.deleted"

Type discriminator that is always chatkit.thread.deleted.