Skip to content

types

StreamingReq module-attribute 

StreamingReq = (
    ThreadsCreateReq
    | ThreadsAddUserMessageReq
    | ThreadsAddClientToolOutputReq
    | ThreadsAddStructuredInputReq
    | ThreadsRetryAfterItemReq
    | ThreadsCustomActionReq
)

Union of request types that produce streaming responses.

NonStreamingReq module-attribute 

NonStreamingReq = (
    ThreadsGetByIdReq
    | ThreadsListReq
    | ItemsListReq
    | ItemsFeedbackReq
    | AttachmentsCreateReq
    | AttachmentsDeleteReq
    | ThreadsUpdateReq
    | ThreadsDeleteReq
    | InputTranscribeReq
    | ThreadsSyncCustomActionReq
)

Union of request types that yield immediate responses.

ThreadStreamEvent module-attribute 

ThreadStreamEvent = Annotated[
    ThreadCreatedEvent
    | ThreadUpdatedEvent
    | ThreadItemDoneEvent
    | ThreadItemAddedEvent
    | ThreadItemUpdated
    | ThreadItemRemovedEvent
    | ThreadItemReplacedEvent
    | StreamOptionsEvent
    | ProgressUpdateEvent
    | ClientEffectEvent
    | ErrorEvent
    | NoticeEvent,
    Field(discriminator="type"),
]

Union of all streaming events emitted to clients.

ThreadItemUpdate module-attribute 

ThreadItemUpdate = (
    AssistantMessageContentPartAdded
    | AssistantMessageContentPartTextDelta
    | AssistantMessageContentPartAnnotationAdded
    | AssistantMessageContentPartDone
    | WidgetStreamingTextValueDelta
    | WidgetComponentUpdated
    | WidgetRootUpdated
    | WorkflowTaskAdded
    | WorkflowTaskUpdated
    | GeneratedImageUpdated
)

Union of possible updates applied to thread items.

ThreadStatus module-attribute 

ThreadStatus = Annotated[
    ActiveStatus | LockedStatus | ClosedStatus,
    Field(discriminator="type"),
]

Union of lifecycle states for a thread.

StructuredInput module-attribute 

StructuredInput = Annotated[
    StructuredInputMultipleChoice | StructuredInputFreeform,
    Field(discriminator="type"),
]

Structured input variants supported by a structured input item.

ThreadItem module-attribute 

ThreadItem = Annotated[
    UserMessageItem
    | AssistantMessageItem
    | ClientToolCallItem
    | WidgetItem
    | GeneratedImageItem
    | StructuredInputItem
    | WorkflowItem
    | TaskItem
    | HiddenContextItem
    | SDKHiddenContextItem
    | EndOfTurnItem,
    Field(discriminator="type"),
]

Union of all thread item variants.

UserMessageContent module-attribute 

UserMessageContent = Annotated[
    UserMessageTextContent | UserMessageTagContent,
    Field(discriminator="type"),
]

Union of allowed user message content payloads.

Attachment module-attribute 

Attachment = Annotated[
    FileAttachment | ImageAttachment,
    Field(discriminator="type"),
]

Union of supported attachment types.

WorkflowSummary module-attribute 

WorkflowSummary = CustomSummary | DurationSummary

Summary variants available for workflows.

Task module-attribute 

Task = Annotated[
    CustomTask
    | SearchTask
    | ThoughtTask
    | FileTask
    | ImageTask,
    Field(discriminator="type"),
]

Union of workflow task variants.

Source module-attribute 

Source = Annotated[
    URLSource | FileSource | EntitySource,
    Field(discriminator="type"),
]

Union of supported source types.

FeedbackKind module-attribute 

FeedbackKind = Literal['positive', 'negative']

Literal type for feedback sentiment.

Page

Bases: BaseModel, Generic[T]

Paginated collection of records returned from the API.

Source code in chatkit/types.py 
24
25
26
27
28
29
class Page(BaseModel, Generic[T]):
    """Paginated collection of records returned from the API."""

    data: list[T] = []
    has_more: bool = False
    after: str | None = None

BaseReq

Bases: BaseModel

Base class for all request payloads.

Source code in chatkit/types.py 
35
36
37
38
39
class BaseReq(BaseModel):
    """Base class for all request payloads."""

    metadata: dict[str, Any] = Field(default_factory=dict)
    """Arbitrary integration-specific metadata."""

metadata class-attribute instance-attribute 

metadata: dict[str, Any] = Field(default_factory=dict)

Arbitrary integration-specific metadata.

ThreadsGetByIdReq

Bases: BaseReq

Request to fetch a single thread by its identifier.

Source code in chatkit/types.py 
42
43
44
45
46
class ThreadsGetByIdReq(BaseReq):
    """Request to fetch a single thread by its identifier."""

    type: Literal["threads.get_by_id"] = "threads.get_by_id"
    params: ThreadGetByIdParams

ThreadGetByIdParams

Bases: BaseModel

Parameters for retrieving a thread by id.

Source code in chatkit/types.py 
49
50
51
52
class ThreadGetByIdParams(BaseModel):
    """Parameters for retrieving a thread by id."""

    thread_id: str

ThreadsCreateReq

Bases: BaseReq

Request to create a new thread from a user message.

Source code in chatkit/types.py 
55
56
57
58
59
class ThreadsCreateReq(BaseReq):
    """Request to create a new thread from a user message."""

    type: Literal["threads.create"] = "threads.create"
    params: ThreadCreateParams

ThreadCreateParams

Bases: BaseModel

User input required to create a thread.

Source code in chatkit/types.py 
62
63
64
65
class ThreadCreateParams(BaseModel):
    """User input required to create a thread."""

    input: UserMessageInput

ThreadListParams

Bases: BaseModel

Pagination parameters for listing threads.

Source code in chatkit/types.py 
68
69
70
71
72
73
class ThreadListParams(BaseModel):
    """Pagination parameters for listing threads."""

    limit: int | None = None
    order: Literal["asc", "desc"] = "desc"
    after: str | None = None

ThreadsListReq

Bases: BaseReq

Request to list threads.

Source code in chatkit/types.py 
76
77
78
79
80
class ThreadsListReq(BaseReq):
    """Request to list threads."""

    type: Literal["threads.list"] = "threads.list"
    params: ThreadListParams

ThreadsAddUserMessageReq

Bases: BaseReq

Request to append a user message to a thread.

Source code in chatkit/types.py 
83
84
85
86
87
class ThreadsAddUserMessageReq(BaseReq):
    """Request to append a user message to a thread."""

    type: Literal["threads.add_user_message"] = "threads.add_user_message"
    params: ThreadAddUserMessageParams

ThreadAddUserMessageParams

Bases: BaseModel

Parameters for adding a user message to a thread.

Source code in chatkit/types.py 
90
91
92
93
94
class ThreadAddUserMessageParams(BaseModel):
    """Parameters for adding a user message to a thread."""

    input: UserMessageInput
    thread_id: str

ThreadsAddClientToolOutputReq

Bases: BaseReq

Request to add a client tool's output to a thread.

Source code in chatkit/types.py 
 97
 98
 99
100
101
class ThreadsAddClientToolOutputReq(BaseReq):
    """Request to add a client tool's output to a thread."""

    type: Literal["threads.add_client_tool_output"] = "threads.add_client_tool_output"
    params: ThreadAddClientToolOutputParams

ThreadAddClientToolOutputParams

Bases: BaseModel

Parameters for recording tool output in a thread.

Source code in chatkit/types.py 
104
105
106
107
108
class ThreadAddClientToolOutputParams(BaseModel):
    """Parameters for recording tool output in a thread."""

    thread_id: str
    result: Any

StructuredInputAnswerSubmission

Bases: BaseModel

Client-submitted answer for a structured input.

Source code in chatkit/types.py 
111
112
113
114
115
116
117
class StructuredInputAnswerSubmission(BaseModel):
    """Client-submitted answer for a structured input."""

    values: list[str] = Field(default_factory=list)
    """Text answer values submitted for the structured input."""
    skipped: bool = False
    """Whether this structured input answer was skipped."""

values class-attribute instance-attribute 

values: list[str] = Field(default_factory=list)

Text answer values submitted for the structured input.

skipped class-attribute instance-attribute 

skipped: bool = False

Whether this structured input answer was skipped.

StructuredInputSubmission

Bases: BaseModel

Client-submitted answers for a pending structured input item.

Source code in chatkit/types.py 
120
121
122
123
124
125
126
class StructuredInputSubmission(BaseModel):
    """Client-submitted answers for a pending structured input item."""

    status: Literal["answered", "skipped"] = "answered"
    """Overall status for the structured input submission."""
    answers: dict[str, StructuredInputAnswerSubmission] = Field(default_factory=dict)
    """Answers keyed by structured input id."""

status class-attribute instance-attribute 

status: Literal['answered', 'skipped'] = 'answered'

Overall status for the structured input submission.

answers class-attribute instance-attribute 

answers: dict[str, StructuredInputAnswerSubmission] = Field(
    default_factory=dict
)

Answers keyed by structured input id.

ThreadsAddStructuredInputReq

Bases: BaseReq

Request to submit answers for a pending structured input item.

Source code in chatkit/types.py 
129
130
131
132
133
class ThreadsAddStructuredInputReq(BaseReq):
    """Request to submit answers for a pending structured input item."""

    type: Literal["threads.add_structured_input"] = "threads.add_structured_input"
    params: ThreadAddStructuredInputParams

ThreadAddStructuredInputParams

Bases: BaseModel

Parameters for adding structured input to a thread.

Source code in chatkit/types.py 
136
137
138
139
140
141
class ThreadAddStructuredInputParams(BaseModel):
    """Parameters for adding structured input to a thread."""

    thread_id: str
    item_id: str
    input: StructuredInputSubmission

ThreadsCustomActionReq

Bases: BaseReq

Request to execute a custom action within a thread.

Source code in chatkit/types.py 
144
145
146
147
148
class ThreadsCustomActionReq(BaseReq):
    """Request to execute a custom action within a thread."""

    type: Literal["threads.custom_action"] = "threads.custom_action"
    params: ThreadCustomActionParams

ThreadsSyncCustomActionReq

Bases: BaseReq

Request to execute a custom action and return a single item update.

Source code in chatkit/types.py 
151
152
153
154
155
class ThreadsSyncCustomActionReq(BaseReq):
    """Request to execute a custom action and return a single item update."""

    type: Literal["threads.sync_custom_action"] = "threads.sync_custom_action"
    params: ThreadCustomActionParams

ThreadCustomActionParams

Bases: BaseModel

Parameters describing the custom action to execute.

Source code in chatkit/types.py 
158
159
160
161
162
163
class ThreadCustomActionParams(BaseModel):
    """Parameters describing the custom action to execute."""

    thread_id: str
    item_id: str | None = None
    action: Action[str, Any]

ThreadsRetryAfterItemReq

Bases: BaseReq

Request to retry processing after a specific thread item.

Source code in chatkit/types.py 
166
167
168
169
170
class ThreadsRetryAfterItemReq(BaseReq):
    """Request to retry processing after a specific thread item."""

    type: Literal["threads.retry_after_item"] = "threads.retry_after_item"
    params: ThreadRetryAfterItemParams

ThreadRetryAfterItemParams

Bases: BaseModel

Parameters specifying which item to retry.

Source code in chatkit/types.py 
173
174
175
176
177
class ThreadRetryAfterItemParams(BaseModel):
    """Parameters specifying which item to retry."""

    thread_id: str
    item_id: str

ItemsFeedbackReq

Bases: BaseReq

Request to submit feedback on specific items.

Source code in chatkit/types.py 
180
181
182
183
184
class ItemsFeedbackReq(BaseReq):
    """Request to submit feedback on specific items."""

    type: Literal["items.feedback"] = "items.feedback"
    params: ItemFeedbackParams

ItemFeedbackParams

Bases: BaseModel

Parameters describing feedback targets and sentiment.

Source code in chatkit/types.py 
187
188
189
190
191
192
class ItemFeedbackParams(BaseModel):
    """Parameters describing feedback targets and sentiment."""

    thread_id: str
    item_ids: list[str]
    kind: FeedbackKind

AttachmentsDeleteReq

Bases: BaseReq

Request to remove an attachment.

Source code in chatkit/types.py 
195
196
197
198
199
class AttachmentsDeleteReq(BaseReq):
    """Request to remove an attachment."""

    type: Literal["attachments.delete"] = "attachments.delete"
    params: AttachmentDeleteParams

AttachmentDeleteParams

Bases: BaseModel

Parameters identifying an attachment to delete.

Source code in chatkit/types.py 
202
203
204
205
class AttachmentDeleteParams(BaseModel):
    """Parameters identifying an attachment to delete."""

    attachment_id: str

AttachmentsCreateReq

Bases: BaseReq

Request to register a new attachment.

Source code in chatkit/types.py 
208
209
210
211
212
class AttachmentsCreateReq(BaseReq):
    """Request to register a new attachment."""

    type: Literal["attachments.create"] = "attachments.create"
    params: AttachmentCreateParams

AttachmentCreateParams

Bases: BaseModel

Metadata needed to initialize an attachment.

Source code in chatkit/types.py 
215
216
217
218
219
220
class AttachmentCreateParams(BaseModel):
    """Metadata needed to initialize an attachment."""

    name: str
    size: int
    mime_type: str

InputTranscribeReq

Bases: BaseReq

Request to transcribe an audio payload into text.

Source code in chatkit/types.py 
223
224
225
226
227
class InputTranscribeReq(BaseReq):
    """Request to transcribe an audio payload into text."""

    type: Literal["input.transcribe"] = "input.transcribe"
    params: InputTranscribeParams

InputTranscribeParams

Bases: BaseModel

Parameters for speech transcription.

Source code in chatkit/types.py 
230
231
232
233
234
235
236
237
class InputTranscribeParams(BaseModel):
    """Parameters for speech transcription."""

    audio_base64: str
    """Base64-encoded audio bytes."""

    mime_type: str
    """Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus"."""

audio_base64 instance-attribute 

audio_base64: str

Base64-encoded audio bytes.

mime_type instance-attribute 

mime_type: str

Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus".

AudioInput

Bases: BaseModel

Audio input data for transcription.

Source code in chatkit/types.py 
240
241
242
243
244
245
246
247
248
249
250
251
252
class AudioInput(BaseModel):
    """Audio input data for transcription."""

    data: bytes
    """Audio data bytes."""

    mime_type: str
    """Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus"."""

    @property
    def media_type(self) -> str:
        """Media type for the audio payload, e.g. "audio/webm"."""
        return self.mime_type.split(";", 1)[0]

data instance-attribute 

data: bytes

Audio data bytes.

mime_type instance-attribute 

mime_type: str

Raw MIME type for the audio payload, e.g. "audio/webm;codecs=opus".

media_type property 

media_type: str

Media type for the audio payload, e.g. "audio/webm".

TranscriptionResult

Bases: BaseModel

Input speech transcription result.

Source code in chatkit/types.py 
255
256
257
258
class TranscriptionResult(BaseModel):
    """Input speech transcription result."""

    text: str

ItemsListReq

Bases: BaseReq

Request to list items inside a thread.

Source code in chatkit/types.py 
261
262
263
264
265
class ItemsListReq(BaseReq):
    """Request to list items inside a thread."""

    type: Literal["items.list"] = "items.list"
    params: ItemsListParams

ItemsListParams

Bases: BaseModel

Pagination parameters for listing thread items.

Source code in chatkit/types.py 
268
269
270
271
272
273
274
class ItemsListParams(BaseModel):
    """Pagination parameters for listing thread items."""

    thread_id: str
    limit: int | None = None
    order: Literal["asc", "desc"] = "desc"
    after: str | None = None

ThreadsUpdateReq

Bases: BaseReq

Request to update thread metadata.

Source code in chatkit/types.py 
277
278
279
280
281
class ThreadsUpdateReq(BaseReq):
    """Request to update thread metadata."""

    type: Literal["threads.update"] = "threads.update"
    params: ThreadUpdateParams

ThreadUpdateParams

Bases: BaseModel

Parameters for updating a thread's properties.

Source code in chatkit/types.py 
284
285
286
287
288
class ThreadUpdateParams(BaseModel):
    """Parameters for updating a thread's properties."""

    thread_id: str
    title: str

ThreadsDeleteReq

Bases: BaseReq

Request to delete a thread.

Source code in chatkit/types.py 
291
292
293
294
295
class ThreadsDeleteReq(BaseReq):
    """Request to delete a thread."""

    type: Literal["threads.delete"] = "threads.delete"
    params: ThreadDeleteParams

ThreadDeleteParams

Bases: BaseModel

Parameters identifying a thread to delete.

Source code in chatkit/types.py 
298
299
300
301
class ThreadDeleteParams(BaseModel):
    """Parameters identifying a thread to delete."""

    thread_id: str

ThreadCreatedEvent

Bases: BaseModel

Event emitted when a thread is created.

Source code in chatkit/types.py 
354
355
356
357
358
class ThreadCreatedEvent(BaseModel):
    """Event emitted when a thread is created."""

    type: Literal["thread.created"] = "thread.created"
    thread: Thread

ThreadUpdatedEvent

Bases: BaseModel

Event emitted when a thread is updated.

Source code in chatkit/types.py 
361
362
363
364
365
class ThreadUpdatedEvent(BaseModel):
    """Event emitted when a thread is updated."""

    type: Literal["thread.updated"] = "thread.updated"
    thread: Thread

ThreadItemAddedEvent

Bases: BaseModel

Event emitted when a new item is added to a thread.

Source code in chatkit/types.py 
368
369
370
371
372
class ThreadItemAddedEvent(BaseModel):
    """Event emitted when a new item is added to a thread."""

    type: Literal["thread.item.added"] = "thread.item.added"
    item: ThreadItem

ThreadItemUpdatedEvent

Bases: BaseModel

Event describing an update to an existing thread item.

Source code in chatkit/types.py 
375
376
377
378
379
380
class ThreadItemUpdatedEvent(BaseModel):
    """Event describing an update to an existing thread item."""

    type: Literal["thread.item.updated"] = "thread.item.updated"
    item_id: str
    update: ThreadItemUpdate

ThreadItemDoneEvent

Bases: BaseModel

Event emitted when a thread item is marked complete.

Source code in chatkit/types.py 
387
388
389
390
391
class ThreadItemDoneEvent(BaseModel):
    """Event emitted when a thread item is marked complete."""

    type: Literal["thread.item.done"] = "thread.item.done"
    item: ThreadItem

ThreadItemRemovedEvent

Bases: BaseModel

Event emitted when a thread item is removed.

Source code in chatkit/types.py 
394
395
396
397
398
class ThreadItemRemovedEvent(BaseModel):
    """Event emitted when a thread item is removed."""

    type: Literal["thread.item.removed"] = "thread.item.removed"
    item_id: str

ThreadItemReplacedEvent

Bases: BaseModel

Event emitted when a thread item is replaced.

Source code in chatkit/types.py 
401
402
403
404
405
class ThreadItemReplacedEvent(BaseModel):
    """Event emitted when a thread item is replaced."""

    type: Literal["thread.item.replaced"] = "thread.item.replaced"
    item: ThreadItem

StreamOptions

Bases: BaseModel

Settings that control runtime stream behavior.

Source code in chatkit/types.py 
408
409
410
411
412
class StreamOptions(BaseModel):
    """Settings that control runtime stream behavior."""

    allow_cancel: bool
    """Allow the client to request cancellation mid-stream."""

allow_cancel instance-attribute 

allow_cancel: bool

Allow the client to request cancellation mid-stream.

StreamOptionsEvent

Bases: BaseModel

Event emitted to set stream options at runtime.

Source code in chatkit/types.py 
415
416
417
418
419
class StreamOptionsEvent(BaseModel):
    """Event emitted to set stream options at runtime."""

    type: Literal["stream_options"] = "stream_options"
    stream_options: StreamOptions

ProgressUpdateEvent

Bases: BaseModel

Event providing incremental progress from the assistant.

Source code in chatkit/types.py 
422
423
424
425
426
427
class ProgressUpdateEvent(BaseModel):
    """Event providing incremental progress from the assistant."""

    type: Literal["progress_update"] = "progress_update"
    icon: IconName | None = None
    text: str

ClientEffectEvent

Bases: BaseModel

Event emitted to trigger a client side-effect.

Source code in chatkit/types.py 
430
431
432
433
434
435
class ClientEffectEvent(BaseModel):
    """Event emitted to trigger a client side-effect."""

    type: Literal["client_effect"] = "client_effect"
    name: str
    data: dict[str, Any] = Field(default_factory=dict)

ErrorEvent

Bases: BaseModel

Event indicating an error occurred while processing a thread.

Source code in chatkit/types.py 
438
439
440
441
442
443
444
class ErrorEvent(BaseModel):
    """Event indicating an error occurred while processing a thread."""

    type: Literal["error"] = "error"
    code: ErrorCode | Literal["custom"] = Field(default="custom")
    message: str | None = None
    allow_retry: bool = Field(default=False)

NoticeEvent

Bases: BaseModel

Event conveying a user-facing notice.

Source code in chatkit/types.py 
447
448
449
450
451
452
453
454
455
456
class NoticeEvent(BaseModel):
    """Event conveying a user-facing notice."""

    type: Literal["notice"] = "notice"
    level: Literal["info", "warning", "danger"]
    message: str
    """
    Supports markdown e.g. "You've reached your limit of 100 messages. [Upgrade](https://...) to a paid plan."
    """
    title: str | None = None

message instance-attribute 

message: str

Supports markdown e.g. "You've reached your limit of 100 messages. Upgrade to a paid plan."

AssistantMessageContentPartAdded

Bases: BaseModel

Event emitted when new assistant content is appended.

Source code in chatkit/types.py 
479
480
481
482
483
484
485
486
class AssistantMessageContentPartAdded(BaseModel):
    """Event emitted when new assistant content is appended."""

    type: Literal["assistant_message.content_part.added"] = (
        "assistant_message.content_part.added"
    )
    content_index: int
    content: AssistantMessageContent

AssistantMessageContentPartTextDelta

Bases: BaseModel

Event carrying incremental assistant text output.

Source code in chatkit/types.py 
489
490
491
492
493
494
495
496
class AssistantMessageContentPartTextDelta(BaseModel):
    """Event carrying incremental assistant text output."""

    type: Literal["assistant_message.content_part.text_delta"] = (
        "assistant_message.content_part.text_delta"
    )
    content_index: int
    delta: str

AssistantMessageContentPartAnnotationAdded

Bases: BaseModel

Event announcing a new annotation on assistant content.

Source code in chatkit/types.py 
499
500
501
502
503
504
505
506
507
class AssistantMessageContentPartAnnotationAdded(BaseModel):
    """Event announcing a new annotation on assistant content."""

    type: Literal["assistant_message.content_part.annotation_added"] = (
        "assistant_message.content_part.annotation_added"
    )
    content_index: int
    annotation_index: int
    annotation: Annotation

AssistantMessageContentPartDone

Bases: BaseModel

Event indicating an assistant content part is finalized.

Source code in chatkit/types.py 
510
511
512
513
514
515
516
517
class AssistantMessageContentPartDone(BaseModel):
    """Event indicating an assistant content part is finalized."""

    type: Literal["assistant_message.content_part.done"] = (
        "assistant_message.content_part.done"
    )
    content_index: int
    content: AssistantMessageContent

WidgetStreamingTextValueDelta

Bases: BaseModel

Event streaming widget text deltas.

Source code in chatkit/types.py 
520
521
522
523
524
525
526
527
528
class WidgetStreamingTextValueDelta(BaseModel):
    """Event streaming widget text deltas."""

    type: Literal["widget.streaming_text.value_delta"] = (
        "widget.streaming_text.value_delta"
    )
    component_id: str
    delta: str
    done: bool

WidgetRootUpdated

Bases: BaseModel

Event published when the widget root changes.

Source code in chatkit/types.py 
531
532
533
534
535
class WidgetRootUpdated(BaseModel):
    """Event published when the widget root changes."""

    type: Literal["widget.root.updated"] = "widget.root.updated"
    widget: WidgetRoot

WidgetComponentUpdated

Bases: BaseModel

Event emitted when a widget component updates.

Source code in chatkit/types.py 
538
539
540
541
542
543
class WidgetComponentUpdated(BaseModel):
    """Event emitted when a widget component updates."""

    type: Literal["widget.component.updated"] = "widget.component.updated"
    component_id: str
    component: WidgetComponent

WorkflowTaskAdded

Bases: BaseModel

Event emitted when a workflow task is added.

Source code in chatkit/types.py 
546
547
548
549
550
551
class WorkflowTaskAdded(BaseModel):
    """Event emitted when a workflow task is added."""

    type: Literal["workflow.task.added"] = "workflow.task.added"
    task_index: int
    task: Task

WorkflowTaskUpdated

Bases: BaseModel

Event emitted when a workflow task is updated.

Source code in chatkit/types.py 
554
555
556
557
558
559
class WorkflowTaskUpdated(BaseModel):
    """Event emitted when a workflow task is updated."""

    type: Literal["workflow.task.updated"] = "workflow.task.updated"
    task_index: int
    task: Task

GeneratedImageUpdated

Bases: BaseModel

Event emitted when a generated image is updated.

Source code in chatkit/types.py 
562
563
564
565
566
567
class GeneratedImageUpdated(BaseModel):
    """Event emitted when a generated image is updated."""

    type: Literal["generated_image.updated"] = "generated_image.updated"
    image: GeneratedImage
    progress: float | None = None

SyncCustomActionResponse

Bases: BaseModel

Single thread item update returned by a sync custom action.

Source code in chatkit/types.py 
585
586
587
class SyncCustomActionResponse(BaseModel):
    """Single thread item update returned by a sync custom action."""
    updated_item: ThreadItem | None = None

ThreadMetadata

Bases: BaseModel

Metadata describing a thread without its items.

Source code in chatkit/types.py 
593
594
595
596
597
598
599
600
601
class ThreadMetadata(BaseModel):
    """Metadata describing a thread without its items."""

    title: str | None = None
    id: str
    created_at: datetime
    status: ThreadStatus = Field(default_factory=lambda: ActiveStatus())
    allowed_image_domains: list[str] | None = None
    metadata: dict[str, Any] = Field(default_factory=dict)

ActiveStatus

Bases: BaseModel

Status indicating the thread is active.

Source code in chatkit/types.py 
604
605
606
607
class ActiveStatus(BaseModel):
    """Status indicating the thread is active."""

    type: Literal["active"] = Field(default="active", frozen=True)

LockedStatus

Bases: BaseModel

Status indicating the thread is locked.

Source code in chatkit/types.py 
610
611
612
613
614
class LockedStatus(BaseModel):
    """Status indicating the thread is locked."""

    type: Literal["locked"] = Field(default="locked", frozen=True)
    reason: str | None = None

ClosedStatus

Bases: BaseModel

Status indicating the thread is closed.

Source code in chatkit/types.py 
617
618
619
620
621
class ClosedStatus(BaseModel):
    """Status indicating the thread is closed."""

    type: Literal["closed"] = Field(default="closed", frozen=True)
    reason: str | None = None

Thread

Bases: ThreadMetadata

Thread with its paginated items.

Source code in chatkit/types.py 
631
632
633
634
class Thread(ThreadMetadata):
    """Thread with its paginated items."""

    items: Page[ThreadItem]

ThreadItemBase

Bases: BaseModel

Base fields shared by all thread items.

Source code in chatkit/types.py 
640
641
642
643
644
645
class ThreadItemBase(BaseModel):
    """Base fields shared by all thread items."""

    id: str
    thread_id: str
    created_at: datetime

UserMessageItem

Bases: ThreadItemBase

Thread item representing a user message.

Source code in chatkit/types.py 
648
649
650
651
652
653
654
655
class UserMessageItem(ThreadItemBase):
    """Thread item representing a user message."""

    type: Literal["user_message"] = "user_message"
    content: list[UserMessageContent]
    attachments: list[Attachment] = Field(default_factory=list)
    quoted_text: str | None = None
    inference_options: InferenceOptions

AssistantMessageItem

Bases: ThreadItemBase

Thread item representing an assistant message.

Source code in chatkit/types.py 
658
659
660
661
662
class AssistantMessageItem(ThreadItemBase):
    """Thread item representing an assistant message."""

    type: Literal["assistant_message"] = "assistant_message"
    content: list[AssistantMessageContent]

ClientToolCallItem

Bases: ThreadItemBase

Thread item capturing a client tool call.

Source code in chatkit/types.py 
665
666
667
668
669
670
671
672
673
class ClientToolCallItem(ThreadItemBase):
    """Thread item capturing a client tool call."""

    type: Literal["client_tool_call"] = "client_tool_call"
    status: Literal["pending", "completed"] = "pending"
    call_id: str
    name: str
    arguments: dict[str, Any]
    output: Any | None = None

WidgetItem

Bases: ThreadItemBase

Thread item containing widget content.

Source code in chatkit/types.py 
676
677
678
679
680
681
class WidgetItem(ThreadItemBase):
    """Thread item containing widget content."""

    type: Literal["widget"] = "widget"
    widget: WidgetRoot
    copy_text: str | None = None

GeneratedImage

Bases: BaseModel

Generated image.

Source code in chatkit/types.py 
684
685
686
687
688
class GeneratedImage(BaseModel):
    """Generated image."""

    id: str
    url: str

GeneratedImageItem

Bases: ThreadItemBase

Thread item containing a generated image.

Source code in chatkit/types.py 
691
692
693
694
695
class GeneratedImageItem(ThreadItemBase):
    """Thread item containing a generated image."""

    type: Literal["generated_image"] = "generated_image"
    image: GeneratedImage | None = None

StructuredInputAnswer

Bases: BaseModel

Answer recorded for a structured input.

Source code in chatkit/types.py 
698
699
700
701
702
703
704
class StructuredInputAnswer(BaseModel):
    """Answer recorded for a structured input."""

    values: list[str] = Field(default_factory=list)
    """Text answer values recorded for the structured input."""
    skipped: bool = False
    """Whether this structured input answer was skipped."""

values class-attribute instance-attribute 

values: list[str] = Field(default_factory=list)

Text answer values recorded for the structured input.

skipped class-attribute instance-attribute 

skipped: bool = False

Whether this structured input answer was skipped.

StructuredInputBase

Bases: BaseModel

Base fields shared by structured inputs.

Source code in chatkit/types.py 
707
708
709
710
711
712
713
714
715
class StructuredInputBase(BaseModel):
    """Base fields shared by structured inputs."""

    id: str
    """Stable id for this structured input."""
    question: str
    """Question shown to the user."""
    answer: StructuredInputAnswer | None = None
    """Answer recorded for this structured input, if available."""

id instance-attribute 

id: str

Stable id for this structured input.

question instance-attribute 

question: str

Question shown to the user.

answer class-attribute instance-attribute 

answer: StructuredInputAnswer | None = None

Answer recorded for this structured input, if available.

StructuredInputMultipleChoiceOption

Bases: BaseModel

Option shown for a multiple-choice structured input.

Source code in chatkit/types.py 
718
719
720
721
722
class StructuredInputMultipleChoiceOption(BaseModel):
    """Option shown for a multiple-choice structured input."""

    value: str
    """Text value submitted when this option is selected."""

value instance-attribute 

value: str

Text value submitted when this option is selected.

StructuredInputMultipleChoice

Bases: StructuredInputBase

Structured input answered by choosing one or more options.

Source code in chatkit/types.py 
725
726
727
728
729
730
731
732
class StructuredInputMultipleChoice(StructuredInputBase):
    """Structured input answered by choosing one or more options."""

    type: Literal["multiple_choice"] = "multiple_choice"
    options: list[StructuredInputMultipleChoiceOption]
    """Suggested choices to display before the freeform custom answer affordance."""
    multiple: bool = False
    """Whether the user may submit more than one text value."""

options instance-attribute 

options: list[StructuredInputMultipleChoiceOption]

Suggested choices to display before the freeform custom answer affordance.

multiple class-attribute instance-attribute 

multiple: bool = False

Whether the user may submit more than one text value.

StructuredInputFreeform

Bases: StructuredInputBase

Structured input answered with freeform text.

Source code in chatkit/types.py 
735
736
737
738
739
740
class StructuredInputFreeform(StructuredInputBase):
    """Structured input answered with freeform text."""

    type: Literal["freeform"] = "freeform"
    description: str | None = None
    """Supporting text shown with this input."""

description class-attribute instance-attribute 

description: str | None = None

Supporting text shown with this input.

StructuredInputItem

Bases: ThreadItemBase

Thread item requesting structured input from the user.

Source code in chatkit/types.py 
750
751
752
753
754
755
class StructuredInputItem(ThreadItemBase):
    """Thread item requesting structured input from the user."""

    type: Literal["structured_input"] = "structured_input"
    status: Literal["pending", "answered", "skipped"] = "pending"
    inputs: list[StructuredInput]

TaskItem

Bases: ThreadItemBase

Thread item containing a task.

Source code in chatkit/types.py 
758
759
760
761
762
class TaskItem(ThreadItemBase):
    """Thread item containing a task."""

    type: Literal["task"] = "task"
    task: Task

WorkflowItem

Bases: ThreadItemBase

Thread item representing a workflow.

Source code in chatkit/types.py 
765
766
767
768
769
class WorkflowItem(ThreadItemBase):
    """Thread item representing a workflow."""

    type: Literal["workflow"] = "workflow"
    workflow: Workflow

EndOfTurnItem

Bases: ThreadItemBase

Marker item indicating the assistant ends its turn.

Source code in chatkit/types.py 
772
773
774
775
class EndOfTurnItem(ThreadItemBase):
    """Marker item indicating the assistant ends its turn."""

    type: Literal["end_of_turn"] = "end_of_turn"

HiddenContextItem

Bases: ThreadItemBase

HiddenContext is never sent to the client. It's not officially part of ChatKit.js. It is only used internally to store additional context in a specific place in the thread.

Source code in chatkit/types.py 
778
779
780
781
782
783
784
785
class HiddenContextItem(ThreadItemBase):
    """
    HiddenContext is never sent to the client. It's not officially part of ChatKit.js.
    It is only used internally to store additional context in a specific place in the thread.
    """

    type: Literal["hidden_context_item"] = "hidden_context_item"
    content: Any

SDKHiddenContextItem

Bases: ThreadItemBase

Hidden context that is used by the ChatKit Python SDK for storing additional context for internal operations.

Source code in chatkit/types.py 
788
789
790
791
792
793
794
795
class SDKHiddenContextItem(ThreadItemBase):
    """
    Hidden context that is used by the ChatKit Python SDK for storing additional context
    for internal operations.
    """

    type: Literal["sdk_hidden_context"] = "sdk_hidden_context"
    content: str

AssistantMessageContent

Bases: BaseModel

Assistant message content consisting of text and annotations.

Source code in chatkit/types.py 
818
819
820
821
822
823
class AssistantMessageContent(BaseModel):
    """Assistant message content consisting of text and annotations."""

    annotations: list[Annotation] = Field(default_factory=list)
    text: str
    type: Literal["output_text"] = "output_text"

Annotation

Bases: BaseModel

Reference to supporting context attached to assistant output.

Source code in chatkit/types.py 
826
827
828
829
830
831
class Annotation(BaseModel):
    """Reference to supporting context attached to assistant output."""

    type: Literal["annotation"] = "annotation"
    source: URLSource | FileSource | EntitySource
    index: int | None = None

UserMessageInput

Bases: BaseModel

Payload describing a user message submission.

Source code in chatkit/types.py 
837
838
839
840
841
842
843
class UserMessageInput(BaseModel):
    """Payload describing a user message submission."""

    content: list[UserMessageContent]
    attachments: list[str]
    quoted_text: str | None = None
    inference_options: InferenceOptions

UserMessageTextContent

Bases: BaseModel

User message content containing plaintext.

Source code in chatkit/types.py 
846
847
848
849
850
class UserMessageTextContent(BaseModel):
    """User message content containing plaintext."""

    type: Literal["input_text"] = "input_text"
    text: str

UserMessageTagContent

Bases: BaseModel

User message content representing an interactive tag.

Source code in chatkit/types.py 
853
854
855
856
857
858
859
860
861
class UserMessageTagContent(BaseModel):
    """User message content representing an interactive tag."""

    type: Literal["input_tag"] = "input_tag"
    id: str
    text: str
    data: dict[str, Any]
    group: str | None = None
    interactive: bool = False

InferenceOptions

Bases: BaseModel

Model and tool configuration for message processing.

Source code in chatkit/types.py 
870
871
872
873
874
class InferenceOptions(BaseModel):
    """Model and tool configuration for message processing."""

    tool_choice: ToolChoice | None = None
    model: str | None = None

ToolChoice

Bases: BaseModel

Explicit tool selection for the assistant to invoke.

Source code in chatkit/types.py 
877
878
879
880
class ToolChoice(BaseModel):
    """Explicit tool selection for the assistant to invoke."""

    id: str

AttachmentUploadDescriptor

Bases: BaseModel

Two-phase upload instructions.

Source code in chatkit/types.py 
883
884
885
886
887
888
889
890
class AttachmentUploadDescriptor(BaseModel):
    """Two-phase upload instructions."""

    url: AnyUrl
    method: Literal["POST", "PUT"]
    """The HTTP method to use when uploading the file for two-phase upload."""
    headers: dict[str, str] = Field(default_factory=dict)
    """Optional headers to include in the upload request."""

method instance-attribute 

method: Literal['POST', 'PUT']

The HTTP method to use when uploading the file for two-phase upload.

headers class-attribute instance-attribute 

headers: dict[str, str] = Field(default_factory=dict)

Optional headers to include in the upload request.

AttachmentBase

Bases: BaseModel

Base metadata shared by all attachments.

Source code in chatkit/types.py 
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
class AttachmentBase(BaseModel):
    """Base metadata shared by all attachments."""

    id: str
    name: str
    mime_type: str
    upload_descriptor: AttachmentUploadDescriptor | None = None
    """
    Two-phase upload instructions.
    Should be set to None after upload is complete or when using direct upload
    where uploading happens when creating the attachment object.
    """
    thread_id: str | None = None
    """
    The thread the attachment belongs to, if any.
    Added when the user message that contains the attachment is saved to store.
    """
    metadata: dict[str, Any] | None = None
    """
    Integration-only metadata stored with the attachment. Ignored by ChatKit and not
    returned in ChatKitServer responses. If you serialize attachments from a custom
    direct-upload endpoint and want to omit this field, pass context={"exclude_metadata": True}.
    """

    @model_serializer(mode="wrap")
    def _serialize(self, serializer, info: SerializationInfo):
        data = serializer(self)
        if isinstance(data, dict) and (info.context or {}).get("exclude_metadata"):
            data.pop("metadata", None)
        return data

upload_descriptor class-attribute instance-attribute 

upload_descriptor: AttachmentUploadDescriptor | None = None

Two-phase upload instructions. Should be set to None after upload is complete or when using direct upload where uploading happens when creating the attachment object.

thread_id class-attribute instance-attribute 

thread_id: str | None = None

The thread the attachment belongs to, if any. Added when the user message that contains the attachment is saved to store.

metadata class-attribute instance-attribute 

metadata: dict[str, Any] | None = None

Integration-only metadata stored with the attachment. Ignored by ChatKit and not returned in ChatKitServer responses. If you serialize attachments from a custom direct-upload endpoint and want to omit this field, pass context={"exclude_metadata": True}.

FileAttachment

Bases: AttachmentBase

Attachment representing a generic file.

Source code in chatkit/types.py 
925
926
927
928
class FileAttachment(AttachmentBase):
    """Attachment representing a generic file."""

    type: Literal["file"] = "file"

ImageAttachment

Bases: AttachmentBase

Attachment representing an image resource.

Source code in chatkit/types.py 
931
932
933
934
935
class ImageAttachment(AttachmentBase):
    """Attachment representing an image resource."""

    type: Literal["image"] = "image"
    preview_url: AnyUrl

Workflow

Bases: BaseModel

Workflow attached to a thread with optional summary.

Source code in chatkit/types.py 
948
949
950
951
952
953
954
class Workflow(BaseModel):
    """Workflow attached to a thread with optional summary."""

    type: Literal["custom", "reasoning"]
    tasks: list[Task]
    summary: WorkflowSummary | None = None
    expanded: bool = False

CustomSummary

Bases: BaseModel

Custom summary for a workflow.

Source code in chatkit/types.py 
957
958
959
960
961
class CustomSummary(BaseModel):
    """Custom summary for a workflow."""

    title: str
    icon: IconName | None = None

DurationSummary

Bases: BaseModel

Summary providing total workflow duration.

Source code in chatkit/types.py 
964
965
966
967
968
class DurationSummary(BaseModel):
    """Summary providing total workflow duration."""

    duration: int
    """The duration of the workflow in seconds"""

duration instance-attribute 

duration: int

The duration of the workflow in seconds

BaseTask

Bases: BaseModel

Base fields common to all workflow tasks.

Source code in chatkit/types.py 
977
978
979
980
981
class BaseTask(BaseModel):
    """Base fields common to all workflow tasks."""

    status_indicator: Literal["none", "loading", "complete"] = "none"
    """Only used when rendering the task as part of a workflow. Indicates the status of the task."""

status_indicator class-attribute instance-attribute 

status_indicator: Literal["none", "loading", "complete"] = (
    "none"
)

Only used when rendering the task as part of a workflow. Indicates the status of the task.

CustomTask

Bases: BaseTask

Workflow task displaying custom content.

Source code in chatkit/types.py 
984
985
986
987
988
989
990
class CustomTask(BaseTask):
    """Workflow task displaying custom content."""

    type: Literal["custom"] = "custom"
    title: str | None = None
    icon: IconName | None = None
    content: str | None = None

SearchTask

Bases: BaseTask

Workflow task representing a web search.

Source code in chatkit/types.py 
 993
 994
 995
 996
 997
 998
 999
1000
class SearchTask(BaseTask):
    """Workflow task representing a web search."""

    type: Literal["web_search"] = "web_search"
    title: str | None = None
    title_query: str | None = None
    queries: list[str] = Field(default_factory=list)
    sources: list[URLSource] = Field(default_factory=list)

ThoughtTask

Bases: BaseTask

Workflow task capturing assistant reasoning.

Source code in chatkit/types.py 
1003
1004
1005
1006
1007
1008
class ThoughtTask(BaseTask):
    """Workflow task capturing assistant reasoning."""

    type: Literal["thought"] = "thought"
    title: str | None = None
    content: str

FileTask

Bases: BaseTask

Workflow task referencing file sources.

Source code in chatkit/types.py 
1011
1012
1013
1014
1015
1016
class FileTask(BaseTask):
    """Workflow task referencing file sources."""

    type: Literal["file"] = "file"
    title: str | None = None
    sources: list[FileSource] = Field(default_factory=list)

ImageTask

Bases: BaseTask

Workflow task rendering image content.

Source code in chatkit/types.py 
1019
1020
1021
1022
1023
class ImageTask(BaseTask):
    """Workflow task rendering image content."""

    type: Literal["image"] = "image"
    title: str | None = None

SourceBase

Bases: BaseModel

Base class for sources displayed to users.

Source code in chatkit/types.py 
1036
1037
1038
1039
1040
1041
1042
class SourceBase(BaseModel):
    """Base class for sources displayed to users."""

    title: str
    description: str | None = None
    timestamp: str | None = None
    group: str | None = None

FileSource

Bases: SourceBase

Source metadata for file-based references.

Source code in chatkit/types.py 
1045
1046
1047
1048
1049
class FileSource(SourceBase):
    """Source metadata for file-based references."""

    type: Literal["file"] = "file"
    filename: str

URLSource

Bases: SourceBase

Source metadata for external URLs.

Source code in chatkit/types.py 
1052
1053
1054
1055
1056
1057
class URLSource(SourceBase):
    """Source metadata for external URLs."""

    type: Literal["url"] = "url"
    url: str
    attribution: str | None = None

EntitySource

Bases: SourceBase

Source metadata for entity references.

Source code in chatkit/types.py 
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
class EntitySource(SourceBase):
    """Source metadata for entity references."""

    type: Literal["entity"] = "entity"
    id: str
    icon: IconName | None = None
    label: str | None = None
    """Optional label shown with the icon in the default entity hover header
    when no preview callback is provided.
    """
    inline_label: str | None = None
    """Optional label for the inline annotation view. When not provided, the icon is used instead."""
    interactive: bool = False
    """Per-entity toggle to wire client callbacks and render this entity as interactive."""
    data: dict[str, Any] = Field(default_factory=dict)
    """Additional data for the entity source that is passed to client entity callbacks."""

    preview: Literal["lazy"] | None = Field(
        default=None,
        deprecated=True,
        description="This field is ignored. Please use the entities.onRequestPreview ChatKit.js option instead.",
    )

label class-attribute instance-attribute 

label: str | None = None

Optional label shown with the icon in the default entity hover header when no preview callback is provided.

inline_label class-attribute instance-attribute 

inline_label: str | None = None

Optional label for the inline annotation view. When not provided, the icon is used instead.

interactive class-attribute instance-attribute 

interactive: bool = False

Per-entity toggle to wire client callbacks and render this entity as interactive.

data class-attribute instance-attribute 

data: dict[str, Any] = Field(default_factory=dict)

Additional data for the entity source that is passed to client entity callbacks.

is_streaming_req 

is_streaming_req(
    request: ChatKitReq,
) -> TypeIs[StreamingReq]

Return True if the given request should be processed as streaming.

Source code in chatkit/types.py 
336
337
338
339
340
341
342
343
344
345
346
347
348
def is_streaming_req(request: ChatKitReq) -> TypeIs[StreamingReq]:
    """Return True if the given request should be processed as streaming."""
    return isinstance(
        request,
        (
            ThreadsCreateReq,
            ThreadsAddUserMessageReq,
            ThreadsRetryAfterItemReq,
            ThreadsAddClientToolOutputReq,
            ThreadsAddStructuredInputReq,
            ThreadsCustomActionReq,
        ),
    )