ruby/resources/beta/subresources/chatkit/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

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: String`

12 

13 Identifier of the workflow backing the session.

14 

15 - `state_variables: Hash[Symbol, String | bool | Float]`

16 

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

18 

19 - `String = String`

20 

21 - `UnionMember1 = bool`

22 

23 - `Float = Float`

24 

25 - `tracing: Tracing{ enabled}`

26 

27 Tracing settings applied to the workflow.

28 

29 - `enabled: bool`

30 

31 Indicates whether tracing is enabled.

32 

33 - `version: String`

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(session_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: String`

52 

53### Returns

54 

55- `class ChatSession`

56 

57 Represents a ChatKit session and its resolved configuration.

58 

59 - `id: String`

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: Integer`

84 

85 Maximum upload size in megabytes.

86 

87 - `max_files: Integer`

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: Integer`

100 

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

102 

103 - `client_secret: String`

104 

105 Ephemeral client secret that authenticates session requests.

106 

107 - `expires_at: Integer`

108 

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

110 

111 - `max_requests_per_1_minute: Integer`

112 

113 Convenience copy of the per-minute request limit.

114 

115 - `object: :"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: Integer`

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: String`

140 

141 User identifier associated with the session.

142 

143 - `workflow: ChatKitWorkflow`

144 

145 Workflow metadata for the session.

146 

147 - `id: String`

148 

149 Identifier of the workflow backing the session.

150 

151 - `state_variables: Hash[Symbol, String | bool | Float]`

152 

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

154 

155 - `String = String`

156 

157 - `UnionMember1 = bool`

158 

159 - `Float = Float`

160 

161 - `tracing: Tracing{ enabled}`

162 

163 Tracing settings applied to the workflow.

164 

165 - `enabled: bool`

166 

167 Indicates whether tracing is enabled.

168 

169 - `version: String`

170 

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

172 

173### Example

174 

175```ruby

176require "openai"

177 

178openai = OpenAI::Client.new(api_key: "My API Key")

179 

180chat_session = openai.beta.chatkit.sessions.cancel("cksess_123")

181 

182puts(chat_session)

183```

184 

185#### Response

186 

187```json

188{

189 "id": "id",

190 "chatkit_configuration": {

191 "automatic_thread_titling": {

192 "enabled": true

193 },

194 "file_upload": {

195 "enabled": true,

196 "max_file_size": 0,

197 "max_files": 0

198 },

199 "history": {

200 "enabled": true,

201 "recent_threads": 0

202 }

203 },

204 "client_secret": "client_secret",

205 "expires_at": 0,

206 "max_requests_per_1_minute": 0,

207 "object": "chatkit.session",

208 "rate_limits": {

209 "max_requests_per_1_minute": 0

210 },

211 "status": "active",

212 "user": "user",

213 "workflow": {

214 "id": "id",

215 "state_variables": {

216 "foo": "string"

217 },

218 "tracing": {

219 "enabled": true

220 },

221 "version": "version"

222 }

223}

224```

225 

226### Example

227 

228```ruby

229require "openai"

230 

231openai = OpenAI::Client.new

232 

233chat_session = openai.beta.chatkit.sessions.cancel("cksess_123")

234 

235puts(chat_session)

236```

237 

238#### Response

239 

240```json

241{

242 "id": "cksess_123",

243 "object": "chatkit.session",

244 "workflow": {

245 "id": "workflow_alpha",

246 "version": "1"

247 },

248 "scope": {

249 "customer_id": "cust_456"

250 },

251 "max_requests_per_1_minute": 30,

252 "ttl_seconds": 900,

253 "status": "cancelled",

254 "cancelled_at": 1712345678

255}

256```

257 

258## Create ChatKit session

259 

260`beta.chatkit.sessions.create(**kwargs) -> ChatSession`

261 

262**post** `/chatkit/sessions`

263 

264Create a ChatKit session.

265 

266### Parameters

267 

268- `user: String`

269 

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

271 

272- `workflow: ChatSessionWorkflowParam`

273 

274 Workflow that powers the session.

275 

276 - `id: String`

277 

278 Identifier for the workflow invoked by the session.

279 

280 - `state_variables: Hash[Symbol, String | bool | Float]`

281 

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

283 

284 - `String = String`

285 

286 - `UnionMember1 = bool`

287 

288 - `Float = Float`

289 

290 - `tracing: Tracing{ enabled}`

291 

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

293 

294 - `enabled: bool`

295 

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

297 

298 - `version: String`

299 

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

301 

302- `chatkit_configuration: ChatSessionChatKitConfigurationParam`

303 

304 Optional overrides for ChatKit runtime configuration features

305 

306 - `automatic_thread_titling: AutomaticThreadTitling{ enabled}`

307 

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

309 

310 - `enabled: bool`

311 

312 Enable automatic thread title generation. Defaults to true.

313 

314 - `file_upload: FileUpload{ enabled, max_file_size, max_files}`

315 

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

317 

318 - `enabled: bool`

319 

320 Enable uploads for this session. Defaults to false.

321 

322 - `max_file_size: Integer`

323 

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

325 

326 - `max_files: Integer`

327 

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

329 

330 - `history: History{ enabled, recent_threads}`

331 

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

333 

334 - `enabled: bool`

335 

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

337 

338 - `recent_threads: Integer`

339 

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

341 

342- `expires_after: ChatSessionExpiresAfterParam`

343 

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

345 

346 - `anchor: :created_at`

347 

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

349 

350 - `:created_at`

351 

352 - `seconds: Integer`

353 

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

355 

356- `rate_limits: ChatSessionRateLimitsParam`

357 

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

359 

360 - `max_requests_per_1_minute: Integer`

361 

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

363 

364### Returns

365 

366- `class ChatSession`

367 

368 Represents a ChatKit session and its resolved configuration.

369 

370 - `id: String`

371 

372 Identifier for the ChatKit session.

373 

374 - `chatkit_configuration: ChatSessionChatKitConfiguration`

375 

376 Resolved ChatKit feature configuration for the session.

377 

378 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`

379 

380 Automatic thread titling preferences.

381 

382 - `enabled: bool`

383 

384 Whether automatic thread titling is enabled.

385 

386 - `file_upload: ChatSessionFileUpload`

387 

388 Upload settings for the session.

389 

390 - `enabled: bool`

391 

392 Indicates if uploads are enabled for the session.

393 

394 - `max_file_size: Integer`

395 

396 Maximum upload size in megabytes.

397 

398 - `max_files: Integer`

399 

400 Maximum number of uploads allowed during the session.

401 

402 - `history: ChatSessionHistory`

403 

404 History retention configuration.

405 

406 - `enabled: bool`

407 

408 Indicates if chat history is persisted for the session.

409 

410 - `recent_threads: Integer`

411 

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

413 

414 - `client_secret: String`

415 

416 Ephemeral client secret that authenticates session requests.

417 

418 - `expires_at: Integer`

419 

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

421 

422 - `max_requests_per_1_minute: Integer`

423 

424 Convenience copy of the per-minute request limit.

425 

426 - `object: :"chatkit.session"`

427 

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

429 

430 - `:"chatkit.session"`

431 

432 - `rate_limits: ChatSessionRateLimits`

433 

434 Resolved rate limit values.

435 

436 - `max_requests_per_1_minute: Integer`

437 

438 Maximum allowed requests per one-minute window.

439 

440 - `status: ChatSessionStatus`

441 

442 Current lifecycle state of the session.

443 

444 - `:active`

445 

446 - `:expired`

447 

448 - `:cancelled`

449 

450 - `user: String`

451 

452 User identifier associated with the session.

453 

454 - `workflow: ChatKitWorkflow`

455 

456 Workflow metadata for the session.

457 

458 - `id: String`

459 

460 Identifier of the workflow backing the session.

461 

462 - `state_variables: Hash[Symbol, String | bool | Float]`

463 

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

465 

466 - `String = String`

467 

468 - `UnionMember1 = bool`

469 

470 - `Float = Float`

471 

472 - `tracing: Tracing{ enabled}`

473 

474 Tracing settings applied to the workflow.

475 

476 - `enabled: bool`

477 

478 Indicates whether tracing is enabled.

479 

480 - `version: String`

481 

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

483 

484### Example

485 

486```ruby

487require "openai"

488 

489openai = OpenAI::Client.new(api_key: "My API Key")

490 

491chat_session = openai.beta.chatkit.sessions.create(user: "x", workflow: {id: "id"})

492 

493puts(chat_session)

494```

495 

496#### Response

497 

498```json

499{

500 "id": "id",

501 "chatkit_configuration": {

502 "automatic_thread_titling": {

503 "enabled": true

504 },

505 "file_upload": {

506 "enabled": true,

507 "max_file_size": 0,

508 "max_files": 0

509 },

510 "history": {

511 "enabled": true,

512 "recent_threads": 0

513 }

514 },

515 "client_secret": "client_secret",

516 "expires_at": 0,

517 "max_requests_per_1_minute": 0,

518 "object": "chatkit.session",

519 "rate_limits": {

520 "max_requests_per_1_minute": 0

521 },

522 "status": "active",

523 "user": "user",

524 "workflow": {

525 "id": "id",

526 "state_variables": {

527 "foo": "string"

528 },

529 "tracing": {

530 "enabled": true

531 },

532 "version": "version"

533 }

534}

535```

536 

537### Example

538 

539```ruby

540require "openai"

541 

542openai = OpenAI::Client.new

543 

544chat_session = openai.beta.chatkit.sessions.create(user: "user", workflow: {id: "id"})

545 

546puts(chat_session)

547```

548 

549#### Response

550 

551```json

552{

553 "client_secret": "chatkit_token_123",

554 "expires_at": 1735689600,

555 "workflow": {

556 "id": "workflow_alpha",

557 "version": "2024-10-01"

558 },

559 "scope": {

560 "project": "alpha",

561 "environment": "staging"

562 },

563 "max_requests_per_1_minute": 60,

564 "max_requests_per_session": 500,

565 "status": "active"

566}

567```

568 

569# Threads

570 

571## List ChatKit thread items

572 

573`beta.chatkit.threads.list_items(thread_id, **kwargs) -> ConversationCursorPage<ChatKitThreadUserMessageItem | ChatKitThreadAssistantMessageItem | ChatKitWidgetItem | 3 more>`

574 

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

576 

577List items that belong to a ChatKit thread.

578 

579### Parameters

580 

581- `thread_id: String`

582 

583- `after: String`

584 

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

586 

587- `before: String`

588 

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

590 

591- `limit: Integer`

592 

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

594 

595- `order: :asc | :desc`

596 

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

598 

599 - `:asc`

600 

601 - `:desc`

602 

603### Returns

604 

605- `ChatKitThreadUserMessageItem | ChatKitThreadAssistantMessageItem | ChatKitWidgetItem | 3 more`

606 

607 - `class ChatKitThreadUserMessageItem`

608 

609 User-authored messages within a thread.

610 

611 - `id: String`

612 

613 Identifier of the thread item.

614 

615 - `attachments: Array[ChatKitAttachment]`

616 

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

618 

619 - `id: String`

620 

621 Identifier for the attachment.

622 

623 - `mime_type: String`

624 

625 MIME type of the attachment.

626 

627 - `name: String`

628 

629 Original display name for the attachment.

630 

631 - `preview_url: String`

632 

633 Preview URL for rendering the attachment inline.

634 

635 - `type: :image | :file`

636 

637 Attachment discriminator.

638 

639 - `:image`

640 

641 - `:file`

642 

643 - `content: Array[InputText{ text, type} | QuotedText{ text, type}]`

644 

645 Ordered content elements supplied by the user.

646 

647 - `class InputText`

648 

649 Text block that a user contributed to the thread.

650 

651 - `text: String`

652 

653 Plain-text content supplied by the user.

654 

655 - `type: :input_text`

656 

657 Type discriminator that is always `input_text`.

658 

659 - `:input_text`

660 

661 - `class QuotedText`

662 

663 Quoted snippet that the user referenced in their message.

664 

665 - `text: String`

666 

667 Quoted text content.

668 

669 - `type: :quoted_text`

670 

671 Type discriminator that is always `quoted_text`.

672 

673 - `:quoted_text`

674 

675 - `created_at: Integer`

676 

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

678 

679 - `inference_options: InferenceOptions{ model, tool_choice}`

680 

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

682 

683 - `model: String`

684 

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

686 

687 - `tool_choice: ToolChoice{ id}`

688 

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

690 

691 - `id: String`

692 

693 Identifier of the requested tool.

694 

695 - `object: :"chatkit.thread_item"`

696 

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

698 

699 - `:"chatkit.thread_item"`

700 

701 - `thread_id: String`

702 

703 Identifier of the parent thread.

704 

705 - `type: :"chatkit.user_message"`

706 

707 - `:"chatkit.user_message"`

708 

709 - `class ChatKitThreadAssistantMessageItem`

710 

711 Assistant-authored message within a thread.

712 

713 - `id: String`

714 

715 Identifier of the thread item.

716 

717 - `content: Array[ChatKitResponseOutputText]`

718 

719 Ordered assistant response segments.

720 

721 - `annotations: Array[File{ source, type} | URL{ source, type}]`

722 

723 Ordered list of annotations attached to the response text.

724 

725 - `class File`

726 

727 Annotation that references an uploaded file.

728 

729 - `source: Source{ filename, type}`

730 

731 File attachment referenced by the annotation.

732 

733 - `filename: String`

734 

735 Filename referenced by the annotation.

736 

737 - `type: :file`

738 

739 Type discriminator that is always `file`.

740 

741 - `:file`

742 

743 - `type: :file`

744 

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

746 

747 - `:file`

748 

749 - `class URL`

750 

751 Annotation that references a URL.

752 

753 - `source: Source{ type, url}`

754 

755 URL referenced by the annotation.

756 

757 - `type: :url`

758 

759 Type discriminator that is always `url`.

760 

761 - `:url`

762 

763 - `url: String`

764 

765 URL referenced by the annotation.

766 

767 - `type: :url`

768 

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

770 

771 - `:url`

772 

773 - `text: String`

774 

775 Assistant generated text.

776 

777 - `type: :output_text`

778 

779 Type discriminator that is always `output_text`.

780 

781 - `:output_text`

782 

783 - `created_at: Integer`

784 

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

786 

787 - `object: :"chatkit.thread_item"`

788 

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

790 

791 - `:"chatkit.thread_item"`

792 

793 - `thread_id: String`

794 

795 Identifier of the parent thread.

796 

797 - `type: :"chatkit.assistant_message"`

798 

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

800 

801 - `:"chatkit.assistant_message"`

802 

803 - `class ChatKitWidgetItem`

804 

805 Thread item that renders a widget payload.

806 

807 - `id: String`

808 

809 Identifier of the thread item.

810 

811 - `created_at: Integer`

812 

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

814 

815 - `object: :"chatkit.thread_item"`

816 

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

818 

819 - `:"chatkit.thread_item"`

820 

821 - `thread_id: String`

822 

823 Identifier of the parent thread.

824 

825 - `type: :"chatkit.widget"`

826 

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

828 

829 - `:"chatkit.widget"`

830 

831 - `widget: String`

832 

833 Serialized widget payload rendered in the UI.

834 

835 - `class ChatKitClientToolCall`

836 

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

838 

839 - `id: String`

840 

841 Identifier of the thread item.

842 

843 - `arguments: String`

844 

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

846 

847 - `call_id: String`

848 

849 Identifier for the client tool call.

850 

851 - `created_at: Integer`

852 

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

854 

855 - `name: String`

856 

857 Tool name that was invoked.

858 

859 - `object: :"chatkit.thread_item"`

860 

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

862 

863 - `:"chatkit.thread_item"`

864 

865 - `output: String`

866 

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

868 

869 - `status: :in_progress | :completed`

870 

871 Execution status for the tool call.

872 

873 - `:in_progress`

874 

875 - `:completed`

876 

877 - `thread_id: String`

878 

879 Identifier of the parent thread.

880 

881 - `type: :"chatkit.client_tool_call"`

882 

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

884 

885 - `:"chatkit.client_tool_call"`

886 

887 - `class ChatKitTask`

888 

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

890 

891 - `id: String`

892 

893 Identifier of the thread item.

894 

895 - `created_at: Integer`

896 

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

898 

899 - `heading: String`

900 

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

902 

903 - `object: :"chatkit.thread_item"`

904 

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

906 

907 - `:"chatkit.thread_item"`

908 

909 - `summary: String`

910 

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

912 

913 - `task_type: :custom | :thought`

914 

915 Subtype for the task.

916 

917 - `:custom`

918 

919 - `:thought`

920 

921 - `thread_id: String`

922 

923 Identifier of the parent thread.

924 

925 - `type: :"chatkit.task"`

926 

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

928 

929 - `:"chatkit.task"`

930 

931 - `class ChatKitTaskGroup`

932 

933 Collection of workflow tasks grouped together in the thread.

934 

935 - `id: String`

936 

937 Identifier of the thread item.

938 

939 - `created_at: Integer`

940 

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

942 

943 - `object: :"chatkit.thread_item"`

944 

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

946 

947 - `:"chatkit.thread_item"`

948 

949 - `tasks: Array[Task{ heading, summary, type}]`

950 

951 Tasks included in the group.

952 

953 - `heading: String`

954 

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

956 

957 - `summary: String`

958 

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

960 

961 - `type: :custom | :thought`

962 

963 Subtype for the grouped task.

964 

965 - `:custom`

966 

967 - `:thought`

968 

969 - `thread_id: String`

970 

971 Identifier of the parent thread.

972 

973 - `type: :"chatkit.task_group"`

974 

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

976 

977 - `:"chatkit.task_group"`

978 

979### Example

980 

981```ruby

982require "openai"

983 

984openai = OpenAI::Client.new(api_key: "My API Key")

985 

986page = openai.beta.chatkit.threads.list_items("cthr_123")

987 

988puts(page)

989```

990 

991#### Response

992 

993```json

994{

995 "data": [

996 {

997 "id": "id",

998 "attachments": [

999 {

1000 "id": "id",

1001 "mime_type": "mime_type",

1002 "name": "name",

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

1004 "type": "image"

1005 }

1006 ],

1007 "content": [

1008 {

1009 "text": "text",

1010 "type": "input_text"

1011 }

1012 ],

1013 "created_at": 0,

1014 "inference_options": {

1015 "model": "model",

1016 "tool_choice": {

1017 "id": "id"

1018 }

1019 },

1020 "object": "chatkit.thread_item",

1021 "thread_id": "thread_id",

1022 "type": "chatkit.user_message"

1023 }

1024 ],

1025 "first_id": "first_id",

1026 "has_more": true,

1027 "last_id": "last_id",

1028 "object": "list"

1029}

1030```

1031 

1032### Example

1033 

1034```ruby

1035require "openai"

1036 

1037openai = OpenAI::Client.new

1038 

1039page = openai.beta.chatkit.threads.list_items("cthr_123")

1040 

1041puts(page)

1042```

1043 

1044#### Response

1045 

1046```json

1047{

1048 "data": [

1049 {

1050 "id": "cthi_user_001",

1051 "object": "chatkit.thread_item",

1052 "type": "user_message",

1053 "content": [

1054 {

1055 "type": "input_text",

1056 "text": "I need help debugging an onboarding issue."

1057 }

1058 ],

1059 "attachments": []

1060 },

1061 {

1062 "id": "cthi_assistant_002",

1063 "object": "chatkit.thread_item",

1064 "type": "assistant_message",

1065 "content": [

1066 {

1067 "type": "output_text",

1068 "text": "Let's start by confirming the workflow version you deployed."

1069 }

1070 ]

1071 }

1072 ],

1073 "has_more": false,

1074 "object": "list"

1075}

1076```

1077 

1078## Retrieve ChatKit thread

1079 

1080`beta.chatkit.threads.retrieve(thread_id) -> ChatKitThread`

1081 

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

1083 

1084Retrieve a ChatKit thread by its identifier.

1085 

1086### Parameters

1087 

1088- `thread_id: String`

1089 

1090### Returns

1091 

1092- `class ChatKitThread`

1093 

1094 Represents a ChatKit thread and its current status.

1095 

1096 - `id: String`

1097 

1098 Identifier of the thread.

1099 

1100 - `created_at: Integer`

1101 

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

1103 

1104 - `object: :"chatkit.thread"`

1105 

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

1107 

1108 - `:"chatkit.thread"`

1109 

1110 - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}`

1111 

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

1113 

1114 - `class Active`

1115 

1116 Indicates that a thread is active.

1117 

1118 - `type: :active`

1119 

1120 Status discriminator that is always `active`.

1121 

1122 - `:active`

1123 

1124 - `class Locked`

1125 

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

1127 

1128 - `reason: String`

1129 

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

1131 

1132 - `type: :locked`

1133 

1134 Status discriminator that is always `locked`.

1135 

1136 - `:locked`

1137 

1138 - `class Closed`

1139 

1140 Indicates that a thread has been closed.

1141 

1142 - `reason: String`

1143 

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

1145 

1146 - `type: :closed`

1147 

1148 Status discriminator that is always `closed`.

1149 

1150 - `:closed`

1151 

1152 - `title: String`

1153 

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

1155 

1156 - `user: String`

1157 

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

1159 

1160### Example

1161 

1162```ruby

1163require "openai"

1164 

1165openai = OpenAI::Client.new(api_key: "My API Key")

1166 

1167chatkit_thread = openai.beta.chatkit.threads.retrieve("cthr_123")

1168 

1169puts(chatkit_thread)

1170```

1171 

1172#### Response

1173 

1174```json

1175{

1176 "id": "cthr_def456",

1177 "created_at": 1712345600,

1178 "object": "chatkit.thread",

1179 "status": {

1180 "type": "active"

1181 },

1182 "title": "Demo feedback",

1183 "user": "user_456"

1184}

1185```

1186 

1187### Example

1188 

1189```ruby

1190require "openai"

1191 

1192openai = OpenAI::Client.new

1193 

1194chatkit_thread = openai.beta.chatkit.threads.retrieve("cthr_123")

1195 

1196puts(chatkit_thread)

1197```

1198 

1199#### Response

1200 

1201```json

1202{

1203 "id": "cthr_abc123",

1204 "object": "chatkit.thread",

1205 "title": "Customer escalation",

1206 "items": {

1207 "data": [

1208 {

1209 "id": "cthi_user_001",

1210 "object": "chatkit.thread_item",

1211 "type": "user_message",

1212 "content": [

1213 {

1214 "type": "input_text",

1215 "text": "I need help debugging an onboarding issue."

1216 }

1217 ],

1218 "attachments": []

1219 },

1220 {

1221 "id": "cthi_assistant_002",

1222 "object": "chatkit.thread_item",

1223 "type": "assistant_message",

1224 "content": [

1225 {

1226 "type": "output_text",

1227 "text": "Let's start by confirming the workflow version you deployed."

1228 }

1229 ]

1230 }

1231 ],

1232 "has_more": false

1233 }

1234}

1235```

1236 

1237## Delete ChatKit thread

1238 

1239`beta.chatkit.threads.delete(thread_id) -> ThreadDeleteResponse`

1240 

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

1242 

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

1244 

1245### Parameters

1246 

1247- `thread_id: String`

1248 

1249### Returns

1250 

1251- `class ThreadDeleteResponse`

1252 

1253 Confirmation payload returned after deleting a thread.

1254 

1255 - `id: String`

1256 

1257 Identifier of the deleted thread.

1258 

1259 - `deleted: bool`

1260 

1261 Indicates that the thread has been deleted.

1262 

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

1264 

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

1266 

1267 - `:"chatkit.thread.deleted"`

1268 

1269### Example

1270 

1271```ruby

1272require "openai"

1273 

1274openai = OpenAI::Client.new(api_key: "My API Key")

1275 

1276thread = openai.beta.chatkit.threads.delete("cthr_123")

1277 

1278puts(thread)

1279```

1280 

1281#### Response

1282 

1283```json

1284{

1285 "id": "id",

1286 "deleted": true,

1287 "object": "chatkit.thread.deleted"

1288}

1289```

1290 

1291### Example

1292 

1293```ruby

1294require "openai"

1295 

1296openai = OpenAI::Client.new

1297 

1298thread = openai.beta.chat_kit.threads.delete("cthr_123")

1299 

1300puts(thread)

1301```

1302 

1303## List ChatKit threads

1304 

1305`beta.chatkit.threads.list(**kwargs) -> ConversationCursorPage<ChatKitThread>`

1306 

1307**get** `/chatkit/threads`

1308 

1309List ChatKit threads with optional pagination and user filters.

1310 

1311### Parameters

1312 

1313- `after: String`

1314 

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

1316 

1317- `before: String`

1318 

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

1320 

1321- `limit: Integer`

1322 

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

1324 

1325- `order: :asc | :desc`

1326 

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

1328 

1329 - `:asc`

1330 

1331 - `:desc`

1332 

1333- `user: String`

1334 

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

1336 

1337### Returns

1338 

1339- `class ChatKitThread`

1340 

1341 Represents a ChatKit thread and its current status.

1342 

1343 - `id: String`

1344 

1345 Identifier of the thread.

1346 

1347 - `created_at: Integer`

1348 

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

1350 

1351 - `object: :"chatkit.thread"`

1352 

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

1354 

1355 - `:"chatkit.thread"`

1356 

1357 - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}`

1358 

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

1360 

1361 - `class Active`

1362 

1363 Indicates that a thread is active.

1364 

1365 - `type: :active`

1366 

1367 Status discriminator that is always `active`.

1368 

1369 - `:active`

1370 

1371 - `class Locked`

1372 

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

1374 

1375 - `reason: String`

1376 

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

1378 

1379 - `type: :locked`

1380 

1381 Status discriminator that is always `locked`.

1382 

1383 - `:locked`

1384 

1385 - `class Closed`

1386 

1387 Indicates that a thread has been closed.

1388 

1389 - `reason: String`

1390 

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

1392 

1393 - `type: :closed`

1394 

1395 Status discriminator that is always `closed`.

1396 

1397 - `:closed`

1398 

1399 - `title: String`

1400 

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

1402 

1403 - `user: String`

1404 

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

1406 

1407### Example

1408 

1409```ruby

1410require "openai"

1411 

1412openai = OpenAI::Client.new(api_key: "My API Key")

1413 

1414page = openai.beta.chatkit.threads.list

1415 

1416puts(page)

1417```

1418 

1419#### Response

1420 

1421```json

1422{

1423 "data": [

1424 {

1425 "id": "cthr_def456",

1426 "created_at": 1712345600,

1427 "object": "chatkit.thread",

1428 "status": {

1429 "type": "active"

1430 },

1431 "title": "Demo feedback",

1432 "user": "user_456"

1433 }

1434 ],

1435 "first_id": "first_id",

1436 "has_more": true,

1437 "last_id": "last_id",

1438 "object": "list"

1439}

1440```

1441 

1442### Example

1443 

1444```ruby

1445require "openai"

1446 

1447openai = OpenAI::Client.new

1448 

1449page = openai.beta.chatkit.threads.list

1450 

1451puts(page)

1452```

1453 

1454#### Response

1455 

1456```json

1457{

1458 "data": [

1459 {

1460 "id": "cthr_abc123",

1461 "object": "chatkit.thread",

1462 "title": "Customer escalation"

1463 },

1464 {

1465 "id": "cthr_def456",

1466 "object": "chatkit.thread",

1467 "title": "Demo feedback"

1468 }

1469 ],

1470 "has_more": false,

1471 "object": "list"

1472}

1473```

1474 

1475## Domain Types

1476 

1477### Chat Session

1478 

1479- `class ChatSession`

1480 

1481 Represents a ChatKit session and its resolved configuration.

1482 

1483 - `id: String`

1484 

1485 Identifier for the ChatKit session.

1486 

1487 - `chatkit_configuration: ChatSessionChatKitConfiguration`

1488 

1489 Resolved ChatKit feature configuration for the session.

1490 

1491 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`

1492 

1493 Automatic thread titling preferences.

1494 

1495 - `enabled: bool`

1496 

1497 Whether automatic thread titling is enabled.

1498 

1499 - `file_upload: ChatSessionFileUpload`

1500 

1501 Upload settings for the session.

1502 

1503 - `enabled: bool`

1504 

1505 Indicates if uploads are enabled for the session.

1506 

1507 - `max_file_size: Integer`

1508 

1509 Maximum upload size in megabytes.

1510 

1511 - `max_files: Integer`

1512 

1513 Maximum number of uploads allowed during the session.

1514 

1515 - `history: ChatSessionHistory`

1516 

1517 History retention configuration.

1518 

1519 - `enabled: bool`

1520 

1521 Indicates if chat history is persisted for the session.

1522 

1523 - `recent_threads: Integer`

1524 

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

1526 

1527 - `client_secret: String`

1528 

1529 Ephemeral client secret that authenticates session requests.

1530 

1531 - `expires_at: Integer`

1532 

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

1534 

1535 - `max_requests_per_1_minute: Integer`

1536 

1537 Convenience copy of the per-minute request limit.

1538 

1539 - `object: :"chatkit.session"`

1540 

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

1542 

1543 - `:"chatkit.session"`

1544 

1545 - `rate_limits: ChatSessionRateLimits`

1546 

1547 Resolved rate limit values.

1548 

1549 - `max_requests_per_1_minute: Integer`

1550 

1551 Maximum allowed requests per one-minute window.

1552 

1553 - `status: ChatSessionStatus`

1554 

1555 Current lifecycle state of the session.

1556 

1557 - `:active`

1558 

1559 - `:expired`

1560 

1561 - `:cancelled`

1562 

1563 - `user: String`

1564 

1565 User identifier associated with the session.

1566 

1567 - `workflow: ChatKitWorkflow`

1568 

1569 Workflow metadata for the session.

1570 

1571 - `id: String`

1572 

1573 Identifier of the workflow backing the session.

1574 

1575 - `state_variables: Hash[Symbol, String | bool | Float]`

1576 

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

1578 

1579 - `String = String`

1580 

1581 - `UnionMember1 = bool`

1582 

1583 - `Float = Float`

1584 

1585 - `tracing: Tracing{ enabled}`

1586 

1587 Tracing settings applied to the workflow.

1588 

1589 - `enabled: bool`

1590 

1591 Indicates whether tracing is enabled.

1592 

1593 - `version: String`

1594 

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

1596 

1597### Chat Session Automatic Thread Titling

1598 

1599- `class ChatSessionAutomaticThreadTitling`

1600 

1601 Automatic thread title preferences for the session.

1602 

1603 - `enabled: bool`

1604 

1605 Whether automatic thread titling is enabled.

1606 

1607### Chat Session ChatKit Configuration

1608 

1609- `class ChatSessionChatKitConfiguration`

1610 

1611 ChatKit configuration for the session.

1612 

1613 - `automatic_thread_titling: ChatSessionAutomaticThreadTitling`

1614 

1615 Automatic thread titling preferences.

1616 

1617 - `enabled: bool`

1618 

1619 Whether automatic thread titling is enabled.

1620 

1621 - `file_upload: ChatSessionFileUpload`

1622 

1623 Upload settings for the session.

1624 

1625 - `enabled: bool`

1626 

1627 Indicates if uploads are enabled for the session.

1628 

1629 - `max_file_size: Integer`

1630 

1631 Maximum upload size in megabytes.

1632 

1633 - `max_files: Integer`

1634 

1635 Maximum number of uploads allowed during the session.

1636 

1637 - `history: ChatSessionHistory`

1638 

1639 History retention configuration.

1640 

1641 - `enabled: bool`

1642 

1643 Indicates if chat history is persisted for the session.

1644 

1645 - `recent_threads: Integer`

1646 

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

1648 

1649### Chat Session ChatKit Configuration Param

1650 

1651- `class ChatSessionChatKitConfigurationParam`

1652 

1653 Optional per-session configuration settings for ChatKit behavior.

1654 

1655 - `automatic_thread_titling: AutomaticThreadTitling{ enabled}`

1656 

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

1658 

1659 - `enabled: bool`

1660 

1661 Enable automatic thread title generation. Defaults to true.

1662 

1663 - `file_upload: FileUpload{ enabled, max_file_size, max_files}`

1664 

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

1666 

1667 - `enabled: bool`

1668 

1669 Enable uploads for this session. Defaults to false.

1670 

1671 - `max_file_size: Integer`

1672 

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

1674 

1675 - `max_files: Integer`

1676 

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

1678 

1679 - `history: History{ enabled, recent_threads}`

1680 

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

1682 

1683 - `enabled: bool`

1684 

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

1686 

1687 - `recent_threads: Integer`

1688 

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

1690 

1691### Chat Session Expires After Param

1692 

1693- `class ChatSessionExpiresAfterParam`

1694 

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

1696 

1697 - `anchor: :created_at`

1698 

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

1700 

1701 - `:created_at`

1702 

1703 - `seconds: Integer`

1704 

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

1706 

1707### Chat Session File Upload

1708 

1709- `class ChatSessionFileUpload`

1710 

1711 Upload permissions and limits applied to the session.

1712 

1713 - `enabled: bool`

1714 

1715 Indicates if uploads are enabled for the session.

1716 

1717 - `max_file_size: Integer`

1718 

1719 Maximum upload size in megabytes.

1720 

1721 - `max_files: Integer`

1722 

1723 Maximum number of uploads allowed during the session.

1724 

1725### Chat Session History

1726 

1727- `class ChatSessionHistory`

1728 

1729 History retention preferences returned for the session.

1730 

1731 - `enabled: bool`

1732 

1733 Indicates if chat history is persisted for the session.

1734 

1735 - `recent_threads: Integer`

1736 

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

1738 

1739### Chat Session Rate Limits

1740 

1741- `class ChatSessionRateLimits`

1742 

1743 Active per-minute request limit for the session.

1744 

1745 - `max_requests_per_1_minute: Integer`

1746 

1747 Maximum allowed requests per one-minute window.

1748 

1749### Chat Session Rate Limits Param

1750 

1751- `class ChatSessionRateLimitsParam`

1752 

1753 Controls request rate limits for the session.

1754 

1755 - `max_requests_per_1_minute: Integer`

1756 

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

1758 

1759### Chat Session Status

1760 

1761- `ChatSessionStatus = :active | :expired | :cancelled`

1762 

1763 - `:active`

1764 

1765 - `:expired`

1766 

1767 - `:cancelled`

1768 

1769### Chat Session Workflow Param

1770 

1771- `class ChatSessionWorkflowParam`

1772 

1773 Workflow reference and overrides applied to the chat session.

1774 

1775 - `id: String`

1776 

1777 Identifier for the workflow invoked by the session.

1778 

1779 - `state_variables: Hash[Symbol, String | bool | Float]`

1780 

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

1782 

1783 - `String = String`

1784 

1785 - `UnionMember1 = bool`

1786 

1787 - `Float = Float`

1788 

1789 - `tracing: Tracing{ enabled}`

1790 

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

1792 

1793 - `enabled: bool`

1794 

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

1796 

1797 - `version: String`

1798 

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

1800 

1801### ChatKit Attachment

1802 

1803- `class ChatKitAttachment`

1804 

1805 Attachment metadata included on thread items.

1806 

1807 - `id: String`

1808 

1809 Identifier for the attachment.

1810 

1811 - `mime_type: String`

1812 

1813 MIME type of the attachment.

1814 

1815 - `name: String`

1816 

1817 Original display name for the attachment.

1818 

1819 - `preview_url: String`

1820 

1821 Preview URL for rendering the attachment inline.

1822 

1823 - `type: :image | :file`

1824 

1825 Attachment discriminator.

1826 

1827 - `:image`

1828 

1829 - `:file`

1830 

1831### ChatKit Response Output Text

1832 

1833- `class ChatKitResponseOutputText`

1834 

1835 Assistant response text accompanied by optional annotations.

1836 

1837 - `annotations: Array[File{ source, type} | URL{ source, type}]`

1838 

1839 Ordered list of annotations attached to the response text.

1840 

1841 - `class File`

1842 

1843 Annotation that references an uploaded file.

1844 

1845 - `source: Source{ filename, type}`

1846 

1847 File attachment referenced by the annotation.

1848 

1849 - `filename: String`

1850 

1851 Filename referenced by the annotation.

1852 

1853 - `type: :file`

1854 

1855 Type discriminator that is always `file`.

1856 

1857 - `:file`

1858 

1859 - `type: :file`

1860 

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

1862 

1863 - `:file`

1864 

1865 - `class URL`

1866 

1867 Annotation that references a URL.

1868 

1869 - `source: Source{ type, url}`

1870 

1871 URL referenced by the annotation.

1872 

1873 - `type: :url`

1874 

1875 Type discriminator that is always `url`.

1876 

1877 - `:url`

1878 

1879 - `url: String`

1880 

1881 URL referenced by the annotation.

1882 

1883 - `type: :url`

1884 

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

1886 

1887 - `:url`

1888 

1889 - `text: String`

1890 

1891 Assistant generated text.

1892 

1893 - `type: :output_text`

1894 

1895 Type discriminator that is always `output_text`.

1896 

1897 - `:output_text`

1898 

1899### ChatKit Thread

1900 

1901- `class ChatKitThread`

1902 

1903 Represents a ChatKit thread and its current status.

1904 

1905 - `id: String`

1906 

1907 Identifier of the thread.

1908 

1909 - `created_at: Integer`

1910 

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

1912 

1913 - `object: :"chatkit.thread"`

1914 

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

1916 

1917 - `:"chatkit.thread"`

1918 

1919 - `status: Active{ type} | Locked{ reason, type} | Closed{ reason, type}`

1920 

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

1922 

1923 - `class Active`

1924 

1925 Indicates that a thread is active.

1926 

1927 - `type: :active`

1928 

1929 Status discriminator that is always `active`.

1930 

1931 - `:active`

1932 

1933 - `class Locked`

1934 

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

1936 

1937 - `reason: String`

1938 

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

1940 

1941 - `type: :locked`

1942 

1943 Status discriminator that is always `locked`.

1944 

1945 - `:locked`

1946 

1947 - `class Closed`

1948 

1949 Indicates that a thread has been closed.

1950 

1951 - `reason: String`

1952 

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

1954 

1955 - `type: :closed`

1956 

1957 Status discriminator that is always `closed`.

1958 

1959 - `:closed`

1960 

1961 - `title: String`

1962 

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

1964 

1965 - `user: String`

1966 

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

1968 

1969### ChatKit Thread Assistant Message Item

1970 

1971- `class ChatKitThreadAssistantMessageItem`

1972 

1973 Assistant-authored message within a thread.

1974 

1975 - `id: String`

1976 

1977 Identifier of the thread item.

1978 

1979 - `content: Array[ChatKitResponseOutputText]`

1980 

1981 Ordered assistant response segments.

1982 

1983 - `annotations: Array[File{ source, type} | URL{ source, type}]`

1984 

1985 Ordered list of annotations attached to the response text.

1986 

1987 - `class File`

1988 

1989 Annotation that references an uploaded file.

1990 

1991 - `source: Source{ filename, type}`

1992 

1993 File attachment referenced by the annotation.

1994 

1995 - `filename: String`

1996