# ChatKit ## Domain Types ### ChatKit Workflow - `chatkit_workflow: 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. - `union_member_0: string` - `union_member_1: boolean` - `union_member_2: 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. # Sessions ## Cancel chat session `$ openai beta:chatkit:sessions cancel` **post** `/chatkit/sessions/{session_id}/cancel` Cancel an active ChatKit session and return its most recent metadata. Cancelling prevents new requests from using the issued client secret. ### Parameters - `--session-id: string` Unique identifier for the ChatKit session to cancel. ### Returns - `chat_session: 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: object { automatic_thread_titling, file_upload, history }` Resolved ChatKit feature configuration for the session. - `automatic_thread_titling: object { enabled }` Automatic thread titling preferences. - `enabled: boolean` Whether automatic thread titling is enabled. - `file_upload: object { enabled, max_file_size, max_files }` Upload settings for 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. - `history: object { enabled, recent_threads }` History retention configuration. - `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. - `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: object { max_requests_per_1_minute }` Resolved rate limit values. - `max_requests_per_1_minute: number` Maximum allowed requests per one-minute window. - `status: "active" or "expired" or "cancelled"` Current lifecycle state of the session. - `"active"` - `"expired"` - `"cancelled"` - `user: string` User identifier associated with the session. - `workflow: object { id, state_variables, tracing, version }` Workflow metadata 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. - `union_member_0: string` - `union_member_1: boolean` - `union_member_2: 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. ### Example ```cli openai beta:chatkit:sessions cancel \ --api-key 'My API Key' \ --session-id cksess_123 ``` #### Response ```json { "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" } } ``` ## Create ChatKit session `$ openai beta:chatkit:sessions create` **post** `/chatkit/sessions` Create a ChatKit session. ### Parameters - `--user: string` A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - `--workflow: object { id, state_variables, tracing, version }` Workflow that powers the session. - `--chatkit-configuration: optional object { automatic_thread_titling, file_upload, history }` Optional overrides for ChatKit runtime configuration features - `--expires-after: optional object { anchor, seconds }` Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - `--rate-limits: optional object { max_requests_per_1_minute }` Optional override for per-minute request limits. When omitted, defaults to 10. ### Returns - `chat_session: 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: object { automatic_thread_titling, file_upload, history }` Resolved ChatKit feature configuration for the session. - `automatic_thread_titling: object { enabled }` Automatic thread titling preferences. - `enabled: boolean` Whether automatic thread titling is enabled. - `file_upload: object { enabled, max_file_size, max_files }` Upload settings for 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. - `history: object { enabled, recent_threads }` History retention configuration. - `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. - `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: object { max_requests_per_1_minute }` Resolved rate limit values. - `max_requests_per_1_minute: number` Maximum allowed requests per one-minute window. - `status: "active" or "expired" or "cancelled"` Current lifecycle state of the session. - `"active"` - `"expired"` - `"cancelled"` - `user: string` User identifier associated with the session. - `workflow: object { id, state_variables, tracing, version }` Workflow metadata 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. - `union_member_0: string` - `union_member_1: boolean` - `union_member_2: 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. ### Example ```cli openai beta:chatkit:sessions create \ --api-key 'My API Key' \ --user x \ --workflow '{id: id}' ``` #### Response ```json { "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" } } ``` # Threads ## List ChatKit thread items `$ openai beta:chatkit:threads list-items` **get** `/chatkit/threads/{thread_id}/items` List items that belong to a ChatKit thread. ### Parameters - `--thread-id: string` Identifier of the ChatKit thread whose items are requested. - `--after: optional string` List items created after this thread item ID. Defaults to null for the first page. - `--before: optional string` List items created before this thread item ID. Defaults to null for the newest results. - `--limit: optional number` Maximum number of thread items to return. Defaults to 20. - `--order: optional "asc" or "desc"` Sort order for results by creation time. Defaults to `desc`. ### Returns - `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }` A paginated list of thread items rendered for the ChatKit API. - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` A list of items - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` User-authored messages within a thread. - `id: string` Identifier of the thread item. - `attachments: array of ChatKitAttachment` 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. - `"image"` - `"file"` - `content: array of object { text, type } or object { text, type }` Ordered content elements supplied by the user. - `input_text: 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`. - `quoted_text: 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"` - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` Assistant-authored message within a thread. - `id: string` Identifier of the thread item. - `content: array of ChatKitResponseOutputText` Ordered assistant response segments. - `annotations: array of object { source, type } or object { source, type }` Ordered list of annotations attached to the response text. - `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`. - `chatkit_widget_item: 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. - `chatkit.client_tool_call: 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. - `"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`. - `chatkit.task: 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. - `"custom"` - `"thought"` - `thread_id: string` Identifier of the parent thread. - `type: "chatkit.task"` Type discriminator that is always `chatkit.task`. - `chatkit.task_group: 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. - `"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`. ### Example ```cli openai beta:chatkit:threads list-items \ --api-key 'My API Key' \ --thread-id cthr_123 ``` #### Response ```json { "data": [ { "id": "id", "attachments": [ { "id": "id", "mime_type": "mime_type", "name": "name", "preview_url": "https://example.com", "type": "image" } ], "content": [ { "text": "text", "type": "input_text" } ], "created_at": 0, "inference_options": { "model": "model", "tool_choice": { "id": "id" } }, "object": "chatkit.thread_item", "thread_id": "thread_id", "type": "chatkit.user_message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve ChatKit thread `$ openai beta:chatkit:threads retrieve` **get** `/chatkit/threads/{thread_id}` Retrieve a ChatKit thread by its identifier. ### Parameters - `--thread-id: string` Identifier of the ChatKit thread to retrieve. ### Returns - `chatkit_thread: 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. - `active: object { type }` Indicates that a thread is 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. ### Example ```cli openai beta:chatkit:threads retrieve \ --api-key 'My API Key' \ --thread-id cthr_123 ``` #### Response ```json { "id": "cthr_def456", "created_at": 1712345600, "object": "chatkit.thread", "status": { "type": "active" }, "title": "Demo feedback", "user": "user_456" } ``` ## Delete ChatKit thread `$ openai beta:chatkit:threads delete` **delete** `/chatkit/threads/{thread_id}` Delete a ChatKit thread along with its items and stored attachments. ### Parameters - `--thread-id: string` Identifier of the ChatKit thread to delete. ### Returns - `BetaChatKitThreadDeleteResponse: 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`. ### Example ```cli openai beta:chatkit:threads delete \ --api-key 'My API Key' \ --thread-id cthr_123 ``` #### Response ```json { "id": "id", "deleted": true, "object": "chatkit.thread.deleted" } ``` ## List ChatKit threads `$ openai beta:chatkit:threads list` **get** `/chatkit/threads` List ChatKit threads with optional pagination and user filters. ### Parameters - `--after: optional string` List items created after this thread item ID. Defaults to null for the first page. - `--before: optional string` List items created before this thread item ID. Defaults to null for the newest results. - `--limit: optional number` Maximum number of thread items to return. Defaults to 20. - `--order: optional "asc" or "desc"` Sort order for results by creation time. Defaults to `desc`. - `--user: optional string` Filter threads that belong to this user identifier. Defaults to null to return all users. ### Returns - `Threads: object { data, first_id, has_more, 2 more }` A paginated list of ChatKit threads. - `data: array of ChatKitThread` A list of items - `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. - `active: object { type }` Indicates that a thread is 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. - `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`. ### Example ```cli openai beta:chatkit:threads list \ --api-key 'My API Key' ``` #### Response ```json { "data": [ { "id": "cthr_def456", "created_at": 1712345600, "object": "chatkit.thread", "status": { "type": "active" }, "title": "Demo feedback", "user": "user_456" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Domain Types ### Chat Session - `chat_session: 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: object { automatic_thread_titling, file_upload, history }` Resolved ChatKit feature configuration for the session. - `automatic_thread_titling: object { enabled }` Automatic thread titling preferences. - `enabled: boolean` Whether automatic thread titling is enabled. - `file_upload: object { enabled, max_file_size, max_files }` Upload settings for 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. - `history: object { enabled, recent_threads }` History retention configuration. - `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. - `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: object { max_requests_per_1_minute }` Resolved rate limit values. - `max_requests_per_1_minute: number` Maximum allowed requests per one-minute window. - `status: "active" or "expired" or "cancelled"` Current lifecycle state of the session. - `"active"` - `"expired"` - `"cancelled"` - `user: string` User identifier associated with the session. - `workflow: object { id, state_variables, tracing, version }` Workflow metadata 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. - `union_member_0: string` - `union_member_1: boolean` - `union_member_2: 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. ### Chat Session Automatic Thread Titling - `chat_session_automatic_thread_titling: object { enabled }` Automatic thread title preferences for the session. - `enabled: boolean` Whether automatic thread titling is enabled. ### Chat Session ChatKit Configuration - `chat_session_chatkit_configuration: object { automatic_thread_titling, file_upload, history }` ChatKit configuration for the session. - `automatic_thread_titling: object { enabled }` Automatic thread titling preferences. - `enabled: boolean` Whether automatic thread titling is enabled. - `file_upload: object { enabled, max_file_size, max_files }` Upload settings for 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. - `history: object { enabled, recent_threads }` History retention configuration. - `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. ### Chat Session ChatKit Configuration Param - `chat_session_chatkit_configuration_param: 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. - `max_files: optional number` Maximum number of files that can be uploaded to the session. Defaults to 10. - `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. ### Chat Session Expires After Param - `chat_session_expires_after_param: 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. ### Chat Session File Upload - `chat_session_file_upload: 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. ### Chat Session History - `chat_session_history: 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. ### Chat Session Rate Limits - `chat_session_rate_limits: 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. ### Chat Session Rate Limits Param - `chat_session_rate_limits_param: 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. ### Chat Session Status - `chat_session_status: "active" or "expired" or "cancelled"` - `"active"` - `"expired"` - `"cancelled"` ### Chat Session Workflow Param - `chat_session_workflow_param: 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. - `union_member_0: string` - `union_member_1: boolean` - `union_member_2: 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. ### ChatKit Attachment - `chatkit_attachment: 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. - `"image"` - `"file"` ### ChatKit Response Output Text - `chatkit_response_output_text: 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. - `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`. ### ChatKit Thread - `chatkit_thread: 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. - `active: object { type }` Indicates that a thread is 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. ### ChatKit Thread Assistant Message Item - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` Assistant-authored message within a thread. - `id: string` Identifier of the thread item. - `content: array of ChatKitResponseOutputText` Ordered assistant response segments. - `annotations: array of object { source, type } or object { source, type }` Ordered list of annotations attached to the response text. - `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`. ### ChatKit Thread Item List - `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }` A paginated list of thread items rendered for the ChatKit API. - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` A list of items - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` User-authored messages within a thread. - `id: string` Identifier of the thread item. - `attachments: array of ChatKitAttachment` 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. - `"image"` - `"file"` - `content: array of object { text, type } or object { text, type }` Ordered content elements supplied by the user. - `input_text: 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`. - `quoted_text: 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"` - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` Assistant-authored message within a thread. - `id: string` Identifier of the thread item. - `content: array of ChatKitResponseOutputText` Ordered assistant response segments. - `annotations: array of object { source, type } or object { source, type }` Ordered list of annotations attached to the response text. - `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`. - `chatkit_widget_item: 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. - `chatkit.client_tool_call: 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. - `"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`. - `chatkit.task: 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. - `"custom"` - `"thought"` - `thread_id: string` Identifier of the parent thread. - `type: "chatkit.task"` Type discriminator that is always `chatkit.task`. - `chatkit.task_group: 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. - `"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`. ### ChatKit Thread User Message Item - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` User-authored messages within a thread. - `id: string` Identifier of the thread item. - `attachments: array of ChatKitAttachment` 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. - `"image"` - `"file"` - `content: array of object { text, type } or object { text, type }` Ordered content elements supplied by the user. - `input_text: 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`. - `quoted_text: 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"` ### ChatKit Widget Item - `chatkit_widget_item: 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.