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

openai beta:chatkit:sessions cancel \
  --api-key 'My API Key' \
  --session-id cksess_123

Response

{
  "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

openai beta:chatkit:sessions create \
  --api-key 'My API Key' \
  --user x \
  --workflow '{id: id}'

Response

{
  "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

openai beta:chatkit:threads list-items \
  --api-key 'My API Key' \
  --thread-id cthr_123

Response

{
  "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

openai beta:chatkit:threads retrieve \
  --api-key 'My API Key' \
  --thread-id cthr_123

Response

{
  "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

openai beta:chatkit:threads delete \
  --api-key 'My API Key' \
  --thread-id cthr_123

Response

{
  "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

openai beta:chatkit:threads list \
  --api-key 'My API Key'

Response

{
  "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: 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.

cli/resources/beta/subresources/chatkit/index.md +2178 −0 created

1# ChatKit

3## Domain Types

5### ChatKit Workflow

7- `chatkit_workflow: object { id, state_variables, tracing, version }`

9 Workflow metadata and state returned for the session.

11 - `id: string`

13 Identifier of the workflow backing the session.

15 - `state_variables: map[string or boolean or number]`

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

19 - `union_member_0: string`

21 - `union_member_1: boolean`

23 - `union_member_2: number`

25 - `tracing: object { enabled }`

27 Tracing settings applied to the workflow.

29 - `enabled: boolean`

31 Indicates whether tracing is enabled.

33 - `version: string`

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

37# Sessions

39## Cancel chat session

41`$ openai beta:chatkit:sessions cancel`

43**post** `/chatkit/sessions/{session_id}/cancel`

45Cancel an active ChatKit session and return its most recent metadata.

47Cancelling prevents new requests from using the issued client secret.

49### Parameters

51- `--session-id: string`

53 Unique identifier for the ChatKit session to cancel.

55### Returns

57- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }`

59 Represents a ChatKit session and its resolved configuration.

61 - `id: string`

63 Identifier for the ChatKit session.

65 - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }`

67 Resolved ChatKit feature configuration for the session.

69 - `automatic_thread_titling: object { enabled }`

71 Automatic thread titling preferences.

73 - `enabled: boolean`

75 Whether automatic thread titling is enabled.

77 - `file_upload: object { enabled, max_file_size, max_files }`

79 Upload settings for the session.

81 - `enabled: boolean`

83 Indicates if uploads are enabled for the session.

85 - `max_file_size: number`

87 Maximum upload size in megabytes.

89 - `max_files: number`

91 Maximum number of uploads allowed during the session.

93 - `history: object { enabled, recent_threads }`

95 History retention configuration.

97 - `enabled: boolean`

99 Indicates if chat history is persisted for the session.

100

101 - `recent_threads: number`

102

103 Number of prior threads surfaced in history views. Defaults to null when all history is retained.

104

105 - `client_secret: string`

106

107 Ephemeral client secret that authenticates session requests.

108

109 - `expires_at: number`

110

111 Unix timestamp (in seconds) for when the session expires.

112

113 - `max_requests_per_1_minute: number`

114

115 Convenience copy of the per-minute request limit.

116

117 - `object: "chatkit.session"`

118

119 Type discriminator that is always `chatkit.session`.

120

121 - `rate_limits: object { max_requests_per_1_minute }`

122

123 Resolved rate limit values.

124

125 - `max_requests_per_1_minute: number`

126

127 Maximum allowed requests per one-minute window.

128

129 - `status: "active" or "expired" or "cancelled"`

130

131 Current lifecycle state of the session.

132

133 - `"active"`

134

135 - `"expired"`

136

137 - `"cancelled"`

138

139 - `user: string`

140

141 User identifier associated with the session.

142

143 - `workflow: object { id, state_variables, tracing, version }`

144

145 Workflow metadata for the session.

146

147 - `id: string`

148

149 Identifier of the workflow backing the session.

150

151 - `state_variables: map[string or boolean or number]`

152

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

154

155 - `union_member_0: string`

156

157 - `union_member_1: boolean`

158

159 - `union_member_2: number`

160

161 - `tracing: object { enabled }`

162

163 Tracing settings applied to the workflow.

164

165 - `enabled: boolean`

166

167 Indicates whether tracing is enabled.

168

169 - `version: string`

170

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

172

173### Example

174

175```cli

176openai beta:chatkit:sessions cancel \

177 --api-key 'My API Key' \

178 --session-id cksess_123

179```

180

181#### Response

182

183```json

184{

185 "id": "id",

186 "chatkit_configuration": {

187 "automatic_thread_titling": {

188 "enabled": true

189 },

190 "file_upload": {

191 "enabled": true,

192 "max_file_size": 0,

193 "max_files": 0

194 },

195 "history": {

196 "enabled": true,

197 "recent_threads": 0

198 }

199 },

200 "client_secret": "client_secret",

201 "expires_at": 0,

202 "max_requests_per_1_minute": 0,

203 "object": "chatkit.session",

204 "rate_limits": {

205 "max_requests_per_1_minute": 0

206 },

207 "status": "active",

208 "user": "user",

209 "workflow": {

210 "id": "id",

211 "state_variables": {

212 "foo": "string"

213 },

214 "tracing": {

215 "enabled": true

216 },

217 "version": "version"

218 }

219}

220```

221

222## Create ChatKit session

223

224`$ openai beta:chatkit:sessions create`

225

226**post** `/chatkit/sessions`

227

228Create a ChatKit session.

229

230### Parameters

231

232- `--user: string`

233

234 A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.

235

236- `--workflow: object { id, state_variables, tracing, version }`

237

238 Workflow that powers the session.

239

240- `--chatkit-configuration: optional object { automatic_thread_titling, file_upload, history }`

241

242 Optional overrides for ChatKit runtime configuration features

243

244- `--expires-after: optional object { anchor, seconds }`

245

246 Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.

247

248- `--rate-limits: optional object { max_requests_per_1_minute }`

249

250 Optional override for per-minute request limits. When omitted, defaults to 10.

251

252### Returns

253

254- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }`

255

256 Represents a ChatKit session and its resolved configuration.

257

258 - `id: string`

259

260 Identifier for the ChatKit session.

261

262 - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }`

263

264 Resolved ChatKit feature configuration for the session.

265

266 - `automatic_thread_titling: object { enabled }`

267

268 Automatic thread titling preferences.

269

270 - `enabled: boolean`

271

272 Whether automatic thread titling is enabled.

273

274 - `file_upload: object { enabled, max_file_size, max_files }`

275

276 Upload settings for the session.

277

278 - `enabled: boolean`

279

280 Indicates if uploads are enabled for the session.

281

282 - `max_file_size: number`

283

284 Maximum upload size in megabytes.

285

286 - `max_files: number`

287

288 Maximum number of uploads allowed during the session.

289

290 - `history: object { enabled, recent_threads }`

291

292 History retention configuration.

293

294 - `enabled: boolean`

295

296 Indicates if chat history is persisted for the session.

297

298 - `recent_threads: number`

299

300 Number of prior threads surfaced in history views. Defaults to null when all history is retained.

301

302 - `client_secret: string`

303

304 Ephemeral client secret that authenticates session requests.

305

306 - `expires_at: number`

307

308 Unix timestamp (in seconds) for when the session expires.

309

310 - `max_requests_per_1_minute: number`

311

312 Convenience copy of the per-minute request limit.

313

314 - `object: "chatkit.session"`

315

316 Type discriminator that is always `chatkit.session`.

317

318 - `rate_limits: object { max_requests_per_1_minute }`

319

320 Resolved rate limit values.

321

322 - `max_requests_per_1_minute: number`

323

324 Maximum allowed requests per one-minute window.

325

326 - `status: "active" or "expired" or "cancelled"`

327

328 Current lifecycle state of the session.

329

330 - `"active"`

331

332 - `"expired"`

333

334 - `"cancelled"`

335

336 - `user: string`

337

338 User identifier associated with the session.

339

340 - `workflow: object { id, state_variables, tracing, version }`

341

342 Workflow metadata for the session.

343

344 - `id: string`

345

346 Identifier of the workflow backing the session.

347

348 - `state_variables: map[string or boolean or number]`

349

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

351

352 - `union_member_0: string`

353

354 - `union_member_1: boolean`

355

356 - `union_member_2: number`

357

358 - `tracing: object { enabled }`

359

360 Tracing settings applied to the workflow.

361

362 - `enabled: boolean`

363

364 Indicates whether tracing is enabled.

365

366 - `version: string`

367

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

369

370### Example

371

372```cli

373openai beta:chatkit:sessions create \

374 --api-key 'My API Key' \

375 --user x \

376 --workflow '{id: id}'

377```

378

379#### Response

380

381```json

382{

383 "id": "id",

384 "chatkit_configuration": {

385 "automatic_thread_titling": {

386 "enabled": true

387 },

388 "file_upload": {

389 "enabled": true,

390 "max_file_size": 0,

391 "max_files": 0

392 },

393 "history": {

394 "enabled": true,

395 "recent_threads": 0

396 }

397 },

398 "client_secret": "client_secret",

399 "expires_at": 0,

400 "max_requests_per_1_minute": 0,

401 "object": "chatkit.session",

402 "rate_limits": {

403 "max_requests_per_1_minute": 0

404 },

405 "status": "active",

406 "user": "user",

407 "workflow": {

408 "id": "id",

409 "state_variables": {

410 "foo": "string"

411 },

412 "tracing": {

413 "enabled": true

414 },

415 "version": "version"

416 }

417}

418```

419

420# Threads

421

422## List ChatKit thread items

423

424`$ openai beta:chatkit:threads list-items`

425

426**get** `/chatkit/threads/{thread_id}/items`

427

428List items that belong to a ChatKit thread.

429

430### Parameters

431

432- `--thread-id: string`

433

434 Identifier of the ChatKit thread whose items are requested.

435

436- `--after: optional string`

437

438 List items created after this thread item ID. Defaults to null for the first page.

439

440- `--before: optional string`

441

442 List items created before this thread item ID. Defaults to null for the newest results.

443

444- `--limit: optional number`

445

446 Maximum number of thread items to return. Defaults to 20.

447

448- `--order: optional "asc" or "desc"`

449

450 Sort order for results by creation time. Defaults to `desc`.

451

452### Returns

453

454- `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }`

455

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

457

458 - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more`

459

460 A list of items

461

462 - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }`

463

464 User-authored messages within a thread.

465

466 - `id: string`

467

468 Identifier of the thread item.

469

470 - `attachments: array of ChatKitAttachment`

471

472 Attachments associated with the user message. Defaults to an empty list.

473

474 - `id: string`

475

476 Identifier for the attachment.

477

478 - `mime_type: string`

479

480 MIME type of the attachment.

481

482 - `name: string`

483

484 Original display name for the attachment.

485

486 - `preview_url: string`

487

488 Preview URL for rendering the attachment inline.

489

490 - `type: "image" or "file"`

491

492 Attachment discriminator.

493

494 - `"image"`

495

496 - `"file"`

497

498 - `content: array of object { text, type } or object { text, type }`

499

500 Ordered content elements supplied by the user.

501

502 - `input_text: object { text, type }`

503

504 Text block that a user contributed to the thread.

505

506 - `text: string`

507

508 Plain-text content supplied by the user.

509

510 - `type: "input_text"`

511

512 Type discriminator that is always `input_text`.

513

514 - `quoted_text: object { text, type }`

515

516 Quoted snippet that the user referenced in their message.

517

518 - `text: string`

519

520 Quoted text content.

521

522 - `type: "quoted_text"`

523

524 Type discriminator that is always `quoted_text`.

525

526 - `created_at: number`

527

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

529

530 - `inference_options: object { model, tool_choice }`

531

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

533

534 - `model: string`

535

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

537

538 - `tool_choice: object { id }`

539

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

541

542 - `id: string`

543

544 Identifier of the requested tool.

545

546 - `object: "chatkit.thread_item"`

547

548 Type discriminator that is always `chatkit.thread_item`.

549

550 - `thread_id: string`

551

552 Identifier of the parent thread.

553

554 - `type: "chatkit.user_message"`

555

556 - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }`

557

558 Assistant-authored message within a thread.

559

560 - `id: string`

561

562 Identifier of the thread item.

563

564 - `content: array of ChatKitResponseOutputText`

565

566 Ordered assistant response segments.

567

568 - `annotations: array of object { source, type } or object { source, type }`

569

570 Ordered list of annotations attached to the response text.

571

572 - `file: object { source, type }`

573

574 Annotation that references an uploaded file.

575

576 - `source: object { filename, type }`

577

578 File attachment referenced by the annotation.

579

580 - `filename: string`

581

582 Filename referenced by the annotation.

583

584 - `type: "file"`

585

586 Type discriminator that is always `file`.

587

588 - `type: "file"`

589

590 Type discriminator that is always `file` for this annotation.

591

592 - `url: object { source, type }`

593

594 Annotation that references a URL.

595

596 - `source: object { type, url }`

597

598 URL referenced by the annotation.

599

600 - `type: "url"`

601

602 Type discriminator that is always `url`.

603

604 - `url: string`

605

606 URL referenced by the annotation.

607

608 - `type: "url"`

609

610 Type discriminator that is always `url` for this annotation.

611

612 - `text: string`

613

614 Assistant generated text.

615

616 - `type: "output_text"`

617

618 Type discriminator that is always `output_text`.

619

620 - `created_at: number`

621

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

623

624 - `object: "chatkit.thread_item"`

625

626 Type discriminator that is always `chatkit.thread_item`.

627

628 - `thread_id: string`

629

630 Identifier of the parent thread.

631

632 - `type: "chatkit.assistant_message"`

633

634 Type discriminator that is always `chatkit.assistant_message`.

635

636 - `chatkit_widget_item: object { id, created_at, object, 3 more }`

637

638 Thread item that renders a widget payload.

639

640 - `id: string`

641

642 Identifier of the thread item.

643

644 - `created_at: number`

645

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

647

648 - `object: "chatkit.thread_item"`

649

650 Type discriminator that is always `chatkit.thread_item`.

651

652 - `thread_id: string`

653

654 Identifier of the parent thread.

655

656 - `type: "chatkit.widget"`

657

658 Type discriminator that is always `chatkit.widget`.

659

660 - `widget: string`

661

662 Serialized widget payload rendered in the UI.

663

664 - `chatkit.client_tool_call: object { id, arguments, call_id, 7 more }`

665

666 Record of a client side tool invocation initiated by the assistant.

667

668 - `id: string`

669

670 Identifier of the thread item.

671

672 - `arguments: string`

673

674 JSON-encoded arguments that were sent to the tool.

675

676 - `call_id: string`

677

678 Identifier for the client tool call.

679

680 - `created_at: number`

681

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

683

684 - `name: string`

685

686 Tool name that was invoked.

687

688 - `object: "chatkit.thread_item"`

689

690 Type discriminator that is always `chatkit.thread_item`.

691

692 - `output: string`

693

694 JSON-encoded output captured from the tool. Defaults to null while execution is in progress.

695

696 - `status: "in_progress" or "completed"`

697

698 Execution status for the tool call.

699

700 - `"in_progress"`

701

702 - `"completed"`

703

704 - `thread_id: string`

705

706 Identifier of the parent thread.

707

708 - `type: "chatkit.client_tool_call"`

709

710 Type discriminator that is always `chatkit.client_tool_call`.

711

712 - `chatkit.task: object { id, created_at, heading, 5 more }`

713

714 Task emitted by the workflow to show progress and status updates.

715

716 - `id: string`

717

718 Identifier of the thread item.

719

720 - `created_at: number`

721

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

723

724 - `heading: string`

725

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

727

728 - `object: "chatkit.thread_item"`

729

730 Type discriminator that is always `chatkit.thread_item`.

731

732 - `summary: string`

733

734 Optional summary that describes the task. Defaults to null when omitted.

735

736 - `task_type: "custom" or "thought"`

737

738 Subtype for the task.

739

740 - `"custom"`

741

742 - `"thought"`

743

744 - `thread_id: string`

745

746 Identifier of the parent thread.

747

748 - `type: "chatkit.task"`

749

750 Type discriminator that is always `chatkit.task`.

751

752 - `chatkit.task_group: object { id, created_at, object, 3 more }`

753

754 Collection of workflow tasks grouped together in the thread.

755

756 - `id: string`

757

758 Identifier of the thread item.

759

760 - `created_at: number`

761

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

763

764 - `object: "chatkit.thread_item"`

765

766 Type discriminator that is always `chatkit.thread_item`.

767

768 - `tasks: array of object { heading, summary, type }`

769

770 Tasks included in the group.

771

772 - `heading: string`

773

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

775

776 - `summary: string`

777

778 Optional summary that describes the grouped task. Defaults to null when omitted.

779

780 - `type: "custom" or "thought"`

781

782 Subtype for the grouped task.

783

784 - `"custom"`

785

786 - `"thought"`

787

788 - `thread_id: string`

789

790 Identifier of the parent thread.

791

792 - `type: "chatkit.task_group"`

793

794 Type discriminator that is always `chatkit.task_group`.

795

796 - `first_id: string`

797

798 The ID of the first item in the list.

799

800 - `has_more: boolean`

801

802 Whether there are more items available.

803

804 - `last_id: string`

805

806 The ID of the last item in the list.

807

808 - `object: "list"`

809

810 The type of object returned, must be `list`.

811

812### Example

813

814```cli

815openai beta:chatkit:threads list-items \

816 --api-key 'My API Key' \

817 --thread-id cthr_123

818```

819

820#### Response

821

822```json

823{

824 "data": [

825 {

826 "id": "id",

827 "attachments": [

828 {

829 "id": "id",

830 "mime_type": "mime_type",

831 "name": "name",

832 "preview_url": "https://example.com",

833 "type": "image"

834 }

835 ],

836 "content": [

837 {

838 "text": "text",

839 "type": "input_text"

840 }

841 ],

842 "created_at": 0,

843 "inference_options": {

844 "model": "model",

845 "tool_choice": {

846 "id": "id"

847 }

848 },

849 "object": "chatkit.thread_item",

850 "thread_id": "thread_id",

851 "type": "chatkit.user_message"

852 }

853 ],

854 "first_id": "first_id",

855 "has_more": true,

856 "last_id": "last_id",

857 "object": "list"

858}

859```

860

861## Retrieve ChatKit thread

862

863`$ openai beta:chatkit:threads retrieve`

864

865**get** `/chatkit/threads/{thread_id}`

866

867Retrieve a ChatKit thread by its identifier.

868

869### Parameters

870

871- `--thread-id: string`

872

873 Identifier of the ChatKit thread to retrieve.

874

875### Returns

876

877- `chatkit_thread: object { id, created_at, object, 3 more }`

878

879 Represents a ChatKit thread and its current status.

880

881 - `id: string`

882

883 Identifier of the thread.

884

885 - `created_at: number`

886

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

888

889 - `object: "chatkit.thread"`

890

891 Type discriminator that is always `chatkit.thread`.

892

893 - `status: object { type } or object { reason, type } or object { reason, type }`

894

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

896

897 - `active: object { type }`

898

899 Indicates that a thread is active.

900

901 - `locked: object { reason, type }`

902

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

904

905 - `reason: string`

906

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

908

909 - `type: "locked"`

910

911 Status discriminator that is always `locked`.

912

913 - `closed: object { reason, type }`

914

915 Indicates that a thread has been closed.

916

917 - `reason: string`

918

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

920

921 - `type: "closed"`

922

923 Status discriminator that is always `closed`.

924

925 - `title: string`

926

927 Optional human-readable title for the thread. Defaults to null when no title has been generated.

928

929 - `user: string`

930

931 Free-form string that identifies your end user who owns the thread.

932

933### Example

934

935```cli

936openai beta:chatkit:threads retrieve \

937 --api-key 'My API Key' \

938 --thread-id cthr_123

939```

940

941#### Response

942

943```json

944{

945 "id": "cthr_def456",

946 "created_at": 1712345600,

947 "object": "chatkit.thread",

948 "status": {

949 "type": "active"

950 },

951 "title": "Demo feedback",

952 "user": "user_456"

953}

954```

955

956## Delete ChatKit thread

957

958`$ openai beta:chatkit:threads delete`

959

960**delete** `/chatkit/threads/{thread_id}`

961

962Delete a ChatKit thread along with its items and stored attachments.

963

964### Parameters

965

966- `--thread-id: string`

967

968 Identifier of the ChatKit thread to delete.

969

970### Returns

971

972- `BetaChatKitThreadDeleteResponse: object { id, deleted, object }`

973

974 Confirmation payload returned after deleting a thread.

975

976 - `id: string`

977

978 Identifier of the deleted thread.

979

980 - `deleted: boolean`

981

982 Indicates that the thread has been deleted.

983

984 - `object: "chatkit.thread.deleted"`

985

986 Type discriminator that is always `chatkit.thread.deleted`.

987

988### Example

989

990```cli

991openai beta:chatkit:threads delete \

992 --api-key 'My API Key' \

993 --thread-id cthr_123

994```

995

996#### Response

997

998```json

999{

1000 "id": "id",

1001 "deleted": true,

1002 "object": "chatkit.thread.deleted"

1003}

1004```

1005

1006## List ChatKit threads

1007

1008`$ openai beta:chatkit:threads list`

1009

1010**get** `/chatkit/threads`

1011

1012List ChatKit threads with optional pagination and user filters.

1013

1014### Parameters

1015

1016- `--after: optional string`

1017

1018 List items created after this thread item ID. Defaults to null for the first page.

1019

1020- `--before: optional string`

1021

1022 List items created before this thread item ID. Defaults to null for the newest results.

1023

1024- `--limit: optional number`

1025

1026 Maximum number of thread items to return. Defaults to 20.

1027

1028- `--order: optional "asc" or "desc"`

1029

1030 Sort order for results by creation time. Defaults to `desc`.

1031

1032- `--user: optional string`

1033

1034 Filter threads that belong to this user identifier. Defaults to null to return all users.

1035

1036### Returns

1037

1038- `Threads: object { data, first_id, has_more, 2 more }`

1039

1040 A paginated list of ChatKit threads.

1041

1042 - `data: array of ChatKitThread`

1043

1044 A list of items

1045

1046 - `id: string`

1047

1048 Identifier of the thread.

1049

1050 - `created_at: number`

1051

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

1053

1054 - `object: "chatkit.thread"`

1055

1056 Type discriminator that is always `chatkit.thread`.

1057

1058 - `status: object { type } or object { reason, type } or object { reason, type }`

1059

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

1061

1062 - `active: object { type }`

1063

1064 Indicates that a thread is active.

1065

1066 - `locked: object { reason, type }`

1067

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

1069

1070 - `reason: string`

1071

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

1073

1074 - `type: "locked"`

1075

1076 Status discriminator that is always `locked`.

1077

1078 - `closed: object { reason, type }`

1079

1080 Indicates that a thread has been closed.

1081

1082 - `reason: string`

1083

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

1085

1086 - `type: "closed"`

1087

1088 Status discriminator that is always `closed`.

1089

1090 - `title: string`

1091

1092 Optional human-readable title for the thread. Defaults to null when no title has been generated.

1093

1094 - `user: string`

1095

1096 Free-form string that identifies your end user who owns the thread.

1097

1098 - `first_id: string`

1099

1100 The ID of the first item in the list.

1101

1102 - `has_more: boolean`

1103

1104 Whether there are more items available.

1105

1106 - `last_id: string`

1107

1108 The ID of the last item in the list.

1109

1110 - `object: "list"`

1111

1112 The type of object returned, must be `list`.

1113

1114### Example

1115

1116```cli

1117openai beta:chatkit:threads list \

1118 --api-key 'My API Key'

1119```

1120

1121#### Response

1122

1123```json

1124{

1125 "data": [

1126 {

1127 "id": "cthr_def456",

1128 "created_at": 1712345600,

1129 "object": "chatkit.thread",

1130 "status": {

1131 "type": "active"

1132 },

1133 "title": "Demo feedback",

1134 "user": "user_456"

1135 }

1136 ],

1137 "first_id": "first_id",

1138 "has_more": true,

1139 "last_id": "last_id",

1140 "object": "list"

1141}

1142```

1143

1144## Domain Types

1145

1146### Chat Session

1147

1148- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }`

1149

1150 Represents a ChatKit session and its resolved configuration.

1151

1152 - `id: string`

1153

1154 Identifier for the ChatKit session.

1155

1156 - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }`

1157

1158 Resolved ChatKit feature configuration for the session.

1159

1160 - `automatic_thread_titling: object { enabled }`

1161

1162 Automatic thread titling preferences.

1163

1164 - `enabled: boolean`

1165

1166 Whether automatic thread titling is enabled.

1167

1168 - `file_upload: object { enabled, max_file_size, max_files }`

1169

1170 Upload settings for the session.

1171

1172 - `enabled: boolean`

1173

1174 Indicates if uploads are enabled for the session.

1175

1176 - `max_file_size: number`

1177

1178 Maximum upload size in megabytes.

1179

1180 - `max_files: number`

1181

1182 Maximum number of uploads allowed during the session.

1183

1184 - `history: object { enabled, recent_threads }`

1185

1186 History retention configuration.

1187

1188 - `enabled: boolean`

1189

1190 Indicates if chat history is persisted for the session.

1191

1192 - `recent_threads: number`

1193

1194 Number of prior threads surfaced in history views. Defaults to null when all history is retained.

1195

1196 - `client_secret: string`

1197

1198 Ephemeral client secret that authenticates session requests.

1199

1200 - `expires_at: number`

1201

1202 Unix timestamp (in seconds) for when the session expires.

1203

1204 - `max_requests_per_1_minute: number`

1205

1206 Convenience copy of the per-minute request limit.

1207

1208 - `object: "chatkit.session"`

1209

1210 Type discriminator that is always `chatkit.session`.

1211

1212 - `rate_limits: object { max_requests_per_1_minute }`

1213

1214 Resolved rate limit values.

1215

1216 - `max_requests_per_1_minute: number`

1217

1218 Maximum allowed requests per one-minute window.

1219

1220 - `status: "active" or "expired" or "cancelled"`

1221

1222 Current lifecycle state of the session.

1223

1224 - `"active"`

1225

1226 - `"expired"`

1227

1228 - `"cancelled"`

1229

1230 - `user: string`

1231

1232 User identifier associated with the session.

1233

1234 - `workflow: object { id, state_variables, tracing, version }`

1235

1236 Workflow metadata for the session.

1237

1238 - `id: string`

1239

1240 Identifier of the workflow backing the session.

1241

1242 - `state_variables: map[string or boolean or number]`

1243

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

1245

1246 - `union_member_0: string`

1247

1248 - `union_member_1: boolean`

1249

1250 - `union_member_2: number`

1251

1252 - `tracing: object { enabled }`

1253

1254 Tracing settings applied to the workflow.

1255

1256 - `enabled: boolean`

1257

1258 Indicates whether tracing is enabled.

1259

1260 - `version: string`

1261

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

1263

1264### Chat Session Automatic Thread Titling

1265

1266- `chat_session_automatic_thread_titling: object { enabled }`

1267

1268 Automatic thread title preferences for the session.

1269

1270 - `enabled: boolean`

1271

1272 Whether automatic thread titling is enabled.

1273

1274### Chat Session ChatKit Configuration

1275

1276- `chat_session_chatkit_configuration: object { automatic_thread_titling, file_upload, history }`

1277

1278 ChatKit configuration for the session.

1279

1280 - `automatic_thread_titling: object { enabled }`

1281

1282 Automatic thread titling preferences.

1283

1284 - `enabled: boolean`

1285

1286 Whether automatic thread titling is enabled.

1287

1288 - `file_upload: object { enabled, max_file_size, max_files }`

1289

1290 Upload settings for the session.

1291

1292 - `enabled: boolean`

1293

1294 Indicates if uploads are enabled for the session.

1295

1296 - `max_file_size: number`

1297

1298 Maximum upload size in megabytes.

1299

1300 - `max_files: number`

1301

1302 Maximum number of uploads allowed during the session.

1303

1304 - `history: object { enabled, recent_threads }`

1305

1306 History retention configuration.

1307

1308 - `enabled: boolean`

1309

1310 Indicates if chat history is persisted for the session.

1311

1312 - `recent_threads: number`

1313

1314 Number of prior threads surfaced in history views. Defaults to null when all history is retained.

1315

1316### Chat Session ChatKit Configuration Param

1317

1318- `chat_session_chatkit_configuration_param: object { automatic_thread_titling, file_upload, history }`

1319

1320 Optional per-session configuration settings for ChatKit behavior.

1321

1322 - `automatic_thread_titling: optional object { enabled }`

1323

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

1325

1326 - `enabled: optional boolean`

1327

1328 Enable automatic thread title generation. Defaults to true.

1329

1330 - `file_upload: optional object { enabled, max_file_size, max_files }`

1331

1332 Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).

1333

1334 - `enabled: optional boolean`

1335

1336 Enable uploads for this session. Defaults to false.

1337

1338 - `max_file_size: optional number`

1339

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

1341

1342 - `max_files: optional number`

1343

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

1345

1346 - `history: optional object { enabled, recent_threads }`

1347

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

1349

1350 - `enabled: optional boolean`

1351

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

1353

1354 - `recent_threads: optional number`

1355

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

1357

1358### Chat Session Expires After Param

1359

1360- `chat_session_expires_after_param: object { anchor, seconds }`

1361

1362 Controls when the session expires relative to an anchor timestamp.

1363

1364 - `anchor: "created_at"`

1365

1366 Base timestamp used to calculate expiration. Currently fixed to `created_at`.

1367

1368 - `seconds: number`

1369

1370 Number of seconds after the anchor when the session expires.

1371

1372### Chat Session File Upload

1373

1374- `chat_session_file_upload: object { enabled, max_file_size, max_files }`

1375

1376 Upload permissions and limits applied to the session.

1377

1378 - `enabled: boolean`

1379

1380 Indicates if uploads are enabled for the session.

1381

1382 - `max_file_size: number`

1383

1384 Maximum upload size in megabytes.

1385

1386 - `max_files: number`

1387

1388 Maximum number of uploads allowed during the session.

1389

1390### Chat Session History

1391

1392- `chat_session_history: object { enabled, recent_threads }`

1393

1394 History retention preferences returned for the session.

1395

1396 - `enabled: boolean`

1397

1398 Indicates if chat history is persisted for the session.

1399

1400 - `recent_threads: number`

1401

1402 Number of prior threads surfaced in history views. Defaults to null when all history is retained.

1403

1404### Chat Session Rate Limits

1405

1406- `chat_session_rate_limits: object { max_requests_per_1_minute }`

1407

1408 Active per-minute request limit for the session.

1409

1410 - `max_requests_per_1_minute: number`

1411

1412 Maximum allowed requests per one-minute window.

1413

1414### Chat Session Rate Limits Param

1415

1416- `chat_session_rate_limits_param: object { max_requests_per_1_minute }`

1417

1418 Controls request rate limits for the session.

1419

1420 - `max_requests_per_1_minute: optional number`

1421

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

1423

1424### Chat Session Status

1425

1426- `chat_session_status: "active" or "expired" or "cancelled"`

1427

1428 - `"active"`

1429

1430 - `"expired"`

1431

1432 - `"cancelled"`

1433

1434### Chat Session Workflow Param

1435

1436- `chat_session_workflow_param: object { id, state_variables, tracing, version }`

1437

1438 Workflow reference and overrides applied to the chat session.

1439

1440 - `id: string`

1441

1442 Identifier for the workflow invoked by the session.

1443

1444 - `state_variables: optional map[string or boolean or number]`

1445

1446 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.

1447

1448 - `union_member_0: string`

1449

1450 - `union_member_1: boolean`

1451

1452 - `union_member_2: number`

1453

1454 - `tracing: optional object { enabled }`

1455

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

1457

1458 - `enabled: optional boolean`

1459

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

1461

1462 - `version: optional string`

1463

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

1465

1466### ChatKit Attachment

1467

1468- `chatkit_attachment: object { id, mime_type, name, 2 more }`

1469

1470 Attachment metadata included on thread items.

1471

1472 - `id: string`

1473

1474 Identifier for the attachment.

1475

1476 - `mime_type: string`

1477

1478 MIME type of the attachment.

1479

1480 - `name: string`

1481

1482 Original display name for the attachment.

1483

1484 - `preview_url: string`

1485

1486 Preview URL for rendering the attachment inline.

1487

1488 - `type: "image" or "file"`

1489

1490 Attachment discriminator.

1491

1492 - `"image"`

1493

1494 - `"file"`

1495

1496### ChatKit Response Output Text

1497

1498- `chatkit_response_output_text: object { annotations, text, type }`

1499

1500 Assistant response text accompanied by optional annotations.

1501

1502 - `annotations: array of object { source, type } or object { source, type }`

1503

1504 Ordered list of annotations attached to the response text.

1505

1506 - `file: object { source, type }`

1507

1508 Annotation that references an uploaded file.

1509

1510 - `source: object { filename, type }`

1511

1512 File attachment referenced by the annotation.

1513

1514 - `filename: string`

1515

1516 Filename referenced by the annotation.

1517

1518 - `type: "file"`

1519

1520 Type discriminator that is always `file`.

1521

1522 - `type: "file"`

1523

1524 Type discriminator that is always `file` for this annotation.

1525

1526 - `url: object { source, type }`

1527

1528 Annotation that references a URL.

1529

1530 - `source: object { type, url }`

1531

1532 URL referenced by the annotation.

1533

1534 - `type: "url"`

1535

1536 Type discriminator that is always `url`.

1537

1538 - `url: string`

1539

1540 URL referenced by the annotation.

1541

1542 - `type: "url"`

1543

1544 Type discriminator that is always `url` for this annotation.

1545

1546 - `text: string`

1547

1548 Assistant generated text.

1549

1550 - `type: "output_text"`

1551

1552 Type discriminator that is always `output_text`.

1553

1554### ChatKit Thread

1555

1556- `chatkit_thread: object { id, created_at, object, 3 more }`

1557

1558 Represents a ChatKit thread and its current status.

1559

1560 - `id: string`

1561

1562 Identifier of the thread.

1563

1564 - `created_at: number`

1565

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

1567

1568 - `object: "chatkit.thread"`

1569

1570 Type discriminator that is always `chatkit.thread`.

1571

1572 - `status: object { type } or object { reason, type } or object { reason, type }`

1573

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

1575

1576 - `active: object { type }`

1577

1578 Indicates that a thread is active.

1579

1580 - `locked: object { reason, type }`

1581

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

1583

1584 - `reason: string`

1585

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

1587

1588 - `type: "locked"`

1589

1590 Status discriminator that is always `locked`.

1591

1592 - `closed: object { reason, type }`

1593

1594 Indicates that a thread has been closed.

1595

1596 - `reason: string`

1597

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

1599

1600 - `type: "closed"`

1601

1602 Status discriminator that is always `closed`.

1603

1604 - `title: string`

1605

1606 Optional human-readable title for the thread. Defaults to null when no title has been generated.

1607

1608 - `user: string`

1609

1610 Free-form string that identifies your end user who owns the thread.

1611

1612### ChatKit Thread Assistant Message Item

1613

1614- `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }`

1615

1616 Assistant-authored message within a thread.

1617

1618 - `id: string`

1619

1620 Identifier of the thread item.

1621

1622 - `content: array of ChatKitResponseOutputText`

1623

1624 Ordered assistant response segments.

1625

1626 - `annotations: array of object { source, type } or object { source, type }`

1627

1628 Ordered list of annotations attached to the response text.

1629

1630 - `file: object { source, type }`

1631

1632 Annotation that references an uploaded file.

1633

1634 - `source: object { filename, type }`

1635

1636 File attachment referenced by the annotation.

1637

1638 - `filename: string`

1639

1640 Filename referenced by the annotation.

1641

1642 - `type: "file"`

1643

1644 Type discriminator that is always `file`.

1645

1646 - `type: "file"`

1647

1648 Type discriminator that is always `file` for this annotation.

1649

1650 - `url: object { source, type }`

1651

1652 Annotation that references a URL.

1653

1654 - `source: object { type, url }`

1655

1656 URL referenced by the annotation.

1657

1658 - `type: "url"`

1659

1660 Type discriminator that is always `url`.

1661

1662 - `url: string`

1663

1664 URL referenced by the annotation.

1665

1666 - `type: "url"`

1667

1668 Type discriminator that is always `url` for this annotation.

1669

1670 - `text: string`

1671

1672 Assistant generated text.

1673

1674 - `type: "output_text"`

1675

1676 Type discriminator that is always `output_text`.

1677

1678 - `created_at: number`

1679

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

1681

1682 - `object: "chatkit.thread_item"`

1683

1684 Type discriminator that is always `chatkit.thread_item`.

1685

1686 - `thread_id: string`

1687

1688 Identifier of the parent thread.

1689

1690 - `type: "chatkit.assistant_message"`

1691

1692 Type discriminator that is always `chatkit.assistant_message`.

1693

1694### ChatKit Thread Item List

1695

1696- `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }`

1697

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

1699

1700 - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more`

1701

1702 A list of items

1703

1704 - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }`

1705

1706 User-authored messages within a thread.

1707

1708 - `id: string`

1709

1710 Identifier of the thread item.

1711

1712 - `attachments: array of ChatKitAttachment`

1713

1714 Attachments associated with the user message. Defaults to an empty list.

1715

1716 - `id: string`

1717

1718 Identifier for the attachment.

1719

1720 - `mime_type: string`

1721

1722 MIME type of the attachment.

1723

1724 - `name: string`

1725

1726 Original display name for the attachment.

1727

1728 - `preview_url: string`

1729

1730 Preview URL for rendering the attachment inline.

1731

1732 - `type: "image" or "file"`

1733

1734 Attachment discriminator.

1735

1736 - `"image"`

1737

1738 - `"file"`

1739

1740 - `content: array of object { text, type } or object { text, type }`

1741

1742 Ordered content elements supplied by the user.

1743

1744 - `input_text: object { text, type }`

1745

1746 Text block that a user contributed to the thread.

1747

1748 - `text: string`

1749

1750 Plain-text content supplied by the user.

1751

1752 - `type: "input_text"`

1753

1754 Type discriminator that is always `input_text`.

1755

1756 - `quoted_text: object { text, type }`

1757

1758 Quoted snippet that the user referenced in their message.

1759

1760 - `text: string`

1761

1762 Quoted text content.

1763

1764 - `type: "quoted_text"`

1765

1766 Type discriminator that is always `quoted_text`.

1767

1768 - `created_at: number`

1769

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

1771

1772 - `inference_options: object { model, tool_choice }`

1773

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

1775

1776 - `model: string`

1777

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

1779

1780 - `tool_choice: object { id }`

1781

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

1783

1784 - `id: string`

1785

1786 Identifier of the requested tool.

1787

1788 - `object: "chatkit.thread_item"`

1789

1790 Type discriminator that is always `chatkit.thread_item`.

1791

1792 - `thread_id: string`

1793

1794 Identifier of the parent thread.

1795

1796 - `type: "chatkit.user_message"`

1797

1798 - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }`

1799

1800 Assistant-authored message within a thread.

1801

1802 - `id: string`

1803

1804 Identifier of the thread item.

1805

1806 - `content: array of ChatKitResponseOutputText`

1807

1808 Ordered assistant response segments.

1809

1810 - `annotations: array of object { source, type } or object { source, type }`

1811

1812 Ordered list of annotations attached to the response text.

1813

1814 - `file: object { source, type }`

1815

1816 Annotation that references an uploaded file.

1817

1818 - `source: object { filename, type }`

1819

1820 File attachment referenced by the annotation.

1821

1822 - `filename: string`

1823

1824 Filename referenced by the annotation.

1825

1826 - `type: "file"`

1827

1828 Type discriminator that is always `file`.

1829

1830 - `type: "file"`

1831

1832 Type discriminator that is always `file` for this annotation.

1833

1834 - `url: object { source, type }`

1835

1836 Annotation that references a URL.

1837

1838 - `source: object { type, url }`

1839

1840 URL referenced by the annotation.

1841

1842 - `type: "url"`

1843

1844 Type discriminator that is always `url`.

1845

1846 - `url: string`

1847

1848 URL referenced by the annotation.

1849

1850 - `type: "url"`

1851

1852 Type discriminator that is always `url` for this annotation.

1853

1854 - `text: string`

1855

1856 Assistant generated text.

1857

1858 - `type: "output_text"`

1859

1860 Type discriminator that is always `output_text`.

1861

1862 - `created_at: number`

1863

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

1865

1866 - `object: "chatkit.thread_item"`

1867

1868 Type discriminator that is always `chatkit.thread_item`.

1869

1870 - `thread_id: string`

1871

1872 Identifier of the parent thread.

1873

1874 - `type: "chatkit.assistant_message"`

1875

1876 Type discriminator that is always `chatkit.assistant_message`.

1877

1878 - `chatkit_widget_item: object { id, created_at, object, 3 more }`

1879

1880 Thread item that renders a widget payload.

1881

1882 - `id: string`

1883

1884 Identifier of the thread item.

1885

1886 - `created_at: number`

1887

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

1889

1890 - `object: "chatkit.thread_item"`

1891

1892 Type discriminator that is always `chatkit.thread_item`.

1893

1894 - `thread_id: string`

1895

1896 Identifier of the parent thread.

1897

1898 - `type: "chatkit.widget"`

1899

1900 Type discriminator that is always `chatkit.widget`.

1901

1902 - `widget: string`

1903

1904 Serialized widget payload rendered in the UI.

1905

1906 - `chatkit.client_tool_call: object { id, arguments, call_id, 7 more }`

1907

1908 Record of a client side tool invocation initiated by the assistant.

1909

1910 - `id: string`

1911

1912 Identifier of the thread item.

1913

1914 - `arguments: string`

1915

1916 JSON-encoded arguments that were sent to the tool.

1917

1918 - `call_id: string`

1919

1920 Identifier for the client tool call.

1921

1922 - `created_at: number`

1923

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

1925

1926 - `name: string`

1927

1928 Tool name that was invoked.

1929

1930 - `object: "chatkit.thread_item"`

1931

1932 Type discriminator that is always `chatkit.thread_item`.

1933

1934 - `output: string`

1935

1936 JSON-encoded output captured from the tool. Defaults to null while execution is in progress.

1937

1938 - `status: "in_progress" or "completed"`

1939

1940 Execution status for the tool call.

1941

1942 - `"in_progress"`

1943

1944 - `"completed"`

1945

1946 - `thread_id: string`

1947

1948 Identifier of the parent thread.

1949

1950 - `type: "chatkit.client_tool_call"`

1951

1952 Type discriminator that is always `chatkit.client_tool_call`.

1953

1954 - `chatkit.task: object { id, created_at, heading, 5 more }`

1955

1956 Task emitted by the workflow to show progress and status updates.

1957

1958 - `id: string`

1959

1960 Identifier of the thread item.

1961

1962 - `created_at: number`

1963

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

1965

1966 - `heading: string`

1967

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

1969

1970 - `object: "chatkit.thread_item"`

1971

1972 Type discriminator that is always `chatkit.thread_item`.

1973

1974 - `summary: string`

1975

1976 Optional summary that describes the task. Defaults to null when omitted.

1977

1978 - `task_type: "custom" or "thought"`

1979

1980 Subtype for the task.

1981

1982 - `"custom"`

1983

1984 - `"thought"`

1985

1986 - `thread_id: string`

1987

1988 Identifier of the parent thread.

1989

1990 - `type: "chatkit.task"`

1991

1992 Type discriminator that is always `chatkit.task`.

1993

1994 - `chatkit.task_group: object { id, created_at, object, 3 more }`

1995

1996 Collection of workflow tasks grouped together in the thread.

1997

1998 - `id: string`

1999

2000 Identifier of the thread item.

2001

2002 - `created_at: number`

2003

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

2005

2006 - `object: "chatkit.thread_item"`

2007

2008 Type discriminator that is always `chatkit.thread_item`.

2009

2010 - `tasks: array of object { heading, summary, type }`

2011

2012 Tasks included in the group.

2013

2014 - `heading: string`

2015

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

2017

2018 - `summary: string`

2019

2020 Optional summary that describes the grouped task. Defaults to null when omitted.

2021

2022 - `type: "custom" or "thought"`

2023

2024 Subtype for the grouped task.

2025

2026 - `"custom"`

2027

2028 - `"thought"`

2029

2030 - `thread_id: string`

2031

2032 Identifier of the parent thread.

2033

2034 - `type: "chatkit.task_group"`

2035

2036 Type discriminator that is always `chatkit.task_group`.

2037

2038 - `first_id: string`

2039

2040 The ID of the first item in the list.

2041

2042 - `has_more: boolean`

2043

2044 Whether there are more items available.

2045

2046 - `last_id: string`

2047

2048 The ID of the last item in the list.

2049

2050 - `object: "list"`

2051

2052 The type of object returned, must be `list`.

2053

2054### ChatKit Thread User Message Item

2055

2056- `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }`

2057

2058 User-authored messages within a thread.

2059

2060 - `id: string`

2061

2062 Identifier of the thread item.

2063

2064 - `attachments: array of ChatKitAttachment`

2065

2066 Attachments associated with the user message. Defaults to an empty list.

2067

2068 - `id: string`

2069

2070 Identifier for the attachment.

2071

2072 - `mime_type: string`

2073

2074 MIME type of the attachment.

2075

2076 - `name: string`

2077

2078 Original display name for the attachment.

2079

2080 - `preview_url: string`

2081

2082 Preview URL for rendering the attachment inline.

2083

2084 - `type: "image" or "file"`

2085

2086 Attachment discriminator.

2087

2088 - `"image"`

2089

2090 - `"file"`

2091

2092 - `content: array of object { text, type } or object { text, type }`

2093

2094 Ordered content elements supplied by the user.

2095

2096 - `input_text: object { text, type }`

2097

2098 Text block that a user contributed to the thread.

2099

2100 - `text: string`

2101

2102 Plain-text content supplied by the user.

2103

2104 - `type: "input_text"`

2105

2106 Type discriminator that is always `input_text`.

2107

2108 - `quoted_text: object { text, type }`

2109

2110 Quoted snippet that the user referenced in their message.

2111

2112 - `text: string`

2113

2114 Quoted text content.

2115

2116 - `type: "quoted_text"`

2117

2118 Type discriminator that is always `quoted_text`.

2119

2120 - `created_at: number`

2121

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

2123

2124 - `inference_options: object { model, tool_choice }`

2125

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

2127

2128 - `model: string`

2129

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

2131

2132 - `tool_choice: object { id }`

2133

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

2135

2136 - `id: string`

2137

2138 Identifier of the requested tool.

2139

2140 - `object: "chatkit.thread_item"`

2141

2142 Type discriminator that is always `chatkit.thread_item`.

2143

2144 - `thread_id: string`

2145

2146 Identifier of the parent thread.

2147

2148 - `type: "chatkit.user_message"`

2149

2150### ChatKit Widget Item

2151

2152- `chatkit_widget_item: object { id, created_at, object, 3 more }`

2153

2154 Thread item that renders a widget payload.

2155

2156 - `id: string`

2157

2158 Identifier of the thread item.

2159

2160 - `created_at: number`

2161

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

2163

2164 - `object: "chatkit.thread_item"`

2165

2166 Type discriminator that is always `chatkit.thread_item`.

2167

2168 - `thread_id: string`

2169

2170 Identifier of the parent thread.

2171

2172 - `type: "chatkit.widget"`

2173

2174 Type discriminator that is always `chatkit.widget`.

2175

2176 - `widget: string`

2177

2178 Serialized widget payload rendered in the UI.

cli/resources/beta/subresources/chatkit/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 UTC

ChatKit

Domain Types

ChatKit Workflow

Sessions

Cancel chat session

Parameters

Returns

Example

Response

Create ChatKit session

Parameters

Returns

Example

Response

Threads

List ChatKit thread items

Parameters

Returns

Example

Response

Retrieve ChatKit thread

Parameters

Returns

Example

Response

Delete ChatKit thread

Parameters

Returns

Example

Response

List ChatKit threads

Parameters

Returns

Example

Response

Domain Types

Chat Session

Chat Session Automatic Thread Titling

Chat Session ChatKit Configuration

Chat Session ChatKit Configuration Param

Chat Session Expires After Param

Chat Session File Upload

Chat Session History

Chat Session Rate Limits

Chat Session Rate Limits Param

Chat Session Status

Chat Session Workflow Param

ChatKit Attachment

ChatKit Response Output Text

ChatKit Thread

ChatKit Thread Assistant Message Item

ChatKit Thread Item List

ChatKit Thread User Message Item

ChatKit Widget Item