# ChatKit ## Domain Types ### ChatKit Workflow - `class ChatKitWorkflow: …` Workflow metadata and state returned for the session. - `id: str` Identifier of the workflow backing the session. - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `str` - `bool` - `float` - `tracing: Tracing` Tracing settings applied to the workflow. - `enabled: bool` Indicates whether tracing is enabled. - `version: Optional[str]` Specific workflow version used for the session. Defaults to null when using the latest deployment. # Sessions ## Cancel chat session `beta.chatkit.sessions.cancel(strsession_id) -> ChatSession` **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: str` ### Returns - `class ChatSession: …` Represents a ChatKit session and its resolved configuration. - `id: str` Identifier for the ChatKit session. - `chatkit_configuration: ChatSessionChatKitConfiguration` Resolved ChatKit feature configuration for the session. - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` Automatic thread titling preferences. - `enabled: bool` Whether automatic thread titling is enabled. - `file_upload: ChatSessionFileUpload` Upload settings for the session. - `enabled: bool` Indicates if uploads are enabled for the session. - `max_file_size: Optional[int]` Maximum upload size in megabytes. - `max_files: Optional[int]` Maximum number of uploads allowed during the session. - `history: ChatSessionHistory` History retention configuration. - `enabled: bool` Indicates if chat history is persisted for the session. - `recent_threads: Optional[int]` Number of prior threads surfaced in history views. Defaults to null when all history is retained. - `client_secret: str` Ephemeral client secret that authenticates session requests. - `expires_at: int` Unix timestamp (in seconds) for when the session expires. - `max_requests_per_1_minute: int` Convenience copy of the per-minute request limit. - `object: Literal["chatkit.session"]` Type discriminator that is always `chatkit.session`. - `"chatkit.session"` - `rate_limits: ChatSessionRateLimits` Resolved rate limit values. - `max_requests_per_1_minute: int` Maximum allowed requests per one-minute window. - `status: ChatSessionStatus` Current lifecycle state of the session. - `"active"` - `"expired"` - `"cancelled"` - `user: str` User identifier associated with the session. - `workflow: ChatKitWorkflow` Workflow metadata for the session. - `id: str` Identifier of the workflow backing the session. - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `str` - `bool` - `float` - `tracing: Tracing` Tracing settings applied to the workflow. - `enabled: bool` Indicates whether tracing is enabled. - `version: Optional[str]` Specific workflow version used for the session. Defaults to null when using the latest deployment. ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) chat_session = client.beta.chatkit.sessions.cancel( "cksess_123", ) print(chat_session.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" } } ``` ### Example ```python from openai import OpenAI client = OpenAI() chat_session = client.beta.chatkit.sessions.cancel( "cksess_123", ) print(chat_session.id) ``` #### Response ```json { "id": "cksess_123", "object": "chatkit.session", "workflow": { "id": "workflow_alpha", "version": "1" }, "scope": { "customer_id": "cust_456" }, "max_requests_per_1_minute": 30, "ttl_seconds": 900, "status": "cancelled", "cancelled_at": 1712345678 } ``` ## Create ChatKit session `beta.chatkit.sessions.create(SessionCreateParams**kwargs) -> ChatSession` **post** `/chatkit/sessions` Create a ChatKit session. ### Parameters - `user: str` A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - `workflow: ChatSessionWorkflowParam` Workflow that powers the session. - `id: str` Identifier for the workflow invoked by the session. - `state_variables: Optional[Dict[str, Union[str, 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. - `str` - `bool` - `float` - `tracing: Optional[Tracing]` Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - `enabled: Optional[bool]` Whether tracing is enabled during the session. Defaults to true. - `version: Optional[str]` Specific workflow version to run. Defaults to the latest deployed version. - `chatkit_configuration: Optional[ChatSessionChatKitConfigurationParam]` Optional overrides for ChatKit runtime configuration features - `automatic_thread_titling: Optional[AutomaticThreadTitling]` Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - `enabled: Optional[bool]` Enable automatic thread title generation. Defaults to true. - `file_upload: Optional[FileUpload]` Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - `enabled: Optional[bool]` Enable uploads for this session. Defaults to false. - `max_file_size: Optional[int]` Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - `max_files: Optional[int]` Maximum number of files that can be uploaded to the session. Defaults to 10. - `history: Optional[History]` Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - `enabled: Optional[bool]` Enables chat users to access previous ChatKit threads. Defaults to true. - `recent_threads: Optional[int]` Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - `expires_after: Optional[ChatSessionExpiresAfterParam]` Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - `anchor: Literal["created_at"]` Base timestamp used to calculate expiration. Currently fixed to `created_at`. - `"created_at"` - `seconds: int` Number of seconds after the anchor when the session expires. - `rate_limits: Optional[ChatSessionRateLimitsParam]` Optional override for per-minute request limits. When omitted, defaults to 10. - `max_requests_per_1_minute: Optional[int]` Maximum number of requests allowed per minute for the session. Defaults to 10. ### Returns - `class ChatSession: …` Represents a ChatKit session and its resolved configuration. - `id: str` Identifier for the ChatKit session. - `chatkit_configuration: ChatSessionChatKitConfiguration` Resolved ChatKit feature configuration for the session. - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` Automatic thread titling preferences. - `enabled: bool` Whether automatic thread titling is enabled. - `file_upload: ChatSessionFileUpload` Upload settings for the session. - `enabled: bool` Indicates if uploads are enabled for the session. - `max_file_size: Optional[int]` Maximum upload size in megabytes. - `max_files: Optional[int]` Maximum number of uploads allowed during the session. - `history: ChatSessionHistory` History retention configuration. - `enabled: bool` Indicates if chat history is persisted for the session. - `recent_threads: Optional[int]` Number of prior threads surfaced in history views. Defaults to null when all history is retained. - `client_secret: str` Ephemeral client secret that authenticates session requests. - `expires_at: int` Unix timestamp (in seconds) for when the session expires. - `max_requests_per_1_minute: int` Convenience copy of the per-minute request limit. - `object: Literal["chatkit.session"]` Type discriminator that is always `chatkit.session`. - `"chatkit.session"` - `rate_limits: ChatSessionRateLimits` Resolved rate limit values. - `max_requests_per_1_minute: int` Maximum allowed requests per one-minute window. - `status: ChatSessionStatus` Current lifecycle state of the session. - `"active"` - `"expired"` - `"cancelled"` - `user: str` User identifier associated with the session. - `workflow: ChatKitWorkflow` Workflow metadata for the session. - `id: str` Identifier of the workflow backing the session. - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `str` - `bool` - `float` - `tracing: Tracing` Tracing settings applied to the workflow. - `enabled: bool` Indicates whether tracing is enabled. - `version: Optional[str]` Specific workflow version used for the session. Defaults to null when using the latest deployment. ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) chat_session = client.beta.chatkit.sessions.create( user="x", workflow={ "id": "id" }, ) print(chat_session.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" } } ``` ### Example ```python from openai import OpenAI client = OpenAI() chat_session = client.beta.chatkit.sessions.create( user="user", workflow={ "id": "id" }, ) print(chat_session.id) ``` #### Response ```json { "client_secret": "chatkit_token_123", "expires_at": 1735689600, "workflow": { "id": "workflow_alpha", "version": "2024-10-01" }, "scope": { "project": "alpha", "environment": "staging" }, "max_requests_per_1_minute": 60, "max_requests_per_session": 500, "status": "active" } ``` # Threads ## List ChatKit thread items `beta.chatkit.threads.list_items(strthread_id, ThreadListItemsParams**kwargs) -> SyncConversationCursorPage[Data]` **get** `/chatkit/threads/{thread_id}/items` List items that belong to a ChatKit thread. ### Parameters - `thread_id: str` - `after: Optional[str]` List items created after this thread item ID. Defaults to null for the first page. - `before: Optional[str]` List items created before this thread item ID. Defaults to null for the newest results. - `limit: Optional[int]` Maximum number of thread items to return. Defaults to 20. - `order: Optional[Literal["asc", "desc"]]` Sort order for results by creation time. Defaults to `desc`. - `"asc"` - `"desc"` ### Returns - `Data` - `class ChatKitThreadUserMessageItem: …` User-authored messages within a thread. - `id: str` Identifier of the thread item. - `attachments: List[ChatKitAttachment]` Attachments associated with the user message. Defaults to an empty list. - `id: str` Identifier for the attachment. - `mime_type: str` MIME type of the attachment. - `name: str` Original display name for the attachment. - `preview_url: Optional[str]` Preview URL for rendering the attachment inline. - `type: Literal["image", "file"]` Attachment discriminator. - `"image"` - `"file"` - `content: List[Content]` Ordered content elements supplied by the user. - `class ContentInputText: …` Text block that a user contributed to the thread. - `text: str` Plain-text content supplied by the user. - `type: Literal["input_text"]` Type discriminator that is always `input_text`. - `"input_text"` - `class ContentQuotedText: …` Quoted snippet that the user referenced in their message. - `text: str` Quoted text content. - `type: Literal["quoted_text"]` Type discriminator that is always `quoted_text`. - `"quoted_text"` - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `inference_options: Optional[InferenceOptions]` Inference overrides applied to the message. Defaults to null when unset. - `model: Optional[str]` Model name that generated the response. Defaults to null when using the session default. - `tool_choice: Optional[InferenceOptionsToolChoice]` Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - `id: str` Identifier of the requested tool. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.user_message"]` - `"chatkit.user_message"` - `class ChatKitThreadAssistantMessageItem: …` Assistant-authored message within a thread. - `id: str` Identifier of the thread item. - `content: List[ChatKitResponseOutputText]` Ordered assistant response segments. - `annotations: List[Annotation]` Ordered list of annotations attached to the response text. - `class AnnotationFile: …` Annotation that references an uploaded file. - `source: AnnotationFileSource` File attachment referenced by the annotation. - `filename: str` Filename referenced by the annotation. - `type: Literal["file"]` Type discriminator that is always `file`. - `"file"` - `type: Literal["file"]` Type discriminator that is always `file` for this annotation. - `"file"` - `class AnnotationURL: …` Annotation that references a URL. - `source: AnnotationURLSource` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url`. - `"url"` - `url: str` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url` for this annotation. - `"url"` - `text: str` Assistant generated text. - `type: Literal["output_text"]` Type discriminator that is always `output_text`. - `"output_text"` - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.assistant_message"]` Type discriminator that is always `chatkit.assistant_message`. - `"chatkit.assistant_message"` - `class ChatKitWidgetItem: …` Thread item that renders a widget payload. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.widget"]` Type discriminator that is always `chatkit.widget`. - `"chatkit.widget"` - `widget: str` Serialized widget payload rendered in the UI. - `class DataChatKitClientToolCall: …` Record of a client side tool invocation initiated by the assistant. - `id: str` Identifier of the thread item. - `arguments: str` JSON-encoded arguments that were sent to the tool. - `call_id: str` Identifier for the client tool call. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `name: str` Tool name that was invoked. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `output: Optional[str]` JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - `status: Literal["in_progress", "completed"]` Execution status for the tool call. - `"in_progress"` - `"completed"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.client_tool_call"]` Type discriminator that is always `chatkit.client_tool_call`. - `"chatkit.client_tool_call"` - `class DataChatKitTask: …` Task emitted by the workflow to show progress and status updates. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `heading: Optional[str]` Optional heading for the task. Defaults to null when not provided. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `summary: Optional[str]` Optional summary that describes the task. Defaults to null when omitted. - `task_type: Literal["custom", "thought"]` Subtype for the task. - `"custom"` - `"thought"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.task"]` Type discriminator that is always `chatkit.task`. - `"chatkit.task"` - `class DataChatKitTaskGroup: …` Collection of workflow tasks grouped together in the thread. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `tasks: List[DataChatKitTaskGroupTask]` Tasks included in the group. - `heading: Optional[str]` Optional heading for the grouped task. Defaults to null when not provided. - `summary: Optional[str]` Optional summary that describes the grouped task. Defaults to null when omitted. - `type: Literal["custom", "thought"]` Subtype for the grouped task. - `"custom"` - `"thought"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.task_group"]` Type discriminator that is always `chatkit.task_group`. - `"chatkit.task_group"` ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) page = client.beta.chatkit.threads.list_items( thread_id="cthr_123", ) page = page.data[0] print(page) ``` #### Response ```json { "data": [ { "id": "id", "attachments": [ { "id": "id", "mime_type": "mime_type", "name": "name", "preview_url": "preview_url", "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" } ``` ### Example ```python from openai import OpenAI client = OpenAI() page = client.beta.chatkit.threads.list_items( thread_id="cthr_123", ) page = page.data[0] print(page) ``` #### Response ```json { "data": [ { "id": "cthi_user_001", "object": "chatkit.thread_item", "type": "user_message", "content": [ { "type": "input_text", "text": "I need help debugging an onboarding issue." } ], "attachments": [] }, { "id": "cthi_assistant_002", "object": "chatkit.thread_item", "type": "assistant_message", "content": [ { "type": "output_text", "text": "Let's start by confirming the workflow version you deployed." } ] } ], "has_more": false, "object": "list" } ``` ## Retrieve ChatKit thread `beta.chatkit.threads.retrieve(strthread_id) -> ChatKitThread` **get** `/chatkit/threads/{thread_id}` Retrieve a ChatKit thread by its identifier. ### Parameters - `thread_id: str` ### Returns - `class ChatKitThread: …` Represents a ChatKit thread and its current status. - `id: str` Identifier of the thread. - `created_at: int` Unix timestamp (in seconds) for when the thread was created. - `object: Literal["chatkit.thread"]` Type discriminator that is always `chatkit.thread`. - `"chatkit.thread"` - `status: Status` Current status for the thread. Defaults to `active` for newly created threads. - `class StatusActive: …` Indicates that a thread is active. - `type: Literal["active"]` Status discriminator that is always `active`. - `"active"` - `class StatusLocked: …` Indicates that a thread is locked and cannot accept new input. - `reason: Optional[str]` Reason that the thread was locked. Defaults to null when no reason is recorded. - `type: Literal["locked"]` Status discriminator that is always `locked`. - `"locked"` - `class StatusClosed: …` Indicates that a thread has been closed. - `reason: Optional[str]` Reason that the thread was closed. Defaults to null when no reason is recorded. - `type: Literal["closed"]` Status discriminator that is always `closed`. - `"closed"` - `title: Optional[str]` Optional human-readable title for the thread. Defaults to null when no title has been generated. - `user: str` Free-form string that identifies your end user who owns the thread. ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) chatkit_thread = client.beta.chatkit.threads.retrieve( "cthr_123", ) print(chatkit_thread.id) ``` #### Response ```json { "id": "cthr_def456", "created_at": 1712345600, "object": "chatkit.thread", "status": { "type": "active" }, "title": "Demo feedback", "user": "user_456" } ``` ### Example ```python from openai import OpenAI client = OpenAI() chatkit_thread = client.beta.chatkit.threads.retrieve( "cthr_123", ) print(chatkit_thread.id) ``` #### Response ```json { "id": "cthr_abc123", "object": "chatkit.thread", "title": "Customer escalation", "items": { "data": [ { "id": "cthi_user_001", "object": "chatkit.thread_item", "type": "user_message", "content": [ { "type": "input_text", "text": "I need help debugging an onboarding issue." } ], "attachments": [] }, { "id": "cthi_assistant_002", "object": "chatkit.thread_item", "type": "assistant_message", "content": [ { "type": "output_text", "text": "Let's start by confirming the workflow version you deployed." } ] } ], "has_more": false } } ``` ## Delete ChatKit thread `beta.chatkit.threads.delete(strthread_id) -> ThreadDeleteResponse` **delete** `/chatkit/threads/{thread_id}` Delete a ChatKit thread along with its items and stored attachments. ### Parameters - `thread_id: str` ### Returns - `class ThreadDeleteResponse: …` Confirmation payload returned after deleting a thread. - `id: str` Identifier of the deleted thread. - `deleted: bool` Indicates that the thread has been deleted. - `object: Literal["chatkit.thread.deleted"]` Type discriminator that is always `chatkit.thread.deleted`. - `"chatkit.thread.deleted"` ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) thread = client.beta.chatkit.threads.delete( "cthr_123", ) print(thread.id) ``` #### Response ```json { "id": "id", "deleted": true, "object": "chatkit.thread.deleted" } ``` ### Example ```python from openai import OpenAI client = OpenAI() thread = client.beta.chat_kit.threads.delete( "cthr_123", ) print(thread.id) ``` ## List ChatKit threads `beta.chatkit.threads.list(ThreadListParams**kwargs) -> SyncConversationCursorPage[ChatKitThread]` **get** `/chatkit/threads` List ChatKit threads with optional pagination and user filters. ### Parameters - `after: Optional[str]` List items created after this thread item ID. Defaults to null for the first page. - `before: Optional[str]` List items created before this thread item ID. Defaults to null for the newest results. - `limit: Optional[int]` Maximum number of thread items to return. Defaults to 20. - `order: Optional[Literal["asc", "desc"]]` Sort order for results by creation time. Defaults to `desc`. - `"asc"` - `"desc"` - `user: Optional[str]` Filter threads that belong to this user identifier. Defaults to null to return all users. ### Returns - `class ChatKitThread: …` Represents a ChatKit thread and its current status. - `id: str` Identifier of the thread. - `created_at: int` Unix timestamp (in seconds) for when the thread was created. - `object: Literal["chatkit.thread"]` Type discriminator that is always `chatkit.thread`. - `"chatkit.thread"` - `status: Status` Current status for the thread. Defaults to `active` for newly created threads. - `class StatusActive: …` Indicates that a thread is active. - `type: Literal["active"]` Status discriminator that is always `active`. - `"active"` - `class StatusLocked: …` Indicates that a thread is locked and cannot accept new input. - `reason: Optional[str]` Reason that the thread was locked. Defaults to null when no reason is recorded. - `type: Literal["locked"]` Status discriminator that is always `locked`. - `"locked"` - `class StatusClosed: …` Indicates that a thread has been closed. - `reason: Optional[str]` Reason that the thread was closed. Defaults to null when no reason is recorded. - `type: Literal["closed"]` Status discriminator that is always `closed`. - `"closed"` - `title: Optional[str]` Optional human-readable title for the thread. Defaults to null when no title has been generated. - `user: str` Free-form string that identifies your end user who owns the thread. ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) page = client.beta.chatkit.threads.list() page = page.data[0] print(page.id) ``` #### 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" } ``` ### Example ```python from openai import OpenAI client = OpenAI() page = client.beta.chatkit.threads.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "cthr_abc123", "object": "chatkit.thread", "title": "Customer escalation" }, { "id": "cthr_def456", "object": "chatkit.thread", "title": "Demo feedback" } ], "has_more": false, "object": "list" } ``` ## Domain Types ### Chat Session - `class ChatSession: …` Represents a ChatKit session and its resolved configuration. - `id: str` Identifier for the ChatKit session. - `chatkit_configuration: ChatSessionChatKitConfiguration` Resolved ChatKit feature configuration for the session. - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` Automatic thread titling preferences. - `enabled: bool` Whether automatic thread titling is enabled. - `file_upload: ChatSessionFileUpload` Upload settings for the session. - `enabled: bool` Indicates if uploads are enabled for the session. - `max_file_size: Optional[int]` Maximum upload size in megabytes. - `max_files: Optional[int]` Maximum number of uploads allowed during the session. - `history: ChatSessionHistory` History retention configuration. - `enabled: bool` Indicates if chat history is persisted for the session. - `recent_threads: Optional[int]` Number of prior threads surfaced in history views. Defaults to null when all history is retained. - `client_secret: str` Ephemeral client secret that authenticates session requests. - `expires_at: int` Unix timestamp (in seconds) for when the session expires. - `max_requests_per_1_minute: int` Convenience copy of the per-minute request limit. - `object: Literal["chatkit.session"]` Type discriminator that is always `chatkit.session`. - `"chatkit.session"` - `rate_limits: ChatSessionRateLimits` Resolved rate limit values. - `max_requests_per_1_minute: int` Maximum allowed requests per one-minute window. - `status: ChatSessionStatus` Current lifecycle state of the session. - `"active"` - `"expired"` - `"cancelled"` - `user: str` User identifier associated with the session. - `workflow: ChatKitWorkflow` Workflow metadata for the session. - `id: str` Identifier of the workflow backing the session. - `state_variables: Optional[Dict[str, Union[str, bool, float]]]` State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `str` - `bool` - `float` - `tracing: Tracing` Tracing settings applied to the workflow. - `enabled: bool` Indicates whether tracing is enabled. - `version: Optional[str]` Specific workflow version used for the session. Defaults to null when using the latest deployment. ### Chat Session Automatic Thread Titling - `class ChatSessionAutomaticThreadTitling: …` Automatic thread title preferences for the session. - `enabled: bool` Whether automatic thread titling is enabled. ### Chat Session ChatKit Configuration - `class ChatSessionChatKitConfiguration: …` ChatKit configuration for the session. - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` Automatic thread titling preferences. - `enabled: bool` Whether automatic thread titling is enabled. - `file_upload: ChatSessionFileUpload` Upload settings for the session. - `enabled: bool` Indicates if uploads are enabled for the session. - `max_file_size: Optional[int]` Maximum upload size in megabytes. - `max_files: Optional[int]` Maximum number of uploads allowed during the session. - `history: ChatSessionHistory` History retention configuration. - `enabled: bool` Indicates if chat history is persisted for the session. - `recent_threads: Optional[int]` Number of prior threads surfaced in history views. Defaults to null when all history is retained. ### Chat Session ChatKit Configuration Param - `class ChatSessionChatKitConfigurationParam: …` Optional per-session configuration settings for ChatKit behavior. - `automatic_thread_titling: Optional[AutomaticThreadTitling]` Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - `enabled: Optional[bool]` Enable automatic thread title generation. Defaults to true. - `file_upload: Optional[FileUpload]` Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - `enabled: Optional[bool]` Enable uploads for this session. Defaults to false. - `max_file_size: Optional[int]` Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - `max_files: Optional[int]` Maximum number of files that can be uploaded to the session. Defaults to 10. - `history: Optional[History]` Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - `enabled: Optional[bool]` Enables chat users to access previous ChatKit threads. Defaults to true. - `recent_threads: Optional[int]` Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. ### Chat Session Expires After Param - `class ChatSessionExpiresAfterParam: …` Controls when the session expires relative to an anchor timestamp. - `anchor: Literal["created_at"]` Base timestamp used to calculate expiration. Currently fixed to `created_at`. - `"created_at"` - `seconds: int` Number of seconds after the anchor when the session expires. ### Chat Session File Upload - `class ChatSessionFileUpload: …` Upload permissions and limits applied to the session. - `enabled: bool` Indicates if uploads are enabled for the session. - `max_file_size: Optional[int]` Maximum upload size in megabytes. - `max_files: Optional[int]` Maximum number of uploads allowed during the session. ### Chat Session History - `class ChatSessionHistory: …` History retention preferences returned for the session. - `enabled: bool` Indicates if chat history is persisted for the session. - `recent_threads: Optional[int]` Number of prior threads surfaced in history views. Defaults to null when all history is retained. ### Chat Session Rate Limits - `class ChatSessionRateLimits: …` Active per-minute request limit for the session. - `max_requests_per_1_minute: int` Maximum allowed requests per one-minute window. ### Chat Session Rate Limits Param - `class ChatSessionRateLimitsParam: …` Controls request rate limits for the session. - `max_requests_per_1_minute: Optional[int]` Maximum number of requests allowed per minute for the session. Defaults to 10. ### Chat Session Status - `Literal["active", "expired", "cancelled"]` - `"active"` - `"expired"` - `"cancelled"` ### Chat Session Workflow Param - `class ChatSessionWorkflowParam: …` Workflow reference and overrides applied to the chat session. - `id: str` Identifier for the workflow invoked by the session. - `state_variables: Optional[Dict[str, Union[str, 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. - `str` - `bool` - `float` - `tracing: Optional[Tracing]` Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - `enabled: Optional[bool]` Whether tracing is enabled during the session. Defaults to true. - `version: Optional[str]` Specific workflow version to run. Defaults to the latest deployed version. ### ChatKit Attachment - `class ChatKitAttachment: …` Attachment metadata included on thread items. - `id: str` Identifier for the attachment. - `mime_type: str` MIME type of the attachment. - `name: str` Original display name for the attachment. - `preview_url: Optional[str]` Preview URL for rendering the attachment inline. - `type: Literal["image", "file"]` Attachment discriminator. - `"image"` - `"file"` ### ChatKit Response Output Text - `class ChatKitResponseOutputText: …` Assistant response text accompanied by optional annotations. - `annotations: List[Annotation]` Ordered list of annotations attached to the response text. - `class AnnotationFile: …` Annotation that references an uploaded file. - `source: AnnotationFileSource` File attachment referenced by the annotation. - `filename: str` Filename referenced by the annotation. - `type: Literal["file"]` Type discriminator that is always `file`. - `"file"` - `type: Literal["file"]` Type discriminator that is always `file` for this annotation. - `"file"` - `class AnnotationURL: …` Annotation that references a URL. - `source: AnnotationURLSource` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url`. - `"url"` - `url: str` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url` for this annotation. - `"url"` - `text: str` Assistant generated text. - `type: Literal["output_text"]` Type discriminator that is always `output_text`. - `"output_text"` ### ChatKit Thread - `class ChatKitThread: …` Represents a ChatKit thread and its current status. - `id: str` Identifier of the thread. - `created_at: int` Unix timestamp (in seconds) for when the thread was created. - `object: Literal["chatkit.thread"]` Type discriminator that is always `chatkit.thread`. - `"chatkit.thread"` - `status: Status` Current status for the thread. Defaults to `active` for newly created threads. - `class StatusActive: …` Indicates that a thread is active. - `type: Literal["active"]` Status discriminator that is always `active`. - `"active"` - `class StatusLocked: …` Indicates that a thread is locked and cannot accept new input. - `reason: Optional[str]` Reason that the thread was locked. Defaults to null when no reason is recorded. - `type: Literal["locked"]` Status discriminator that is always `locked`. - `"locked"` - `class StatusClosed: …` Indicates that a thread has been closed. - `reason: Optional[str]` Reason that the thread was closed. Defaults to null when no reason is recorded. - `type: Literal["closed"]` Status discriminator that is always `closed`. - `"closed"` - `title: Optional[str]` Optional human-readable title for the thread. Defaults to null when no title has been generated. - `user: str` Free-form string that identifies your end user who owns the thread. ### ChatKit Thread Assistant Message Item - `class ChatKitThreadAssistantMessageItem: …` Assistant-authored message within a thread. - `id: str` Identifier of the thread item. - `content: List[ChatKitResponseOutputText]` Ordered assistant response segments. - `annotations: List[Annotation]` Ordered list of annotations attached to the response text. - `class AnnotationFile: …` Annotation that references an uploaded file. - `source: AnnotationFileSource` File attachment referenced by the annotation. - `filename: str` Filename referenced by the annotation. - `type: Literal["file"]` Type discriminator that is always `file`. - `"file"` - `type: Literal["file"]` Type discriminator that is always `file` for this annotation. - `"file"` - `class AnnotationURL: …` Annotation that references a URL. - `source: AnnotationURLSource` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url`. - `"url"` - `url: str` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url` for this annotation. - `"url"` - `text: str` Assistant generated text. - `type: Literal["output_text"]` Type discriminator that is always `output_text`. - `"output_text"` - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.assistant_message"]` Type discriminator that is always `chatkit.assistant_message`. - `"chatkit.assistant_message"` ### ChatKit Thread Item List - `class ChatKitThreadItemList: …` A paginated list of thread items rendered for the ChatKit API. - `data: List[Data]` A list of items - `class ChatKitThreadUserMessageItem: …` User-authored messages within a thread. - `id: str` Identifier of the thread item. - `attachments: List[ChatKitAttachment]` Attachments associated with the user message. Defaults to an empty list. - `id: str` Identifier for the attachment. - `mime_type: str` MIME type of the attachment. - `name: str` Original display name for the attachment. - `preview_url: Optional[str]` Preview URL for rendering the attachment inline. - `type: Literal["image", "file"]` Attachment discriminator. - `"image"` - `"file"` - `content: List[Content]` Ordered content elements supplied by the user. - `class ContentInputText: …` Text block that a user contributed to the thread. - `text: str` Plain-text content supplied by the user. - `type: Literal["input_text"]` Type discriminator that is always `input_text`. - `"input_text"` - `class ContentQuotedText: …` Quoted snippet that the user referenced in their message. - `text: str` Quoted text content. - `type: Literal["quoted_text"]` Type discriminator that is always `quoted_text`. - `"quoted_text"` - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `inference_options: Optional[InferenceOptions]` Inference overrides applied to the message. Defaults to null when unset. - `model: Optional[str]` Model name that generated the response. Defaults to null when using the session default. - `tool_choice: Optional[InferenceOptionsToolChoice]` Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - `id: str` Identifier of the requested tool. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.user_message"]` - `"chatkit.user_message"` - `class ChatKitThreadAssistantMessageItem: …` Assistant-authored message within a thread. - `id: str` Identifier of the thread item. - `content: List[ChatKitResponseOutputText]` Ordered assistant response segments. - `annotations: List[Annotation]` Ordered list of annotations attached to the response text. - `class AnnotationFile: …` Annotation that references an uploaded file. - `source: AnnotationFileSource` File attachment referenced by the annotation. - `filename: str` Filename referenced by the annotation. - `type: Literal["file"]` Type discriminator that is always `file`. - `"file"` - `type: Literal["file"]` Type discriminator that is always `file` for this annotation. - `"file"` - `class AnnotationURL: …` Annotation that references a URL. - `source: AnnotationURLSource` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url`. - `"url"` - `url: str` URL referenced by the annotation. - `type: Literal["url"]` Type discriminator that is always `url` for this annotation. - `"url"` - `text: str` Assistant generated text. - `type: Literal["output_text"]` Type discriminator that is always `output_text`. - `"output_text"` - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.assistant_message"]` Type discriminator that is always `chatkit.assistant_message`. - `"chatkit.assistant_message"` - `class ChatKitWidgetItem: …` Thread item that renders a widget payload. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.widget"]` Type discriminator that is always `chatkit.widget`. - `"chatkit.widget"` - `widget: str` Serialized widget payload rendered in the UI. - `class DataChatKitClientToolCall: …` Record of a client side tool invocation initiated by the assistant. - `id: str` Identifier of the thread item. - `arguments: str` JSON-encoded arguments that were sent to the tool. - `call_id: str` Identifier for the client tool call. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `name: str` Tool name that was invoked. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `output: Optional[str]` JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - `status: Literal["in_progress", "completed"]` Execution status for the tool call. - `"in_progress"` - `"completed"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.client_tool_call"]` Type discriminator that is always `chatkit.client_tool_call`. - `"chatkit.client_tool_call"` - `class DataChatKitTask: …` Task emitted by the workflow to show progress and status updates. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `heading: Optional[str]` Optional heading for the task. Defaults to null when not provided. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `summary: Optional[str]` Optional summary that describes the task. Defaults to null when omitted. - `task_type: Literal["custom", "thought"]` Subtype for the task. - `"custom"` - `"thought"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.task"]` Type discriminator that is always `chatkit.task`. - `"chatkit.task"` - `class DataChatKitTaskGroup: …` Collection of workflow tasks grouped together in the thread. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `tasks: List[DataChatKitTaskGroupTask]` Tasks included in the group. - `heading: Optional[str]` Optional heading for the grouped task. Defaults to null when not provided. - `summary: Optional[str]` Optional summary that describes the grouped task. Defaults to null when omitted. - `type: Literal["custom", "thought"]` Subtype for the grouped task. - `"custom"` - `"thought"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.task_group"]` Type discriminator that is always `chatkit.task_group`. - `"chatkit.task_group"` - `first_id: Optional[str]` The ID of the first item in the list. - `has_more: bool` Whether there are more items available. - `last_id: Optional[str]` The ID of the last item in the list. - `object: Literal["list"]` The type of object returned, must be `list`. - `"list"` ### ChatKit Thread User Message Item - `class ChatKitThreadUserMessageItem: …` User-authored messages within a thread. - `id: str` Identifier of the thread item. - `attachments: List[ChatKitAttachment]` Attachments associated with the user message. Defaults to an empty list. - `id: str` Identifier for the attachment. - `mime_type: str` MIME type of the attachment. - `name: str` Original display name for the attachment. - `preview_url: Optional[str]` Preview URL for rendering the attachment inline. - `type: Literal["image", "file"]` Attachment discriminator. - `"image"` - `"file"` - `content: List[Content]` Ordered content elements supplied by the user. - `class ContentInputText: …` Text block that a user contributed to the thread. - `text: str` Plain-text content supplied by the user. - `type: Literal["input_text"]` Type discriminator that is always `input_text`. - `"input_text"` - `class ContentQuotedText: …` Quoted snippet that the user referenced in their message. - `text: str` Quoted text content. - `type: Literal["quoted_text"]` Type discriminator that is always `quoted_text`. - `"quoted_text"` - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `inference_options: Optional[InferenceOptions]` Inference overrides applied to the message. Defaults to null when unset. - `model: Optional[str]` Model name that generated the response. Defaults to null when using the session default. - `tool_choice: Optional[InferenceOptionsToolChoice]` Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - `id: str` Identifier of the requested tool. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.user_message"]` - `"chatkit.user_message"` ### ChatKit Widget Item - `class ChatKitWidgetItem: …` Thread item that renders a widget payload. - `id: str` Identifier of the thread item. - `created_at: int` Unix timestamp (in seconds) for when the item was created. - `object: Literal["chatkit.thread_item"]` Type discriminator that is always `chatkit.thread_item`. - `"chatkit.thread_item"` - `thread_id: str` Identifier of the parent thread. - `type: Literal["chatkit.widget"]` Type discriminator that is always `chatkit.widget`. - `"chatkit.widget"` - `widget: str` Serialized widget payload rendered in the UI.