Skip to content

requests

Request objects decoded from the ChatKit browser protocol.

StreamingReq module-attribute

Union of request types that produce streaming responses.

NonStreamingReq module-attribute

Union of request types that yield immediate responses.

ChatKitReq module-attribute

ChatKitReq = Annotated[StreamingReq | NonStreamingReq, Field(discriminator='type')]

Validated browser operations, discriminated by their type field.

BaseReq

Bases: BaseModel

Base class for all request payloads.

Source code in chatkit/requests.py
10
11
12
13
14
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/requests.py
17
18
19
20
21
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/requests.py
24
25
26
27
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/requests.py
30
31
32
33
34
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/requests.py
37
38
39
40
class ThreadCreateParams(BaseModel):
    """User input required to create a thread."""

    input: models.UserMessageInput

ThreadListParams

Bases: BaseModel

Pagination parameters for listing threads.

Source code in chatkit/requests.py
43
44
45
46
47
48
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/requests.py
51
52
53
54
55
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/requests.py
58
59
60
61
62
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/requests.py
65
66
67
68
69
class ThreadAddUserMessageParams(BaseModel):
    """Parameters for adding a user message to a thread."""

    input: models.UserMessageInput
    thread_id: str

ThreadsAddClientToolOutputReq

Bases: BaseReq

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

Source code in chatkit/requests.py
72
73
74
75
76
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

ClientToolCallbackResult

Bases: BaseModel

Output for one exact client tool invocation.

Source code in chatkit/requests.py
79
80
81
82
83
84
85
class ClientToolCallbackResult(BaseModel):
    """Output for one exact client tool invocation."""

    model_config = ConfigDict(extra="forbid")

    item_id: Annotated[str, Field(min_length=1, pattern=r"\S")]
    output: Any

ThreadAddClientToolOutputParams

Bases: BaseModel

Parameters for recording tool output in a thread.

Source code in chatkit/requests.py
88
89
90
91
92
class ThreadAddClientToolOutputParams(BaseModel):
    """Parameters for recording tool output in a thread."""

    thread_id: str
    result: ClientToolCallbackResult

StructuredInputAnswerSubmission

Bases: BaseModel

Client-submitted answer for a structured input.

Source code in chatkit/requests.py
 95
 96
 97
 98
 99
100
101
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/requests.py
104
105
106
107
108
109
110
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/requests.py
113
114
115
116
117
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/requests.py
120
121
122
123
124
125
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/requests.py
128
129
130
131
132
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/requests.py
135
136
137
138
139
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/requests.py
142
143
144
145
146
147
class ThreadCustomActionParams(BaseModel):
    """Parameters describing the custom action to execute."""

    thread_id: str
    item_id: str | None = None
    action: actions.IncomingAction

ThreadsRetryAfterItemReq

Bases: BaseReq

Request to retry processing after a specific thread item.

Source code in chatkit/requests.py
150
151
152
153
154
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/requests.py
157
158
159
160
161
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/requests.py
164
165
166
167
168
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/requests.py
171
172
173
174
175
176
class ItemFeedbackParams(BaseModel):
    """Parameters describing feedback targets and sentiment."""

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

AttachmentsDeleteReq

Bases: BaseReq

Request to remove an attachment.

Source code in chatkit/requests.py
179
180
181
182
183
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/requests.py
186
187
188
189
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/requests.py
192
193
194
195
196
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/requests.py
199
200
201
202
203
204
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/requests.py
207
208
209
210
211
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/requests.py
214
215
216
217
218
219
220
221
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".

ItemsListReq

Bases: BaseReq

Request to list items inside a thread.

Source code in chatkit/requests.py
224
225
226
227
228
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/requests.py
231
232
233
234
235
236
237
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/requests.py
240
241
242
243
244
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/requests.py
247
248
249
250
251
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/requests.py
254
255
256
257
258
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/requests.py
261
262
263
264
class ThreadDeleteParams(BaseModel):
    """Parameters identifying a thread to delete."""

    thread_id: str

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/requests.py
300
301
302
def is_streaming_req(request: ChatKitReq) -> TypeIs[StreamingReq]:
    """Return True if the given request should be processed as streaming."""
    return isinstance(request, StreamingReq)