python/resources/beta/subresources/chatkit/index.md +0 −2645 deleted
File Deleted View Diff
1# ChatKit
2
3## Domain Types
4
5### ChatKit Workflow
6
7- `class ChatKitWorkflow: …`
8
9 Workflow metadata and state returned for the session.
10
11 - `id: str`
12
13 Identifier of the workflow backing the session.
14
15 - `state_variables: Optional[Dict[str, Union[str, bool, float]]]`
16
17 State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
18
19 - `str`
20
21 - `bool`
22
23 - `float`
24
25 - `tracing: Tracing`
26
27 Tracing settings applied to the workflow.
28
29 - `enabled: bool`
30
31 Indicates whether tracing is enabled.
32
33 - `version: Optional[str]`
34
35 Specific workflow version used for the session. Defaults to null when using the latest deployment.
36
37# Sessions
38
39## Cancel chat session
40
41`beta.chatkit.sessions.cancel(strsession_id) -> ChatSession`
42
43**post** `/chatkit/sessions/{session_id}/cancel`
44
45Cancel an active ChatKit session and return its most recent metadata.
46
47Cancelling prevents new requests from using the issued client secret.
48
49### Parameters
50
51- `session_id: str`
52
53### Returns
54
55- `class ChatSession: …`
56
57 Represents a ChatKit session and its resolved configuration.
58
59 - `id: str`
60
61 Identifier for the ChatKit session.
62
63 - `chatkit_configuration: ChatSessionChatKitConfiguration`
64
65 Resolved ChatKit feature configuration for the session.
66
67 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`
68
69 Automatic thread titling preferences.
70
71 - `enabled: bool`
72
73 Whether automatic thread titling is enabled.
74
75 - `file_upload: ChatSessionFileUpload`
76
77 Upload settings for the session.
78
79 - `enabled: bool`
80
81 Indicates if uploads are enabled for the session.
82
83 - `max_file_size: Optional[int]`
84
85 Maximum upload size in megabytes.
86
87 - `max_files: Optional[int]`
88
89 Maximum number of uploads allowed during the session.
90
91 - `history: ChatSessionHistory`
92
93 History retention configuration.
94
95 - `enabled: bool`
96
97 Indicates if chat history is persisted for the session.
98
99 - `recent_threads: Optional[int]`
100
101 Number of prior threads surfaced in history views. Defaults to null when all history is retained.
102
103 - `client_secret: str`
104
105 Ephemeral client secret that authenticates session requests.
106
107 - `expires_at: int`
108
109 Unix timestamp (in seconds) for when the session expires.
110
111 - `max_requests_per_1_minute: int`
112
113 Convenience copy of the per-minute request limit.
114
115 - `object: Literal["chatkit.session"]`
116
117 Type discriminator that is always `chatkit.session`.
118
119 - `"chatkit.session"`
120
121 - `rate_limits: ChatSessionRateLimits`
122
123 Resolved rate limit values.
124
125 - `max_requests_per_1_minute: int`
126
127 Maximum allowed requests per one-minute window.
128
129 - `status: ChatSessionStatus`
130
131 Current lifecycle state of the session.
132
133 - `"active"`
134
135 - `"expired"`
136
137 - `"cancelled"`
138
139 - `user: str`
140
141 User identifier associated with the session.
142
143 - `workflow: ChatKitWorkflow`
144
145 Workflow metadata for the session.
146
147 - `id: str`
148
149 Identifier of the workflow backing the session.
150
151 - `state_variables: Optional[Dict[str, Union[str, bool, float]]]`
152
153 State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
154
155 - `str`
156
157 - `bool`
158
159 - `float`
160
161 - `tracing: Tracing`
162
163 Tracing settings applied to the workflow.
164
165 - `enabled: bool`
166
167 Indicates whether tracing is enabled.
168
169 - `version: Optional[str]`
170
171 Specific workflow version used for the session. Defaults to null when using the latest deployment.
172
173### Example
174
175```python
176import os
177from openai import OpenAI
178
179client = OpenAI(
180 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
181)
182chat_session = client.beta.chatkit.sessions.cancel(
183 "cksess_123",
184)
185print(chat_session.id)
186```
187
188#### Response
189
190```json
191{
192 "id": "id",
193 "chatkit_configuration": {
194 "automatic_thread_titling": {
195 "enabled": true
196 },
197 "file_upload": {
198 "enabled": true,
199 "max_file_size": 0,
200 "max_files": 0
201 },
202 "history": {
203 "enabled": true,
204 "recent_threads": 0
205 }
206 },
207 "client_secret": "client_secret",
208 "expires_at": 0,
209 "max_requests_per_1_minute": 0,
210 "object": "chatkit.session",
211 "rate_limits": {
212 "max_requests_per_1_minute": 0
213 },
214 "status": "active",
215 "user": "user",
216 "workflow": {
217 "id": "id",
218 "state_variables": {
219 "foo": "string"
220 },
221 "tracing": {
222 "enabled": true
223 },
224 "version": "version"
225 }
226}
227```
228
229### Example
230
231```python
232from openai import OpenAI
233
234client = OpenAI()
235chat_session = client.beta.chatkit.sessions.cancel(
236 "cksess_123",
237)
238print(chat_session.id)
239```
240
241#### Response
242
243```json
244{
245 "id": "cksess_123",
246 "object": "chatkit.session",
247 "workflow": {
248 "id": "workflow_alpha",
249 "version": "1"
250 },
251 "scope": {
252 "customer_id": "cust_456"
253 },
254 "max_requests_per_1_minute": 30,
255 "ttl_seconds": 900,
256 "status": "cancelled",
257 "cancelled_at": 1712345678
258}
259```
260
261## Create ChatKit session
262
263`beta.chatkit.sessions.create(SessionCreateParams**kwargs) -> ChatSession`
264
265**post** `/chatkit/sessions`
266
267Create a ChatKit session.
268
269### Parameters
270
271- `user: str`
272
273 A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.
274
275- `workflow: ChatSessionWorkflowParam`
276
277 Workflow that powers the session.
278
279 - `id: str`
280
281 Identifier for the workflow invoked by the session.
282
283 - `state_variables: Optional[Dict[str, Union[str, bool, float]]]`
284
285 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.
286
287 - `str`
288
289 - `bool`
290
291 - `float`
292
293 - `tracing: Optional[Tracing]`
294
295 Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default.
296
297 - `enabled: Optional[bool]`
298
299 Whether tracing is enabled during the session. Defaults to true.
300
301 - `version: Optional[str]`
302
303 Specific workflow version to run. Defaults to the latest deployed version.
304
305- `chatkit_configuration: Optional[ChatSessionChatKitConfigurationParam]`
306
307 Optional overrides for ChatKit runtime configuration features
308
309 - `automatic_thread_titling: Optional[AutomaticThreadTitling]`
310
311 Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.
312
313 - `enabled: Optional[bool]`
314
315 Enable automatic thread title generation. Defaults to true.
316
317 - `file_upload: Optional[FileUpload]`
318
319 Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).
320
321 - `enabled: Optional[bool]`
322
323 Enable uploads for this session. Defaults to false.
324
325 - `max_file_size: Optional[int]`
326
327 Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.
328
329 - `max_files: Optional[int]`
330
331 Maximum number of files that can be uploaded to the session. Defaults to 10.
332
333 - `history: Optional[History]`
334
335 Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null).
336
337 - `enabled: Optional[bool]`
338
339 Enables chat users to access previous ChatKit threads. Defaults to true.
340
341 - `recent_threads: Optional[int]`
342
343 Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.
344
345- `expires_after: Optional[ChatSessionExpiresAfterParam]`
346
347 Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.
348
349 - `anchor: Literal["created_at"]`
350
351 Base timestamp used to calculate expiration. Currently fixed to `created_at`.
352
353 - `"created_at"`
354
355 - `seconds: int`
356
357 Number of seconds after the anchor when the session expires.
358
359- `rate_limits: Optional[ChatSessionRateLimitsParam]`
360
361 Optional override for per-minute request limits. When omitted, defaults to 10.
362
363 - `max_requests_per_1_minute: Optional[int]`
364
365 Maximum number of requests allowed per minute for the session. Defaults to 10.
366
367### Returns
368
369- `class ChatSession: …`
370
371 Represents a ChatKit session and its resolved configuration.
372
373 - `id: str`
374
375 Identifier for the ChatKit session.
376
377 - `chatkit_configuration: ChatSessionChatKitConfiguration`
378
379 Resolved ChatKit feature configuration for the session.
380
381 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`
382
383 Automatic thread titling preferences.
384
385 - `enabled: bool`
386
387 Whether automatic thread titling is enabled.
388
389 - `file_upload: ChatSessionFileUpload`
390
391 Upload settings for the session.
392
393 - `enabled: bool`
394
395 Indicates if uploads are enabled for the session.
396
397 - `max_file_size: Optional[int]`
398
399 Maximum upload size in megabytes.
400
401 - `max_files: Optional[int]`
402
403 Maximum number of uploads allowed during the session.
404
405 - `history: ChatSessionHistory`
406
407 History retention configuration.
408
409 - `enabled: bool`
410
411 Indicates if chat history is persisted for the session.
412
413 - `recent_threads: Optional[int]`
414
415 Number of prior threads surfaced in history views. Defaults to null when all history is retained.
416
417 - `client_secret: str`
418
419 Ephemeral client secret that authenticates session requests.
420
421 - `expires_at: int`
422
423 Unix timestamp (in seconds) for when the session expires.
424
425 - `max_requests_per_1_minute: int`
426
427 Convenience copy of the per-minute request limit.
428
429 - `object: Literal["chatkit.session"]`
430
431 Type discriminator that is always `chatkit.session`.
432
433 - `"chatkit.session"`
434
435 - `rate_limits: ChatSessionRateLimits`
436
437 Resolved rate limit values.
438
439 - `max_requests_per_1_minute: int`
440
441 Maximum allowed requests per one-minute window.
442
443 - `status: ChatSessionStatus`
444
445 Current lifecycle state of the session.
446
447 - `"active"`
448
449 - `"expired"`
450
451 - `"cancelled"`
452
453 - `user: str`
454
455 User identifier associated with the session.
456
457 - `workflow: ChatKitWorkflow`
458
459 Workflow metadata for the session.
460
461 - `id: str`
462
463 Identifier of the workflow backing the session.
464
465 - `state_variables: Optional[Dict[str, Union[str, bool, float]]]`
466
467 State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
468
469 - `str`
470
471 - `bool`
472
473 - `float`
474
475 - `tracing: Tracing`
476
477 Tracing settings applied to the workflow.
478
479 - `enabled: bool`
480
481 Indicates whether tracing is enabled.
482
483 - `version: Optional[str]`
484
485 Specific workflow version used for the session. Defaults to null when using the latest deployment.
486
487### Example
488
489```python
490import os
491from openai import OpenAI
492
493client = OpenAI(
494 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
495)
496chat_session = client.beta.chatkit.sessions.create(
497 user="x",
498 workflow={
499 "id": "id"
500 },
501)
502print(chat_session.id)
503```
504
505#### Response
506
507```json
508{
509 "id": "id",
510 "chatkit_configuration": {
511 "automatic_thread_titling": {
512 "enabled": true
513 },
514 "file_upload": {
515 "enabled": true,
516 "max_file_size": 0,
517 "max_files": 0
518 },
519 "history": {
520 "enabled": true,
521 "recent_threads": 0
522 }
523 },
524 "client_secret": "client_secret",
525 "expires_at": 0,
526 "max_requests_per_1_minute": 0,
527 "object": "chatkit.session",
528 "rate_limits": {
529 "max_requests_per_1_minute": 0
530 },
531 "status": "active",
532 "user": "user",
533 "workflow": {
534 "id": "id",
535 "state_variables": {
536 "foo": "string"
537 },
538 "tracing": {
539 "enabled": true
540 },
541 "version": "version"
542 }
543}
544```
545
546### Example
547
548```python
549from openai import OpenAI
550
551client = OpenAI()
552chat_session = client.beta.chatkit.sessions.create(
553 user="user",
554 workflow={
555 "id": "id"
556 },
557)
558print(chat_session.id)
559```
560
561#### Response
562
563```json
564{
565 "client_secret": "chatkit_token_123",
566 "expires_at": 1735689600,
567 "workflow": {
568 "id": "workflow_alpha",
569 "version": "2024-10-01"
570 },
571 "scope": {
572 "project": "alpha",
573 "environment": "staging"
574 },
575 "max_requests_per_1_minute": 60,
576 "max_requests_per_session": 500,
577 "status": "active"
578}
579```
580
581# Threads
582
583## List ChatKit thread items
584
585`beta.chatkit.threads.list_items(strthread_id, ThreadListItemsParams**kwargs) -> SyncConversationCursorPage[Data]`
586
587**get** `/chatkit/threads/{thread_id}/items`
588
589List items that belong to a ChatKit thread.
590
591### Parameters
592
593- `thread_id: str`
594
595- `after: Optional[str]`
596
597 List items created after this thread item ID. Defaults to null for the first page.
598
599- `before: Optional[str]`
600
601 List items created before this thread item ID. Defaults to null for the newest results.
602
603- `limit: Optional[int]`
604
605 Maximum number of thread items to return. Defaults to 20.
606
607- `order: Optional[Literal["asc", "desc"]]`
608
609 Sort order for results by creation time. Defaults to `desc`.
610
611 - `"asc"`
612
613 - `"desc"`
614
615### Returns
616
617- `Data`
618
619 - `class ChatKitThreadUserMessageItem: …`
620
621 User-authored messages within a thread.
622
623 - `id: str`
624
625 Identifier of the thread item.
626
627 - `attachments: List[ChatKitAttachment]`
628
629 Attachments associated with the user message. Defaults to an empty list.
630
631 - `id: str`
632
633 Identifier for the attachment.
634
635 - `mime_type: str`
636
637 MIME type of the attachment.
638
639 - `name: str`
640
641 Original display name for the attachment.
642
643 - `preview_url: Optional[str]`
644
645 Preview URL for rendering the attachment inline.
646
647 - `type: Literal["image", "file"]`
648
649 Attachment discriminator.
650
651 - `"image"`
652
653 - `"file"`
654
655 - `content: List[Content]`
656
657 Ordered content elements supplied by the user.
658
659 - `class ContentInputText: …`
660
661 Text block that a user contributed to the thread.
662
663 - `text: str`
664
665 Plain-text content supplied by the user.
666
667 - `type: Literal["input_text"]`
668
669 Type discriminator that is always `input_text`.
670
671 - `"input_text"`
672
673 - `class ContentQuotedText: …`
674
675 Quoted snippet that the user referenced in their message.
676
677 - `text: str`
678
679 Quoted text content.
680
681 - `type: Literal["quoted_text"]`
682
683 Type discriminator that is always `quoted_text`.
684
685 - `"quoted_text"`
686
687 - `created_at: int`
688
689 Unix timestamp (in seconds) for when the item was created.
690
691 - `inference_options: Optional[InferenceOptions]`
692
693 Inference overrides applied to the message. Defaults to null when unset.
694
695 - `model: Optional[str]`
696
697 Model name that generated the response. Defaults to null when using the session default.
698
699 - `tool_choice: Optional[InferenceOptionsToolChoice]`
700
701 Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
702
703 - `id: str`
704
705 Identifier of the requested tool.
706
707 - `object: Literal["chatkit.thread_item"]`
708
709 Type discriminator that is always `chatkit.thread_item`.
710
711 - `"chatkit.thread_item"`
712
713 - `thread_id: str`
714
715 Identifier of the parent thread.
716
717 - `type: Literal["chatkit.user_message"]`
718
719 - `"chatkit.user_message"`
720
721 - `class ChatKitThreadAssistantMessageItem: …`
722
723 Assistant-authored message within a thread.
724
725 - `id: str`
726
727 Identifier of the thread item.
728
729 - `content: List[ChatKitResponseOutputText]`
730
731 Ordered assistant response segments.
732
733 - `annotations: List[Annotation]`
734
735 Ordered list of annotations attached to the response text.
736
737 - `class AnnotationFile: …`
738
739 Annotation that references an uploaded file.
740
741 - `source: AnnotationFileSource`
742
743 File attachment referenced by the annotation.
744
745 - `filename: str`
746
747 Filename referenced by the annotation.
748
749 - `type: Literal["file"]`
750
751 Type discriminator that is always `file`.
752
753 - `"file"`
754
755 - `type: Literal["file"]`
756
757 Type discriminator that is always `file` for this annotation.
758
759 - `"file"`
760
761 - `class AnnotationURL: …`
762
763 Annotation that references a URL.
764
765 - `source: AnnotationURLSource`
766
767 URL referenced by the annotation.
768
769 - `type: Literal["url"]`
770
771 Type discriminator that is always `url`.
772
773 - `"url"`
774
775 - `url: str`
776
777 URL referenced by the annotation.
778
779 - `type: Literal["url"]`
780
781 Type discriminator that is always `url` for this annotation.
782
783 - `"url"`
784
785 - `text: str`
786
787 Assistant generated text.
788
789 - `type: Literal["output_text"]`
790
791 Type discriminator that is always `output_text`.
792
793 - `"output_text"`
794
795 - `created_at: int`
796
797 Unix timestamp (in seconds) for when the item was created.
798
799 - `object: Literal["chatkit.thread_item"]`
800
801 Type discriminator that is always `chatkit.thread_item`.
802
803 - `"chatkit.thread_item"`
804
805 - `thread_id: str`
806
807 Identifier of the parent thread.
808
809 - `type: Literal["chatkit.assistant_message"]`
810
811 Type discriminator that is always `chatkit.assistant_message`.
812
813 - `"chatkit.assistant_message"`
814
815 - `class ChatKitWidgetItem: …`
816
817 Thread item that renders a widget payload.
818
819 - `id: str`
820
821 Identifier of the thread item.
822
823 - `created_at: int`
824
825 Unix timestamp (in seconds) for when the item was created.
826
827 - `object: Literal["chatkit.thread_item"]`
828
829 Type discriminator that is always `chatkit.thread_item`.
830
831 - `"chatkit.thread_item"`
832
833 - `thread_id: str`
834
835 Identifier of the parent thread.
836
837 - `type: Literal["chatkit.widget"]`
838
839 Type discriminator that is always `chatkit.widget`.
840
841 - `"chatkit.widget"`
842
843 - `widget: str`
844
845 Serialized widget payload rendered in the UI.
846
847 - `class DataChatKitClientToolCall: …`
848
849 Record of a client side tool invocation initiated by the assistant.
850
851 - `id: str`
852
853 Identifier of the thread item.
854
855 - `arguments: str`
856
857 JSON-encoded arguments that were sent to the tool.
858
859 - `call_id: str`
860
861 Identifier for the client tool call.
862
863 - `created_at: int`
864
865 Unix timestamp (in seconds) for when the item was created.
866
867 - `name: str`
868
869 Tool name that was invoked.
870
871 - `object: Literal["chatkit.thread_item"]`
872
873 Type discriminator that is always `chatkit.thread_item`.
874
875 - `"chatkit.thread_item"`
876
877 - `output: Optional[str]`
878
879 JSON-encoded output captured from the tool. Defaults to null while execution is in progress.
880
881 - `status: Literal["in_progress", "completed"]`
882
883 Execution status for the tool call.
884
885 - `"in_progress"`
886
887 - `"completed"`
888
889 - `thread_id: str`
890
891 Identifier of the parent thread.
892
893 - `type: Literal["chatkit.client_tool_call"]`
894
895 Type discriminator that is always `chatkit.client_tool_call`.
896
897 - `"chatkit.client_tool_call"`
898
899 - `class DataChatKitTask: …`
900
901 Task emitted by the workflow to show progress and status updates.
902
903 - `id: str`
904
905 Identifier of the thread item.
906
907 - `created_at: int`
908
909 Unix timestamp (in seconds) for when the item was created.
910
911 - `heading: Optional[str]`
912
913 Optional heading for the task. Defaults to null when not provided.
914
915 - `object: Literal["chatkit.thread_item"]`
916
917 Type discriminator that is always `chatkit.thread_item`.
918
919 - `"chatkit.thread_item"`
920
921 - `summary: Optional[str]`
922
923 Optional summary that describes the task. Defaults to null when omitted.
924
925 - `task_type: Literal["custom", "thought"]`
926
927 Subtype for the task.
928
929 - `"custom"`
930
931 - `"thought"`
932
933 - `thread_id: str`
934
935 Identifier of the parent thread.
936
937 - `type: Literal["chatkit.task"]`
938
939 Type discriminator that is always `chatkit.task`.
940
941 - `"chatkit.task"`
942
943 - `class DataChatKitTaskGroup: …`
944
945 Collection of workflow tasks grouped together in the thread.
946
947 - `id: str`
948
949 Identifier of the thread item.
950
951 - `created_at: int`
952
953 Unix timestamp (in seconds) for when the item was created.
954
955 - `object: Literal["chatkit.thread_item"]`
956
957 Type discriminator that is always `chatkit.thread_item`.
958
959 - `"chatkit.thread_item"`
960
961 - `tasks: List[DataChatKitTaskGroupTask]`
962
963 Tasks included in the group.
964
965 - `heading: Optional[str]`
966
967 Optional heading for the grouped task. Defaults to null when not provided.
968
969 - `summary: Optional[str]`
970
971 Optional summary that describes the grouped task. Defaults to null when omitted.
972
973 - `type: Literal["custom", "thought"]`
974
975 Subtype for the grouped task.
976
977 - `"custom"`
978
979 - `"thought"`
980
981 - `thread_id: str`
982
983 Identifier of the parent thread.
984
985 - `type: Literal["chatkit.task_group"]`
986
987 Type discriminator that is always `chatkit.task_group`.
988
989 - `"chatkit.task_group"`
990
991### Example
992
993```python
994import os
995from openai import OpenAI
996
997client = OpenAI(
998 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
999)
1000page = client.beta.chatkit.threads.list_items(
1001 thread_id="cthr_123",
1002)
1003page = page.data[0]
1004print(page)
1005```
1006
1007#### Response
1008
1009```json
1010{
1011 "data": [
1012 {
1013 "id": "id",
1014 "attachments": [
1015 {
1016 "id": "id",
1017 "mime_type": "mime_type",
1018 "name": "name",
1019 "preview_url": "https://example.com",
1020 "type": "image"
1021 }
1022 ],
1023 "content": [
1024 {
1025 "text": "text",
1026 "type": "input_text"
1027 }
1028 ],
1029 "created_at": 0,
1030 "inference_options": {
1031 "model": "model",
1032 "tool_choice": {
1033 "id": "id"
1034 }
1035 },
1036 "object": "chatkit.thread_item",
1037 "thread_id": "thread_id",
1038 "type": "chatkit.user_message"
1039 }
1040 ],
1041 "first_id": "first_id",
1042 "has_more": true,
1043 "last_id": "last_id",
1044 "object": "list"
1045}
1046```
1047
1048### Example
1049
1050```python
1051from openai import OpenAI
1052
1053client = OpenAI()
1054page = client.beta.chatkit.threads.list_items(
1055 thread_id="cthr_123",
1056)
1057page = page.data[0]
1058print(page)
1059```
1060
1061#### Response
1062
1063```json
1064{
1065 "data": [
1066 {
1067 "id": "cthi_user_001",
1068 "object": "chatkit.thread_item",
1069 "type": "user_message",
1070 "content": [
1071 {
1072 "type": "input_text",
1073 "text": "I need help debugging an onboarding issue."
1074 }
1075 ],
1076 "attachments": []
1077 },
1078 {
1079 "id": "cthi_assistant_002",
1080 "object": "chatkit.thread_item",
1081 "type": "assistant_message",
1082 "content": [
1083 {
1084 "type": "output_text",
1085 "text": "Let's start by confirming the workflow version you deployed."
1086 }
1087 ]
1088 }
1089 ],
1090 "has_more": false,
1091 "object": "list"
1092}
1093```
1094
1095## Retrieve ChatKit thread
1096
1097`beta.chatkit.threads.retrieve(strthread_id) -> ChatKitThread`
1098
1099**get** `/chatkit/threads/{thread_id}`
1100
1101Retrieve a ChatKit thread by its identifier.
1102
1103### Parameters
1104
1105- `thread_id: str`
1106
1107### Returns
1108
1109- `class ChatKitThread: …`
1110
1111 Represents a ChatKit thread and its current status.
1112
1113 - `id: str`
1114
1115 Identifier of the thread.
1116
1117 - `created_at: int`
1118
1119 Unix timestamp (in seconds) for when the thread was created.
1120
1121 - `object: Literal["chatkit.thread"]`
1122
1123 Type discriminator that is always `chatkit.thread`.
1124
1125 - `"chatkit.thread"`
1126
1127 - `status: Status`
1128
1129 Current status for the thread. Defaults to `active` for newly created threads.
1130
1131 - `class StatusActive: …`
1132
1133 Indicates that a thread is active.
1134
1135 - `type: Literal["active"]`
1136
1137 Status discriminator that is always `active`.
1138
1139 - `"active"`
1140
1141 - `class StatusLocked: …`
1142
1143 Indicates that a thread is locked and cannot accept new input.
1144
1145 - `reason: Optional[str]`
1146
1147 Reason that the thread was locked. Defaults to null when no reason is recorded.
1148
1149 - `type: Literal["locked"]`
1150
1151 Status discriminator that is always `locked`.
1152
1153 - `"locked"`
1154
1155 - `class StatusClosed: …`
1156
1157 Indicates that a thread has been closed.
1158
1159 - `reason: Optional[str]`
1160
1161 Reason that the thread was closed. Defaults to null when no reason is recorded.
1162
1163 - `type: Literal["closed"]`
1164
1165 Status discriminator that is always `closed`.
1166
1167 - `"closed"`
1168
1169 - `title: Optional[str]`
1170
1171 Optional human-readable title for the thread. Defaults to null when no title has been generated.
1172
1173 - `user: str`
1174
1175 Free-form string that identifies your end user who owns the thread.
1176
1177### Example
1178
1179```python
1180import os
1181from openai import OpenAI
1182
1183client = OpenAI(
1184 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1185)
1186chatkit_thread = client.beta.chatkit.threads.retrieve(
1187 "cthr_123",
1188)
1189print(chatkit_thread.id)
1190```
1191
1192#### Response
1193
1194```json
1195{
1196 "id": "cthr_def456",
1197 "created_at": 1712345600,
1198 "object": "chatkit.thread",
1199 "status": {
1200 "type": "active"
1201 },
1202 "title": "Demo feedback",
1203 "user": "user_456"
1204}
1205```
1206
1207### Example
1208
1209```python
1210from openai import OpenAI
1211
1212client = OpenAI()
1213chatkit_thread = client.beta.chatkit.threads.retrieve(
1214 "cthr_123",
1215)
1216print(chatkit_thread.id)
1217```
1218
1219#### Response
1220
1221```json
1222{
1223 "id": "cthr_abc123",
1224 "object": "chatkit.thread",
1225 "title": "Customer escalation",
1226 "items": {
1227 "data": [
1228 {
1229 "id": "cthi_user_001",
1230 "object": "chatkit.thread_item",
1231 "type": "user_message",
1232 "content": [
1233 {
1234 "type": "input_text",
1235 "text": "I need help debugging an onboarding issue."
1236 }
1237 ],
1238 "attachments": []
1239 },
1240 {
1241 "id": "cthi_assistant_002",
1242 "object": "chatkit.thread_item",
1243 "type": "assistant_message",
1244 "content": [
1245 {
1246 "type": "output_text",
1247 "text": "Let's start by confirming the workflow version you deployed."
1248 }
1249 ]
1250 }
1251 ],
1252 "has_more": false
1253 }
1254}
1255```
1256
1257## Delete ChatKit thread
1258
1259`beta.chatkit.threads.delete(strthread_id) -> ThreadDeleteResponse`
1260
1261**delete** `/chatkit/threads/{thread_id}`
1262
1263Delete a ChatKit thread along with its items and stored attachments.
1264
1265### Parameters
1266
1267- `thread_id: str`
1268
1269### Returns
1270
1271- `class ThreadDeleteResponse: …`
1272
1273 Confirmation payload returned after deleting a thread.
1274
1275 - `id: str`
1276
1277 Identifier of the deleted thread.
1278
1279 - `deleted: bool`
1280
1281 Indicates that the thread has been deleted.
1282
1283 - `object: Literal["chatkit.thread.deleted"]`
1284
1285 Type discriminator that is always `chatkit.thread.deleted`.
1286
1287 - `"chatkit.thread.deleted"`
1288
1289### Example
1290
1291```python
1292import os
1293from openai import OpenAI
1294
1295client = OpenAI(
1296 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1297)
1298thread = client.beta.chatkit.threads.delete(
1299 "cthr_123",
1300)
1301print(thread.id)
1302```
1303
1304#### Response
1305
1306```json
1307{
1308 "id": "id",
1309 "deleted": true,
1310 "object": "chatkit.thread.deleted"
1311}
1312```
1313
1314### Example
1315
1316```python
1317from openai import OpenAI
1318
1319client = OpenAI()
1320thread = client.beta.chat_kit.threads.delete(
1321 "cthr_123",
1322)
1323print(thread.id)
1324```
1325
1326## List ChatKit threads
1327
1328`beta.chatkit.threads.list(ThreadListParams**kwargs) -> SyncConversationCursorPage[ChatKitThread]`
1329
1330**get** `/chatkit/threads`
1331
1332List ChatKit threads with optional pagination and user filters.
1333
1334### Parameters
1335
1336- `after: Optional[str]`
1337
1338 List items created after this thread item ID. Defaults to null for the first page.
1339
1340- `before: Optional[str]`
1341
1342 List items created before this thread item ID. Defaults to null for the newest results.
1343
1344- `limit: Optional[int]`
1345
1346 Maximum number of thread items to return. Defaults to 20.
1347
1348- `order: Optional[Literal["asc", "desc"]]`
1349
1350 Sort order for results by creation time. Defaults to `desc`.
1351
1352 - `"asc"`
1353
1354 - `"desc"`
1355
1356- `user: Optional[str]`
1357
1358 Filter threads that belong to this user identifier. Defaults to null to return all users.
1359
1360### Returns
1361
1362- `class ChatKitThread: …`
1363
1364 Represents a ChatKit thread and its current status.
1365
1366 - `id: str`
1367
1368 Identifier of the thread.
1369
1370 - `created_at: int`
1371
1372 Unix timestamp (in seconds) for when the thread was created.
1373
1374 - `object: Literal["chatkit.thread"]`
1375
1376 Type discriminator that is always `chatkit.thread`.
1377
1378 - `"chatkit.thread"`
1379
1380 - `status: Status`
1381
1382 Current status for the thread. Defaults to `active` for newly created threads.
1383
1384 - `class StatusActive: …`
1385
1386 Indicates that a thread is active.
1387
1388 - `type: Literal["active"]`
1389
1390 Status discriminator that is always `active`.
1391
1392 - `"active"`
1393
1394 - `class StatusLocked: …`
1395
1396 Indicates that a thread is locked and cannot accept new input.
1397
1398 - `reason: Optional[str]`
1399
1400 Reason that the thread was locked. Defaults to null when no reason is recorded.
1401
1402 - `type: Literal["locked"]`
1403
1404 Status discriminator that is always `locked`.
1405
1406 - `"locked"`
1407
1408 - `class StatusClosed: …`
1409
1410 Indicates that a thread has been closed.
1411
1412 - `reason: Optional[str]`
1413
1414 Reason that the thread was closed. Defaults to null when no reason is recorded.
1415
1416 - `type: Literal["closed"]`
1417
1418 Status discriminator that is always `closed`.
1419
1420 - `"closed"`
1421
1422 - `title: Optional[str]`
1423
1424 Optional human-readable title for the thread. Defaults to null when no title has been generated.
1425
1426 - `user: str`
1427
1428 Free-form string that identifies your end user who owns the thread.
1429
1430### Example
1431
1432```python
1433import os
1434from openai import OpenAI
1435
1436client = OpenAI(
1437 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1438)
1439page = client.beta.chatkit.threads.list()
1440page = page.data[0]
1441print(page.id)
1442```
1443
1444#### Response
1445
1446```json
1447{
1448 "data": [
1449 {
1450 "id": "cthr_def456",
1451 "created_at": 1712345600,
1452 "object": "chatkit.thread",
1453 "status": {
1454 "type": "active"
1455 },
1456 "title": "Demo feedback",
1457 "user": "user_456"
1458 }
1459 ],
1460 "first_id": "first_id",
1461 "has_more": true,
1462 "last_id": "last_id",
1463 "object": "list"
1464}
1465```
1466
1467### Example
1468
1469```python
1470from openai import OpenAI
1471
1472client = OpenAI()
1473page = client.beta.chatkit.threads.list()
1474page = page.data[0]
1475print(page.id)
1476```
1477
1478#### Response
1479
1480```json
1481{
1482 "data": [
1483 {
1484 "id": "cthr_abc123",
1485 "object": "chatkit.thread",
1486 "title": "Customer escalation"
1487 },
1488 {
1489 "id": "cthr_def456",
1490 "object": "chatkit.thread",
1491 "title": "Demo feedback"
1492 }
1493 ],
1494 "has_more": false,
1495 "object": "list"
1496}
1497```
1498
1499## Domain Types
1500
1501### Chat Session
1502
1503- `class ChatSession: …`
1504
1505 Represents a ChatKit session and its resolved configuration.
1506
1507 - `id: str`
1508
1509 Identifier for the ChatKit session.
1510
1511 - `chatkit_configuration: ChatSessionChatKitConfiguration`
1512
1513 Resolved ChatKit feature configuration for the session.
1514
1515 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`
1516
1517 Automatic thread titling preferences.
1518
1519 - `enabled: bool`
1520
1521 Whether automatic thread titling is enabled.
1522
1523 - `file_upload: ChatSessionFileUpload`
1524
1525 Upload settings for the session.
1526
1527 - `enabled: bool`
1528
1529 Indicates if uploads are enabled for the session.
1530
1531 - `max_file_size: Optional[int]`
1532
1533 Maximum upload size in megabytes.
1534
1535 - `max_files: Optional[int]`
1536
1537 Maximum number of uploads allowed during the session.
1538
1539 - `history: ChatSessionHistory`
1540
1541 History retention configuration.
1542
1543 - `enabled: bool`
1544
1545 Indicates if chat history is persisted for the session.
1546
1547 - `recent_threads: Optional[int]`
1548
1549 Number of prior threads surfaced in history views. Defaults to null when all history is retained.
1550
1551 - `client_secret: str`
1552
1553 Ephemeral client secret that authenticates session requests.
1554
1555 - `expires_at: int`
1556
1557 Unix timestamp (in seconds) for when the session expires.
1558
1559 - `max_requests_per_1_minute: int`
1560
1561 Convenience copy of the per-minute request limit.
1562
1563 - `object: Literal["chatkit.session"]`
1564
1565 Type discriminator that is always `chatkit.session`.
1566
1567 - `"chatkit.session"`
1568
1569 - `rate_limits: ChatSessionRateLimits`
1570
1571 Resolved rate limit values.
1572
1573 - `max_requests_per_1_minute: int`
1574
1575 Maximum allowed requests per one-minute window.
1576
1577 - `status: ChatSessionStatus`
1578
1579 Current lifecycle state of the session.
1580
1581 - `"active"`
1582
1583 - `"expired"`
1584
1585 - `"cancelled"`
1586
1587 - `user: str`
1588
1589 User identifier associated with the session.
1590
1591 - `workflow: ChatKitWorkflow`
1592
1593 Workflow metadata for the session.
1594
1595 - `id: str`
1596
1597 Identifier of the workflow backing the session.
1598
1599 - `state_variables: Optional[Dict[str, Union[str, bool, float]]]`
1600
1601 State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.
1602
1603 - `str`
1604
1605 - `bool`
1606
1607 - `float`
1608
1609 - `tracing: Tracing`
1610
1611 Tracing settings applied to the workflow.
1612
1613 - `enabled: bool`
1614
1615 Indicates whether tracing is enabled.
1616
1617 - `version: Optional[str]`
1618
1619 Specific workflow version used for the session. Defaults to null when using the latest deployment.
1620
1621### Chat Session Automatic Thread Titling
1622
1623- `class ChatSessionAutomaticThreadTitling: …`
1624
1625 Automatic thread title preferences for the session.
1626
1627 - `enabled: bool`
1628
1629 Whether automatic thread titling is enabled.
1630
1631### Chat Session ChatKit Configuration
1632
1633- `class ChatSessionChatKitConfiguration: …`
1634
1635 ChatKit configuration for the session.
1636
1637 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`
1638
1639 Automatic thread titling preferences.
1640
1641 - `enabled: bool`
1642
1643 Whether automatic thread titling is enabled.
1644
1645 - `file_upload: ChatSessionFileUpload`
1646
1647 Upload settings for the session.
1648
1649 - `enabled: bool`
1650
1651 Indicates if uploads are enabled for the session.
1652
1653 - `max_file_size: Optional[int]`
1654
1655 Maximum upload size in megabytes.
1656
1657 - `max_files: Optional[int]`
1658
1659 Maximum number of uploads allowed during the session.
1660
1661 - `history: ChatSessionHistory`
1662
1663 History retention configuration.
1664
1665 - `enabled: bool`
1666
1667 Indicates if chat history is persisted for the session.
1668
1669 - `recent_threads: Optional[int]`
1670
1671 Number of prior threads surfaced in history views. Defaults to null when all history is retained.
1672
1673### Chat Session ChatKit Configuration Param
1674
1675- `class ChatSessionChatKitConfigurationParam: …`
1676
1677 Optional per-session configuration settings for ChatKit behavior.
1678
1679 - `automatic_thread_titling: Optional[AutomaticThreadTitling]`
1680
1681 Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.
1682
1683 - `enabled: Optional[bool]`
1684
1685 Enable automatic thread title generation. Defaults to true.
1686
1687 - `file_upload: Optional[FileUpload]`
1688
1689 Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).
1690
1691 - `enabled: Optional[bool]`
1692
1693 Enable uploads for this session. Defaults to false.
1694
1695 - `max_file_size: Optional[int]`
1696
1697 Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.
1698
1699 - `max_files: Optional[int]`
1700
1701 Maximum number of files that can be uploaded to the session. Defaults to 10.
1702
1703 - `history: Optional[History]`
1704
1705 Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null).
1706
1707 - `enabled: Optional[bool]`
1708
1709 Enables chat users to access previous ChatKit threads. Defaults to true.
1710
1711 - `recent_threads: Optional[int]`
1712
1713 Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.
1714
1715### Chat Session Expires After Param
1716
1717- `class ChatSessionExpiresAfterParam: …`
1718
1719 Controls when the session expires relative to an anchor timestamp.
1720
1721 - `anchor: Literal["created_at"]`
1722
1723 Base timestamp used to calculate expiration. Currently fixed to `created_at`.
1724
1725 - `"created_at"`
1726
1727 - `seconds: int`
1728
1729 Number of seconds after the anchor when the session expires.
1730
1731### Chat Session File Upload
1732
1733- `class ChatSessionFileUpload: …`
1734
1735 Upload permissions and limits applied to the session.
1736
1737 - `enabled: bool`
1738
1739 Indicates if uploads are enabled for the session.
1740
1741 - `max_file_size: Optional[int]`
1742
1743 Maximum upload size in megabytes.
1744
1745 - `max_files: Optional[int]`
1746
1747 Maximum number of uploads allowed during the session.
1748
1749### Chat Session History
1750
1751- `class ChatSessionHistory: …`
1752
1753 History retention preferences returned for the session.
1754
1755 - `enabled: bool`
1756
1757 Indicates if chat history is persisted for the session.
1758
1759 - `recent_threads: Optional[int]`
1760
1761 Number of prior threads surfaced in history views. Defaults to null when all history is retained.
1762
1763### Chat Session Rate Limits
1764
1765- `class ChatSessionRateLimits: …`
1766
1767 Active per-minute request limit for the session.
1768
1769 - `max_requests_per_1_minute: int`
1770
1771 Maximum allowed requests per one-minute window.
1772
1773### Chat Session Rate Limits Param
1774
1775- `class ChatSessionRateLimitsParam: …`
1776
1777 Controls request rate limits for the session.
1778
1779 - `max_requests_per_1_minute: Optional[int]`
1780
1781 Maximum number of requests allowed per minute for the session. Defaults to 10.
1782
1783### Chat Session Status
1784
1785- `Literal["active", "expired", "cancelled"]`
1786
1787 - `"active"`
1788
1789 - `"expired"`
1790
1791 - `"cancelled"`
1792
1793### Chat Session Workflow Param
1794
1795- `class ChatSessionWorkflowParam: …`
1796
1797 Workflow reference and overrides applied to the chat session.
1798
1799 - `id: str`
1800
1801 Identifier for the workflow invoked by the session.
1802
1803 - `state_variables: Optional[Dict[str, Union[str, bool, float]]]`
1804
1805 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.
1806
1807 - `str`
1808
1809 - `bool`
1810
1811 - `float`
1812
1813 - `tracing: Optional[Tracing]`
1814
1815 Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default.
1816
1817 - `enabled: Optional[bool]`
1818
1819 Whether tracing is enabled during the session. Defaults to true.
1820
1821 - `version: Optional[str]`
1822
1823 Specific workflow version to run. Defaults to the latest deployed version.
1824
1825### ChatKit Attachment
1826
1827- `class ChatKitAttachment: …`
1828
1829 Attachment metadata included on thread items.
1830
1831 - `id: str`
1832
1833 Identifier for the attachment.
1834
1835 - `mime_type: str`
1836
1837 MIME type of the attachment.
1838
1839 - `name: str`
1840
1841 Original display name for the attachment.
1842
1843 - `preview_url: Optional[str]`
1844
1845 Preview URL for rendering the attachment inline.
1846
1847 - `type: Literal["image", "file"]`
1848
1849 Attachment discriminator.
1850
1851 - `"image"`
1852
1853 - `"file"`
1854
1855### ChatKit Response Output Text
1856
1857- `class ChatKitResponseOutputText: …`
1858
1859 Assistant response text accompanied by optional annotations.
1860
1861 - `annotations: List[Annotation]`
1862
1863 Ordered list of annotations attached to the response text.
1864
1865 - `class AnnotationFile: …`
1866
1867 Annotation that references an uploaded file.
1868
1869 - `source: AnnotationFileSource`
1870
1871 File attachment referenced by the annotation.
1872
1873 - `filename: str`
1874
1875 Filename referenced by the annotation.
1876
1877 - `type: Literal["file"]`
1878
1879 Type discriminator that is always `file`.
1880
1881 - `"file"`
1882
1883 - `type: Literal["file"]`
1884
1885 Type discriminator that is always `file` for this annotation.
1886
1887 - `"file"`
1888
1889 - `class AnnotationURL: …`
1890
1891 Annotation that references a URL.
1892
1893 - `source: AnnotationURLSource`
1894
1895 URL referenced by the annotation.
1896
1897 - `type: Literal["url"]`
1898
1899 Type discriminator that is always `url`.
1900
1901 - `"url"`
1902
1903 - `url: str`
1904
1905 URL referenced by the annotation.
1906
1907 - `type: Literal["url"]`
1908
1909 Type discriminator that is always `url` for this annotation.
1910
1911 - `"url"`
1912
1913 - `text: str`
1914
1915 Assistant generated text.
1916
1917 - `type: Literal["output_text"]`
1918
1919 Type discriminator that is always `output_text`.
1920
1921 - `"output_text"`
1922
1923### ChatKit Thread
1924
1925- `class ChatKitThread: …`
1926
1927 Represents a ChatKit thread and its current status.
1928
1929 - `id: str`
1930
1931 Identifier of the thread.
1932
1933 - `created_at: int`
1934
1935 Unix timestamp (in seconds) for when the thread was created.
1936
1937 - `object: Literal["chatkit.thread"]`
1938
1939 Type discriminator that is always `chatkit.thread`.
1940
1941 - `"chatkit.thread"`
1942
1943 - `status: Status`
1944
1945 Current status for the thread. Defaults to `active` for newly created threads.
1946
1947 - `class StatusActive: …`
1948
1949 Indicates that a thread is active.
1950
1951 - `type: Literal["active"]`
1952
1953 Status discriminator that is always `active`.
1954
1955 - `"active"`
1956
1957 - `class StatusLocked: …`
1958
1959 Indicates that a thread is locked and cannot accept new input.
1960
1961 - `reason: Optional[str]`
1962
1963 Reason that the thread was locked. Defaults to null when no reason is recorded.
1964
1965 - `type: Literal["locked"]`
1966
1967 Status discriminator that is always `locked`.
1968
1969 - `"locked"`
1970
1971 - `class StatusClosed: …`
1972
1973 Indicates that a thread has been closed.
1974
1975 - `reason: Optional[str]`
1976
1977 Reason that the thread was closed. Defaults to null when no reason is recorded.
1978
1979 - `type: Literal["closed"]`
1980
1981 Status discriminator that is always `closed`.
1982
1983 - `"closed"`
1984
1985 - `title: Optional[str]`
1986
1987 Optional human-readable title for the thread. Defaults to null when no title has been generated.
1988
1989 - `user: str`
1990
1991 Free-form string that identifies your end user who owns the thread.
1992
1993### ChatKit Thread Assistant Message Item
1994
1995- `class ChatKitThreadAssistantMessageItem: …`
1996
1997 Assistant-authored message within a thread.
1998
1999 - `id: str`
2000
2001 Identifier of the thread item.
2002
2003 - `content: List[ChatKitResponseOutputText]`
2004
2005 Ordered assistant response segments.
2006
2007 - `annotations: List[Annotation]`
2008
2009 Ordered list of annotations attached to the response text.
2010
2011 - `class AnnotationFile: …`
2012
2013 Annotation that references an uploaded file.
2014
2015 - `source: AnnotationFileSource`
2016
2017 File attachment referenced by the annotation.
2018
2019 - `filename: str`
2020
2021 Filename referenced by the annotation.
2022
2023 - `type: Literal["file"]`
2024
2025 Type discriminator that is always `file`.
2026
2027 - `"file"`
2028
2029 - `type: Literal["file"]`
2030
2031 Type discriminator that is always `file` for this annotation.
2032
2033 - `"file"`
2034
2035 - `class AnnotationURL: …`
2036
2037 Annotation that references a URL.
2038
2039 - `source: AnnotationURLSource`
2040
2041 URL referenced by the annotation.
2042
2043 - `type: Literal["url"]`
2044
2045 Type discriminator that is always `url`.
2046
2047 - `"url"`
2048
2049 - `url: str`
2050
2051 URL referenced by the annotation.
2052
2053 - `type: Literal["url"]`
2054
2055 Type discriminator that is always `url` for this annotation.
2056
2057 - `"url"`
2058
2059 - `text: str`
2060
2061 Assistant generated text.
2062
2063 - `type: Literal["output_text"]`
2064
2065 Type discriminator that is always `output_text`.
2066
2067 - `"output_text"`
2068
2069 - `created_at: int`
2070
2071 Unix timestamp (in seconds) for when the item was created.
2072
2073 - `object: Literal["chatkit.thread_item"]`
2074
2075 Type discriminator that is always `chatkit.thread_item`.
2076
2077 - `"chatkit.thread_item"`
2078
2079 - `thread_id: str`
2080
2081 Identifier of the parent thread.
2082
2083 - `type: Literal["chatkit.assistant_message"]`
2084
2085 Type discriminator that is always `chatkit.assistant_message`.
2086
2087 - `"chatkit.assistant_message"`
2088
2089### ChatKit Thread Item List
2090
2091- `class ChatKitThreadItemList: …`
2092
2093 A paginated list of thread items rendered for the ChatKit API.
2094
2095 - `data: List[Data]`
2096
2097 A list of items
2098
2099 - `class ChatKitThreadUserMessageItem: …`
2100
2101 User-authored messages within a thread.
2102
2103 - `id: str`
2104
2105 Identifier of the thread item.
2106
2107 - `attachments: List[ChatKitAttachment]`
2108
2109 Attachments associated with the user message. Defaults to an empty list.
2110
2111 - `id: str`
2112
2113 Identifier for the attachment.
2114
2115 - `mime_type: str`
2116
2117 MIME type of the attachment.
2118
2119 - `name: str`
2120
2121 Original display name for the attachment.
2122
2123 - `preview_url: Optional[str]`
2124
2125 Preview URL for rendering the attachment inline.
2126
2127 - `type: Literal["image", "file"]`
2128
2129 Attachment discriminator.
2130
2131 - `"image"`
2132
2133 - `"file"`
2134
2135 - `content: List[Content]`
2136
2137 Ordered content elements supplied by the user.
2138
2139 - `class ContentInputText: …`
2140
2141 Text block that a user contributed to the thread.
2142
2143 - `text: str`
2144
2145 Plain-text content supplied by the user.
2146
2147 - `type: Literal["input_text"]`
2148
2149 Type discriminator that is always `input_text`.
2150
2151 - `"input_text"`
2152
2153 - `class ContentQuotedText: …`
2154
2155 Quoted snippet that the user referenced in their message.
2156
2157 - `text: str`
2158
2159 Quoted text content.
2160
2161 - `type: Literal["quoted_text"]`
2162
2163 Type discriminator that is always `quoted_text`.
2164
2165 - `"quoted_text"`
2166
2167 - `created_at: int`
2168
2169 Unix timestamp (in seconds) for when the item was created.
2170
2171 - `inference_options: Optional[InferenceOptions]`
2172
2173 Inference overrides applied to the message. Defaults to null when unset.
2174
2175 - `model: Optional[str]`
2176
2177 Model name that generated the response. Defaults to null when using the session default.
2178
2179 - `tool_choice: Optional[InferenceOptionsToolChoice]`
2180
2181 Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
2182
2183 - `id: str`
2184
2185 Identifier of the requested tool.
2186
2187 - `object: Literal["chatkit.thread_item"]`
2188
2189 Type discriminator that is always `chatkit.thread_item`.
2190
2191 - `"chatkit.thread_item"`
2192
2193 - `thread_id: str`
2194
2195 Identifier of the parent thread.
2196
2197 - `type: Literal["chatkit.user_message"]`
2198
2199 - `"chatkit.user_message"`
2200
2201 - `class ChatKitThreadAssistantMessageItem: …`
2202
2203 Assistant-authored message within a thread.
2204
2205 - `id: str`
2206
2207 Identifier of the thread item.
2208
2209 - `content: List[ChatKitResponseOutputText]`
2210
2211 Ordered assistant response segments.
2212
2213 - `annotations: List[Annotation]`
2214
2215 Ordered list of annotations attached to the response text.
2216
2217 - `class AnnotationFile: …`
2218
2219 Annotation that references an uploaded file.
2220
2221 - `source: AnnotationFileSource`
2222
2223 File attachment referenced by the annotation.
2224
2225 - `filename: str`
2226
2227 Filename referenced by the annotation.
2228
2229 - `type: Literal["file"]`
2230
2231 Type discriminator that is always `file`.
2232
2233 - `"file"`
2234
2235 - `type: Literal["file"]`
2236
2237 Type discriminator that is always `file` for this annotation.
2238
2239 - `"file"`
2240
2241 - `class AnnotationURL: …`
2242
2243 Annotation that references a URL.
2244
2245 - `source: AnnotationURLSource`
2246
2247 URL referenced by the annotation.
2248
2249 - `type: Literal["url"]`
2250
2251 Type discriminator that is always `url`.
2252
2253 - `"url"`
2254
2255 - `url: str`
2256
2257 URL referenced by the annotation.
2258
2259 - `type: Literal["url"]`
2260
2261 Type discriminator that is always `url` for this annotation.
2262
2263 - `"url"`
2264
2265 - `text: str`
2266
2267 Assistant generated text.
2268
2269 - `type: Literal["output_text"]`
2270
2271 Type discriminator that is always `output_text`.
2272
2273 - `"output_text"`
2274
2275 - `created_at: int`
2276
2277 Unix timestamp (in seconds) for when the item was created.
2278
2279 - `object: Literal["chatkit.thread_item"]`
2280
2281 Type discriminator that is always `chatkit.thread_item`.
2282
2283 - `"chatkit.thread_item"`
2284
2285 - `thread_id: str`
2286
2287 Identifier of the parent thread.
2288
2289 - `type: Literal["chatkit.assistant_message"]`
2290
2291 Type discriminator that is always `chatkit.assistant_message`.
2292
2293 - `"chatkit.assistant_message"`
2294
2295 - `class ChatKitWidgetItem: …`
2296
2297 Thread item that renders a widget payload.
2298
2299 - `id: str`
2300
2301 Identifier of the thread item.
2302
2303 - `created_at: int`
2304
2305 Unix timestamp (in seconds) for when the item was created.
2306
2307 - `object: Literal["chatkit.thread_item"]`
2308
2309 Type discriminator that is always `chatkit.thread_item`.
2310
2311 - `"chatkit.thread_item"`
2312
2313 - `thread_id: str`
2314
2315 Identifier of the parent thread.
2316
2317 - `type: Literal["chatkit.widget"]`
2318
2319 Type discriminator that is always `chatkit.widget`.
2320
2321 - `"chatkit.widget"`
2322
2323 - `widget: str`
2324
2325 Serialized widget payload rendered in the UI.
2326
2327 - `class DataChatKitClientToolCall: …`
2328
2329 Record of a client side tool invocation initiated by the assistant.
2330
2331 - `id: str`
2332
2333 Identifier of the thread item.
2334
2335 - `arguments: str`
2336
2337 JSON-encoded arguments that were sent to the tool.
2338
2339 - `call_id: str`
2340
2341 Identifier for the client tool call.
2342
2343 - `created_at: int`
2344
2345 Unix timestamp (in seconds) for when the item was created.
2346
2347 - `name: str`
2348
2349 Tool name that was invoked.
2350
2351 - `object: Literal["chatkit.thread_item"]`
2352
2353 Type discriminator that is always `chatkit.thread_item`.
2354
2355 - `"chatkit.thread_item"`
2356
2357 - `output: Optional[str]`
2358
2359 JSON-encoded output captured from the tool. Defaults to null while execution is in progress.
2360
2361 - `status: Literal["in_progress", "completed"]`
2362
2363 Execution status for the tool call.
2364
2365 - `"in_progress"`
2366
2367 - `"completed"`
2368
2369 - `thread_id: str`
2370
2371 Identifier of the parent thread.
2372
2373 - `type: Literal["chatkit.client_tool_call"]`
2374
2375 Type discriminator that is always `chatkit.client_tool_call`.
2376
2377 - `"chatkit.client_tool_call"`
2378
2379 - `class DataChatKitTask: …`
2380
2381 Task emitted by the workflow to show progress and status updates.
2382
2383 - `id: str`
2384
2385 Identifier of the thread item.
2386
2387 - `created_at: int`
2388
2389 Unix timestamp (in seconds) for when the item was created.
2390
2391 - `heading: Optional[str]`
2392
2393 Optional heading for the task. Defaults to null when not provided.
2394
2395 - `object: Literal["chatkit.thread_item"]`
2396
2397 Type discriminator that is always `chatkit.thread_item`.
2398
2399 - `"chatkit.thread_item"`
2400
2401 - `summary: Optional[str]`
2402
2403 Optional summary that describes the task. Defaults to null when omitted.
2404
2405 - `task_type: Literal["custom", "thought"]`
2406
2407 Subtype for the task.
2408
2409 - `"custom"`
2410
2411 - `"thought"`
2412
2413 - `thread_id: str`
2414
2415 Identifier of the parent thread.
2416
2417 - `type: Literal["chatkit.task"]`
2418
2419 Type discriminator that is always `chatkit.task`.
2420
2421 - `"chatkit.task"`
2422
2423 - `class DataChatKitTaskGroup: …`
2424
2425 Collection of workflow tasks grouped together in the thread.
2426
2427 - `id: str`
2428
2429 Identifier of the thread item.
2430
2431 - `created_at: int`
2432
2433 Unix timestamp (in seconds) for when the item was created.
2434
2435 - `object: Literal["chatkit.thread_item"]`
2436
2437 Type discriminator that is always `chatkit.thread_item`.
2438
2439 - `"chatkit.thread_item"`
2440
2441 - `tasks: List[DataChatKitTaskGroupTask]`
2442
2443 Tasks included in the group.
2444
2445 - `heading: Optional[str]`
2446
2447 Optional heading for the grouped task. Defaults to null when not provided.
2448
2449 - `summary: Optional[str]`
2450
2451 Optional summary that describes the grouped task. Defaults to null when omitted.
2452
2453 - `type: Literal["custom", "thought"]`
2454
2455 Subtype for the grouped task.
2456
2457 - `"custom"`
2458
2459 - `"thought"`
2460
2461 - `thread_id: str`
2462
2463 Identifier of the parent thread.
2464
2465 - `type: Literal["chatkit.task_group"]`
2466
2467 Type discriminator that is always `chatkit.task_group`.
2468
2469 - `"chatkit.task_group"`
2470
2471 - `first_id: Optional[str]`
2472
2473 The ID of the first item in the list.
2474
2475 - `has_more: bool`
2476
2477 Whether there are more items available.
2478
2479 - `last_id: Optional[str]`
2480
2481 The ID of the last item in the list.
2482
2483 - `object: Literal["list"]`
2484
2485 The type of object returned, must be `list`.
2486
2487 - `"list"`
2488
2489### ChatKit Thread User Message Item
2490
2491- `class ChatKitThreadUserMessageItem: …`
2492
2493 User-authored messages within a thread.
2494
2495 - `id: str`
2496
2497 Identifier of the thread item.
2498
2499 - `attachments: List[ChatKitAttachment]`
2500
2501 Attachments associated with the user message. Defaults to an empty list.
2502
2503 - `id: str`
2504
2505 Identifier for the attachment.
2506
2507 - `mime_type: str`
2508
2509 MIME type of the attachment.
2510
2511 - `name: str`
2512
2513 Original display name for the attachment.
2514
2515 - `preview_url: Optional[str]`
2516
2517 Preview URL for rendering the attachment inline.
2518
2519 - `type: Literal["image", "file"]`
2520
2521 Attachment discriminator.
2522
2523 - `"image"`
2524
2525 - `"file"`
2526
2527 - `content: List[Content]`
2528
2529 Ordered content elements supplied by the user.
2530
2531 - `class ContentInputText: …`
2532
2533 Text block that a user contributed to the thread.
2534
2535 - `text: str`
2536
2537 Plain-text content supplied by the user.
2538
2539 - `type: Literal["input_text"]`
2540
2541 Type discriminator that is always `input_text`.
2542
2543 - `"input_text"`
2544
2545 - `class ContentQuotedText: …`
2546
2547 Quoted snippet that the user referenced in their message.
2548
2549 - `text: str`
2550
2551 Quoted text content.
2552
2553 - `type: Literal["quoted_text"]`
2554
2555 Type discriminator that is always `quoted_text`.
2556
2557 - `"quoted_text"`
2558
2559 - `created_at: int`
2560
2561 Unix timestamp (in seconds) for when the item was created.
2562
2563 - `inference_options: Optional[InferenceOptions]`
2564
2565 Inference overrides applied to the message. Defaults to null when unset.
2566
2567 - `model: Optional[str]`
2568
2569 Model name that generated the response. Defaults to null when using the session default.
2570
2571 - `tool_choice: Optional[InferenceOptionsToolChoice]`
2572
2573 Preferred tool to invoke. Defaults to null when ChatKit should auto-select.
2574
2575 - `id: str`
2576
2577 Identifier of the requested tool.
2578
2579 - `object: Literal["chatkit.thread_item"]`
2580
2581 Type discriminator that is always `chatkit.thread_item`.
2582
2583 - `"chatkit.thread_item"`
2584
2585 - `thread_id: str`
2586
2587 Identifier of the parent thread.
2588
2589 - `type: Literal["chatkit.user_message"]`
2590
2591 - `"chatkit.user_message"`
2592
2593### ChatKit Widget Item
2594
2595- `class ChatKitWidgetItem: …`
2596
2597 Thread item that renders a widget payload.
2598
2599 - `id: str`
2600
2601 Identifier of the thread item.
2602
2603 - `created_at: int`
2604
2605 Unix timestamp (in seconds) for when the item was created.
2606
2607 - `object: Literal["chatkit.thread_item"]`
2608
2609 Type discriminator that is always `chatkit.thread_item`.
2610
2611 - `"chatkit.thread_item"`
2612
2613 - `thread_id: str`
2614
2615 Identifier of the parent thread.
2616
2617 - `type: Literal["chatkit.widget"]`
2618
2619 Type discriminator that is always `chatkit.widget`.
2620
2621 - `"chatkit.widget"`
2622
2623 - `widget: str`
2624
2625 Serialized widget payload rendered in the UI.
2626
2627### Thread Delete Response
2628
2629- `class ThreadDeleteResponse: …`
2630
2631 Confirmation payload returned after deleting a thread.
2632
2633 - `id: str`
2634
2635 Identifier of the deleted thread.
2636
2637 - `deleted: bool`
2638
2639 Indicates that the thread has been deleted.
2640
2641 - `object: Literal["chatkit.thread.deleted"]`
2642
2643 Type discriminator that is always `chatkit.thread.deleted`.
2644
2645 - `"chatkit.thread.deleted"`