Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

ChatKit

Models
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 number or boolean or number] or null

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

One of the following:
string
number
boolean
number
tracing: object { enabled }

Tracing settings applied to the workflow.

enabled: boolean

Indicates whether tracing is enabled.

version: string or null

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

ChatKitSessions

Cancel a ChatKit session
POST
/chatkit/sessions/{session_id}/cancel
Create a ChatKit session
POST
/chatkit/sessions

ChatKitThreads

Delete a ChatKit thread
DELETE
/chatkit/threads/{thread_id}
List ChatKit threads
GET
/chatkit/threads
List ChatKit thread items
GET
/chatkit/threads/{thread_id}/items
Retrieve a ChatKit thread
GET
/chatkit/threads/{thread_id}
Models
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: 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" (default: "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 integer

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

minimum1
maximum512
max_files: optional integer

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 integer

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" (default: "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.

formatint64
minimum1
maximum600
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: integer or null

Maximum upload size in megabytes.

max_files: integer or null

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: integer or null

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: integer

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 integer

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 number 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
maxLength10485760
number
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 or null

Preview URL for rendering the attachment inline.

formaturi
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 File { source, type } or URL { 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" (default: "file")

Type discriminator that is always file.

type: "file" (default: "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" (default: "url")

Type discriminator that is always url.

url: string

URL referenced by the annotation.

formaturi
type: "url" (default: "url")

Type discriminator that is always url for this annotation.

text: string

Assistant generated text.

type: "output_text" (default: "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: integer

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

formatunixtime
object: "chatkit.thread" (default: "chatkit.thread")

Type discriminator that is always chatkit.thread.

status: Active { type } or Locked { reason, type } or Closed { 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" (default: "active")

Status discriminator that is always active.

Locked object { reason, type }

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

reason: string or null

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

type: "locked" (default: "locked")

Status discriminator that is always locked.

Closed object { reason, type }

Indicates that a thread has been closed.

reason: string or null

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

type: "closed" (default: "closed")

Status discriminator that is always closed.

title: string or null

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 File { source, type } or URL { 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" (default: "file")

Type discriminator that is always file.

type: "file" (default: "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" (default: "url")

Type discriminator that is always url.

url: string

URL referenced by the annotation.

formaturi
type: "url" (default: "url")

Type discriminator that is always url for this annotation.

text: string

Assistant generated text.

type: "output_text" (default: "output_text")

Type discriminator that is always output_text.

created_at: integer

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

formatunixtime
object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

thread_id: string

Identifier of the parent thread.

type: "chatkit.assistant_message" (default: "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 or null

Preview URL for rendering the attachment inline.

formaturi
type: "image" or "file"

Attachment discriminator.

One of the following:
"image"
"file"
content: array of InputText { text, type } or QuotedText { 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" (default: "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" (default: "quoted_text")

Type discriminator that is always quoted_text.

created_at: integer

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

formatunixtime
inference_options: object { model, tool_choice } or null

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

model: string or null

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

tool_choice: object { id } or null

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

id: string

Identifier of the requested tool.

object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

thread_id: string

Identifier of the parent thread.

type: "chatkit.user_message" (default: "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 File { source, type } or URL { 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" (default: "file")

Type discriminator that is always file.

type: "file" (default: "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" (default: "url")

Type discriminator that is always url.

url: string

URL referenced by the annotation.

formaturi
type: "url" (default: "url")

Type discriminator that is always url for this annotation.

text: string

Assistant generated text.

type: "output_text" (default: "output_text")

Type discriminator that is always output_text.

created_at: integer

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

formatunixtime
object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

thread_id: string

Identifier of the parent thread.

type: "chatkit.assistant_message" (default: "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: integer

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

formatunixtime
object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

thread_id: string

Identifier of the parent thread.

type: "chatkit.widget" (default: "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: integer

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

formatunixtime
name: string

Tool name that was invoked.

object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

output: string or null

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" (default: "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: integer

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

formatunixtime
heading: string or null

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

object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

summary: string or null

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" (default: "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: integer

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

formatunixtime
object: "chatkit.thread_item" (default: "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 or null

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

summary: string or null

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" (default: "chatkit.task_group")

Type discriminator that is always chatkit.task_group.

first_id: string or null

The ID of the first item in the list.

has_more: boolean

Whether there are more items available.

last_id: string or null

The ID of the last item in the list.

object: "list" (default: "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 or null

Preview URL for rendering the attachment inline.

formaturi
type: "image" or "file"

Attachment discriminator.

One of the following:
"image"
"file"
content: array of InputText { text, type } or QuotedText { 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" (default: "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" (default: "quoted_text")

Type discriminator that is always quoted_text.

created_at: integer

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

formatunixtime
inference_options: object { model, tool_choice } or null

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

model: string or null

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

tool_choice: object { id } or null

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

id: string

Identifier of the requested tool.

object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

thread_id: string

Identifier of the parent thread.

type: "chatkit.user_message" (default: "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: integer

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

formatunixtime
object: "chatkit.thread_item" (default: "chatkit.thread_item")

Type discriminator that is always chatkit.thread_item.

thread_id: string

Identifier of the parent thread.

type: "chatkit.widget" (default: "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" (default: "chatkit.thread.deleted")

Type discriminator that is always chatkit.thread.deleted.