cli/resources/responses/methods/compact/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1## Compact a response

2 

3`$ openai responses compact`

4 

5**post** `/responses/compact`

6 

7Compact a conversation. Returns a compacted response object.

8 

9Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).

10 

11### Parameters

12 

13- `--model: "gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 89 more or string`

14 

15 Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models.

16 

17- `--input: optional string or array of ResponseInputItem`

18 

19 Text, image, or file inputs to the model, used to generate a response

20 

21- `--instructions: optional string`

22 

23 A system (or developer) message inserted into the model's context.

24 When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

25 

26- `--previous-response-id: optional string`

27 

28 The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`.

29 

30- `--prompt-cache-key: optional string`

31 

32 A key to use when reading from or writing to the prompt cache.

33 

34- `--prompt-cache-retention: optional "in_memory" or "24h"`

35 

36 How long to retain a prompt cache entry created by this request.

37 

38- `--service-tier: optional "auto" or "default" or "flex" or "priority"`

39 

40 The service tier to use for this request.

41 

42### Returns

43 

44- `compacted_response: object { id, created_at, object, 2 more }`

45 

46 - `id: string`

47 

48 The unique identifier for the compacted response.

49 

50 - `created_at: number`

51 

52 Unix timestamp (in seconds) when the compacted conversation was created.

53 

54 - `object: "response.compaction"`

55 

56 The object type. Always `response.compaction`.

57 

58 - `output: array of ResponseOutputItem`

59 

60 The compacted list of output items. This is a list of all user messages, followed by a single compaction item.

61 

62 - `response_output_message: object { id, content, role, 3 more }`

63 

64 An output message from the model.

65 

66 - `id: string`

67 

68 The unique ID of the output message.

69 

70 - `content: array of ResponseOutputText or ResponseOutputRefusal`

71 

72 The content of the output message.

73 

74 - `response_output_text: object { annotations, text, type, logprobs }`

75 

76 A text output from the model.

77 

78 - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }`

79 

80 The annotations of the text output.

81 

82 - `file_citation: object { file_id, filename, index, type }`

83 

84 A citation to a file.

85 

86 - `file_id: string`

87 

88 The ID of the file.

89 

90 - `filename: string`

91 

92 The filename of the file cited.

93 

94 - `index: number`

95 

96 The index of the file in the list of files.

97 

98 - `type: "file_citation"`

99 

100 The type of the file citation. Always `file_citation`.

101 

102 - `url_citation: object { end_index, start_index, title, 2 more }`

103 

104 A citation for a web resource used to generate a model response.

105 

106 - `end_index: number`

107 

108 The index of the last character of the URL citation in the message.

109 

110 - `start_index: number`

111 

112 The index of the first character of the URL citation in the message.

113 

114 - `title: string`

115 

116 The title of the web resource.

117 

118 - `type: "url_citation"`

119 

120 The type of the URL citation. Always `url_citation`.

121 

122 - `url: string`

123 

124 The URL of the web resource.

125 

126 - `container_file_citation: object { container_id, end_index, file_id, 3 more }`

127 

128 A citation for a container file used to generate a model response.

129 

130 - `container_id: string`

131 

132 The ID of the container file.

133 

134 - `end_index: number`

135 

136 The index of the last character of the container file citation in the message.

137 

138 - `file_id: string`

139 

140 The ID of the file.

141 

142 - `filename: string`

143 

144 The filename of the container file cited.

145 

146 - `start_index: number`

147 

148 The index of the first character of the container file citation in the message.

149 

150 - `type: "container_file_citation"`

151 

152 The type of the container file citation. Always `container_file_citation`.

153 

154 - `file_path: object { file_id, index, type }`

155 

156 A path to a file.

157 

158 - `file_id: string`

159 

160 The ID of the file.

161 

162 - `index: number`

163 

164 The index of the file in the list of files.

165 

166 - `type: "file_path"`

167 

168 The type of the file path. Always `file_path`.

169 

170 - `text: string`

171 

172 The text output from the model.

173 

174 - `type: "output_text"`

175 

176 The type of the output text. Always `output_text`.

177 

178 - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }`

179 

180 - `token: string`

181 

182 - `bytes: array of number`

183 

184 - `logprob: number`

185 

186 - `top_logprobs: array of object { token, bytes, logprob }`

187 

188 - `token: string`

189 

190 - `bytes: array of number`

191 

192 - `logprob: number`

193 

194 - `response_output_refusal: object { refusal, type }`

195 

196 A refusal from the model.

197 

198 - `refusal: string`

199 

200 The refusal explanation from the model.

201 

202 - `type: "refusal"`

203 

204 The type of the refusal. Always `refusal`.

205 

206 - `role: "assistant"`

207 

208 The role of the output message. Always `assistant`.

209 

210 - `status: "in_progress" or "completed" or "incomplete"`

211 

212 The status of the message input. One of `in_progress`, `completed`, or

213 `incomplete`. Populated when input items are returned via API.

214 

215 - `"in_progress"`

216 

217 - `"completed"`

218 

219 - `"incomplete"`

220 

221 - `type: "message"`

222 

223 The type of the output message. Always `message`.

224 

225 - `phase: optional "commentary" or "final_answer"`

226 

227 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`).

228 For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend

229 phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

230 

231 - `"commentary"`

232 

233 - `"final_answer"`

234 

235 - `response_file_search_tool_call: object { id, queries, status, 2 more }`

236 

237 The results of a file search tool call. See the

238 [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information.

239 

240 - `id: string`

241 

242 The unique ID of the file search tool call.

243 

244 - `queries: array of string`

245 

246 The queries used to search for files.

247 

248 - `status: "in_progress" or "searching" or "completed" or 2 more`

249 

250 The status of the file search tool call. One of `in_progress`,

251 `searching`, `incomplete` or `failed`,

252 

253 - `"in_progress"`

254 

255 - `"searching"`

256 

257 - `"completed"`

258 

259 - `"incomplete"`

260 

261 - `"failed"`

262 

263 - `type: "file_search_call"`

264 

265 The type of the file search tool call. Always `file_search_call`.

266 

267 - `results: optional array of object { attributes, file_id, filename, 2 more }`

268 

269 The results of the file search tool call.

270 

271 - `attributes: optional map[string or number or boolean]`

272 

273 Set of 16 key-value pairs that can be attached to an object. This can be

274 useful for storing additional information about the object in a structured

275 format, and querying for objects via API or the dashboard. Keys are strings

276 with a maximum length of 64 characters. Values are strings with a maximum

277 length of 512 characters, booleans, or numbers.

278 

279 - `union_member_0: string`

280 

281 - `union_member_1: number`

282 

283 - `union_member_2: boolean`

284 

285 - `file_id: optional string`

286 

287 The unique ID of the file.

288 

289 - `filename: optional string`

290 

291 The name of the file.

292 

293 - `score: optional number`

294 

295 The relevance score of the file - a value between 0 and 1.

296 

297 - `text: optional string`

298 

299 The text that was retrieved from the file.

300 

301 - `response_function_tool_call: object { arguments, call_id, name, 4 more }`

302 

303 A tool call to run a function. See the

304 [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information.

305 

306 - `arguments: string`

307 

308 A JSON string of the arguments to pass to the function.

309 

310 - `call_id: string`

311 

312 The unique ID of the function tool call generated by the model.

313 

314 - `name: string`

315 

316 The name of the function to run.

317 

318 - `type: "function_call"`

319 

320 The type of the function tool call. Always `function_call`.

321 

322 - `id: optional string`

323 

324 The unique ID of the function tool call.

325 

326 - `namespace: optional string`

327 

328 The namespace of the function to run.

329 

330 - `status: optional "in_progress" or "completed" or "incomplete"`

331 

332 The status of the item. One of `in_progress`, `completed`, or

333 `incomplete`. Populated when items are returned via API.

334 

335 - `"in_progress"`

336 

337 - `"completed"`

338 

339 - `"incomplete"`

340 

341 - `response_function_tool_call_output_item: object { id, call_id, output, 3 more }`

342 

343 - `id: string`

344 

345 The unique ID of the function call tool output.

346 

347 - `call_id: string`

348 

349 The unique ID of the function tool call generated by the model.

350 

351 - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile`

352 

353 The output from the function call generated by your code.

354 Can be a string or an list of output content.

355 

356 - `string output: string`

357 

358 A string of the output of the function call.

359 

360 - `output content list: array of ResponseInputText or ResponseInputImage or ResponseInputFile`

361 

362 Text, image, or file output of the function call.

363 

364 - `response_input_text: object { text, type }`

365 

366 A text input to the model.

367 

368 - `text: string`

369 

370 The text input to the model.

371 

372 - `type: "input_text"`

373 

374 The type of the input item. Always `input_text`.

375 

376 - `response_input_image: object { detail, type, file_id, image_url }`

377 

378 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).

379 

380 - `detail: "low" or "high" or "auto" or "original"`

381 

382 The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.

383 

384 - `"low"`

385 

386 - `"high"`

387 

388 - `"auto"`

389 

390 - `"original"`

391 

392 - `type: "input_image"`

393 

394 The type of the input item. Always `input_image`.

395 

396 - `file_id: optional string`

397 

398 The ID of the file to be sent to the model.

399 

400 - `image_url: optional string`

401 

402 The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

403 

404 - `response_input_file: object { type, detail, file_data, 3 more }`

405 

406 A file input to the model.

407 

408 - `type: "input_file"`

409 

410 The type of the input item. Always `input_file`.

411 

412 - `detail: optional "low" or "high"`

413 

414 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

415 

416 - `"low"`

417 

418 - `"high"`

419 

420 - `file_data: optional string`

421 

422 The content of the file to be sent to the model.

423 

424 - `file_id: optional string`

425 

426 The ID of the file to be sent to the model.

427 

428 - `file_url: optional string`

429 

430 The URL of the file to be sent to the model.

431 

432 - `filename: optional string`

433 

434 The name of the file to be sent to the model.

435 

436 - `status: "in_progress" or "completed" or "incomplete"`

437 

438 The status of the item. One of `in_progress`, `completed`, or

439 `incomplete`. Populated when items are returned via API.

440 

441 - `"in_progress"`

442 

443 - `"completed"`

444 

445 - `"incomplete"`

446 

447 - `type: "function_call_output"`

448 

449 The type of the function tool call output. Always `function_call_output`.

450 

451 - `created_by: optional string`

452 

453 The identifier of the actor that created the item.

454 

455 - `response_function_web_search: object { id, action, status, type }`

456 

457 The results of a web search tool call. See the

458 [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information.

459 

460 - `id: string`

461 

462 The unique ID of the web search tool call.

463 

464 - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }`

465 

466 An object describing the specific action taken in this web search call.

467 Includes details on how the model used the web (search, open_page, find_in_page).

468 

469 - `search: object { query, type, queries, sources }`

470 

471 Action type "search" - Performs a web search query.

472 

473 - `query: string`

474 

475 [DEPRECATED] The search query.

476 

477 - `type: "search"`

478 

479 The action type.

480 

481 - `queries: optional array of string`

482 

483 The search queries.

484 

485 - `sources: optional array of object { type, url }`

486 

487 The sources used in the search.

488 

489 - `type: "url"`

490 

491 The type of source. Always `url`.

492 

493 - `url: string`

494 

495 The URL of the source.

496 

497 - `open_page: object { type, url }`

498 

499 Action type "open_page" - Opens a specific URL from search results.

500 

501 - `type: "open_page"`

502 

503 The action type.

504 

505 - `url: optional string`

506 

507 The URL opened by the model.

508 

509 - `find_in_page: object { pattern, type, url }`

510 

511 Action type "find_in_page": Searches for a pattern within a loaded page.

512 

513 - `pattern: string`

514 

515 The pattern or text to search for within the page.

516 

517 - `type: "find_in_page"`

518 

519 The action type.

520 

521 - `url: string`

522 

523 The URL of the page searched for the pattern.

524 

525 - `status: "in_progress" or "searching" or "completed" or "failed"`

526 

527 The status of the web search tool call.

528 

529 - `"in_progress"`

530 

531 - `"searching"`

532 

533 - `"completed"`

534 

535 - `"failed"`

536 

537 - `type: "web_search_call"`

538 

539 The type of the web search tool call. Always `web_search_call`.

540 

541 - `response_computer_tool_call: object { id, call_id, pending_safety_checks, 4 more }`

542 

543 A tool call to a computer use tool. See the

544 [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information.

545 

546 - `id: string`

547 

548 The unique ID of the computer call.

549 

550 - `call_id: string`

551 

552 An identifier used when responding to the tool call with output.

553 

554 - `pending_safety_checks: array of object { id, code, message }`

555 

556 The pending safety checks for the computer call.

557 

558 - `id: string`

559 

560 The ID of the pending safety check.

561 

562 - `code: optional string`

563 

564 The type of the pending safety check.

565 

566 - `message: optional string`

567 

568 Details about the pending safety check.

569 

570 - `status: "in_progress" or "completed" or "incomplete"`

571 

572 The status of the item. One of `in_progress`, `completed`, or

573 `incomplete`. Populated when items are returned via API.

574 

575 - `"in_progress"`

576 

577 - `"completed"`

578 

579 - `"incomplete"`

580 

581 - `type: "computer_call"`

582 

583 The type of the computer call. Always `computer_call`.

584 

585 - `"computer_call"`

586 

587 - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more`

588 

589 A click action.

590 

591 - `click: object { button, type, x, 2 more }`

592 

593 A click action.

594 

595 - `button: "left" or "right" or "wheel" or 2 more`

596 

597 Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.

598 

599 - `"left"`

600 

601 - `"right"`

602 

603 - `"wheel"`

604 

605 - `"back"`

606 

607 - `"forward"`

608 

609 - `type: "click"`

610 

611 Specifies the event type. For a click action, this property is always `click`.

612 

613 - `x: number`

614 

615 The x-coordinate where the click occurred.

616 

617 - `y: number`

618 

619 The y-coordinate where the click occurred.

620 

621 - `keys: optional array of string`

622 

623 The keys being held while clicking.

624 

625 - `double_click: object { keys, type, x, y }`

626 

627 A double click action.

628 

629 - `keys: array of string`

630 

631 The keys being held while double-clicking.

632 

633 - `type: "double_click"`

634 

635 Specifies the event type. For a double click action, this property is always set to `double_click`.

636 

637 - `x: number`

638 

639 The x-coordinate where the double click occurred.

640 

641 - `y: number`

642 

643 The y-coordinate where the double click occurred.

644 

645 - `drag: object { path, type, keys }`

646 

647 A drag action.

648 

649 - `path: array of object { x, y }`

650 

651 An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg

652 

653 ```

654 [

655 { x: 100, y: 200 },

656 { x: 200, y: 300 }

657 ]

658 ```

659 

660 - `x: number`

661 

662 The x-coordinate.

663 

664 - `y: number`

665 

666 The y-coordinate.

667 

668 - `type: "drag"`

669 

670 Specifies the event type. For a drag action, this property is always set to `drag`.

671 

672 - `keys: optional array of string`

673 

674 The keys being held while dragging the mouse.

675 

676 - `keypress: object { keys, type }`

677 

678 A collection of keypresses the model would like to perform.

679 

680 - `keys: array of string`

681 

682 The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

683 

684 - `type: "keypress"`

685 

686 Specifies the event type. For a keypress action, this property is always set to `keypress`.

687 

688 - `move: object { type, x, y, keys }`

689 

690 A mouse move action.

691 

692 - `type: "move"`

693 

694 Specifies the event type. For a move action, this property is always set to `move`.

695 

696 - `x: number`

697 

698 The x-coordinate to move to.

699 

700 - `y: number`

701 

702 The y-coordinate to move to.

703 

704 - `keys: optional array of string`

705 

706 The keys being held while moving the mouse.

707 

708 - `screenshot: object { type }`

709 

710 A screenshot action.

711 

712 - `scroll: object { scroll_x, scroll_y, type, 3 more }`

713 

714 A scroll action.

715 

716 - `scroll_x: number`

717 

718 The horizontal scroll distance.

719 

720 - `scroll_y: number`

721 

722 The vertical scroll distance.

723 

724 - `type: "scroll"`

725 

726 Specifies the event type. For a scroll action, this property is always set to `scroll`.

727 

728 - `x: number`

729 

730 The x-coordinate where the scroll occurred.

731 

732 - `y: number`

733 

734 The y-coordinate where the scroll occurred.

735 

736 - `keys: optional array of string`

737 

738 The keys being held while scrolling.

739 

740 - `type: object { text, type }`

741 

742 An action to type in text.

743 

744 - `text: string`

745 

746 The text to type.

747 

748 - `type: "type"`

749 

750 Specifies the event type. For a type action, this property is always set to `type`.

751 

752 - `wait: object { type }`

753 

754 A wait action.

755 

756 - `actions: optional array of ComputerAction`

757 

758 Flattened batched actions for `computer_use`. Each action includes an

759 `type` discriminator and action-specific fields.

760 

761 - `click: object { button, type, x, 2 more }`

762 

763 A click action.

764 

765 - `button: "left" or "right" or "wheel" or 2 more`

766 

767 Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.

768 

769 - `"left"`

770 

771 - `"right"`

772 

773 - `"wheel"`

774 

775 - `"back"`

776 

777 - `"forward"`

778 

779 - `type: "click"`

780 

781 Specifies the event type. For a click action, this property is always `click`.

782 

783 - `x: number`

784 

785 The x-coordinate where the click occurred.

786 

787 - `y: number`

788 

789 The y-coordinate where the click occurred.

790 

791 - `keys: optional array of string`

792 

793 The keys being held while clicking.

794 

795 - `double_click: object { keys, type, x, y }`

796 

797 A double click action.

798 

799 - `keys: array of string`

800 

801 The keys being held while double-clicking.

802 

803 - `type: "double_click"`

804 

805 Specifies the event type. For a double click action, this property is always set to `double_click`.

806 

807 - `x: number`

808 

809 The x-coordinate where the double click occurred.

810 

811 - `y: number`

812 

813 The y-coordinate where the double click occurred.

814 

815 - `drag: object { path, type, keys }`

816 

817 A drag action.

818 

819 - `path: array of object { x, y }`

820 

821 An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg

822 

823 ```

824 [

825 { x: 100, y: 200 },

826 { x: 200, y: 300 }

827 ]

828 ```

829 

830 - `x: number`

831 

832 The x-coordinate.

833 

834 - `y: number`

835 

836 The y-coordinate.

837 

838 - `type: "drag"`

839 

840 Specifies the event type. For a drag action, this property is always set to `drag`.

841 

842 - `keys: optional array of string`

843 

844 The keys being held while dragging the mouse.

845 

846 - `keypress: object { keys, type }`

847 

848 A collection of keypresses the model would like to perform.

849 

850 - `keys: array of string`

851 

852 The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

853 

854 - `type: "keypress"`

855 

856 Specifies the event type. For a keypress action, this property is always set to `keypress`.

857 

858 - `move: object { type, x, y, keys }`

859 

860 A mouse move action.

861 

862 - `type: "move"`

863 

864 Specifies the event type. For a move action, this property is always set to `move`.

865 

866 - `x: number`

867 

868 The x-coordinate to move to.

869 

870 - `y: number`

871 

872 The y-coordinate to move to.

873 

874 - `keys: optional array of string`

875 

876 The keys being held while moving the mouse.

877 

878 - `screenshot: object { type }`

879 

880 A screenshot action.

881 

882 - `scroll: object { scroll_x, scroll_y, type, 3 more }`

883 

884 A scroll action.

885 

886 - `scroll_x: number`

887 

888 The horizontal scroll distance.

889 

890 - `scroll_y: number`

891 

892 The vertical scroll distance.

893 

894 - `type: "scroll"`

895 

896 Specifies the event type. For a scroll action, this property is always set to `scroll`.

897 

898 - `x: number`

899 

900 The x-coordinate where the scroll occurred.

901 

902 - `y: number`

903 

904 The y-coordinate where the scroll occurred.

905 

906 - `keys: optional array of string`

907 

908 The keys being held while scrolling.

909 

910 - `type: object { text, type }`

911 

912 An action to type in text.

913 

914 - `text: string`

915 

916 The text to type.

917 

918 - `type: "type"`

919 

920 Specifies the event type. For a type action, this property is always set to `type`.

921 

922 - `wait: object { type }`

923 

924 A wait action.

925 

926 - `response_computer_tool_call_output_item: object { id, call_id, output, 4 more }`

927 

928 - `id: string`

929 

930 The unique ID of the computer call tool output.

931 

932 - `call_id: string`

933 

934 The ID of the computer tool call that produced the output.

935 

936 - `output: object { type, file_id, image_url }`

937 

938 A computer screenshot image used with the computer use tool.

939 

940 - `type: "computer_screenshot"`

941 

942 Specifies the event type. For a computer screenshot, this property is

943 always set to `computer_screenshot`.

944 

945 - `file_id: optional string`

946 

947 The identifier of an uploaded file that contains the screenshot.

948 

949 - `image_url: optional string`

950 

951 The URL of the screenshot image.

952 

953 - `status: "completed" or "incomplete" or "failed" or "in_progress"`

954 

955 The status of the message input. One of `in_progress`, `completed`, or

956 `incomplete`. Populated when input items are returned via API.

957 

958 - `"completed"`

959 

960 - `"incomplete"`

961 

962 - `"failed"`

963 

964 - `"in_progress"`

965 

966 - `type: "computer_call_output"`

967 

968 The type of the computer tool call output. Always `computer_call_output`.

969 

970 - `acknowledged_safety_checks: optional array of object { id, code, message }`

971 

972 The safety checks reported by the API that have been acknowledged by the

973 developer.

974 

975 - `id: string`

976 

977 The ID of the pending safety check.

978 

979 - `code: optional string`

980 

981 The type of the pending safety check.

982 

983 - `message: optional string`

984 

985 Details about the pending safety check.

986 

987 - `created_by: optional string`

988 

989 The identifier of the actor that created the item.

990 

991 - `response_reasoning_item: object { id, summary, type, 3 more }`

992 

993 A description of the chain of thought used by a reasoning model while generating

994 a response. Be sure to include these items in your `input` to the Responses API

995 for subsequent turns of a conversation if you are manually

996 [managing context](https://platform.openai.com/docs/guides/conversation-state).

997 

998 - `id: string`

999 

1000 The unique identifier of the reasoning content.

1001 

1002 - `summary: array of object { text, type }`

1003 

1004 Reasoning summary content.

1005 

1006 - `text: string`

1007 

1008 A summary of the reasoning output from the model so far.

1009 

1010 - `type: "summary_text"`

1011 

1012 The type of the object. Always `summary_text`.

1013 

1014 - `type: "reasoning"`

1015 

1016 The type of the object. Always `reasoning`.

1017 

1018 - `content: optional array of object { text, type }`

1019 

1020 Reasoning text content.

1021 

1022 - `text: string`

1023 

1024 The reasoning text from the model.

1025 

1026 - `type: "reasoning_text"`

1027 

1028 The type of the reasoning text. Always `reasoning_text`.

1029 

1030 - `encrypted_content: optional string`

1031 

1032 The encrypted content of the reasoning item - populated when a response is

1033 generated with `reasoning.encrypted_content` in the `include` parameter.

1034 

1035 - `status: optional "in_progress" or "completed" or "incomplete"`

1036 

1037 The status of the item. One of `in_progress`, `completed`, or

1038 `incomplete`. Populated when items are returned via API.

1039 

1040 - `"in_progress"`

1041 

1042 - `"completed"`

1043 

1044 - `"incomplete"`

1045 

1046 - `response_tool_search_call: object { id, arguments, call_id, 4 more }`

1047 

1048 - `id: string`

1049 

1050 The unique ID of the tool search call item.

1051 

1052 - `arguments: unknown`

1053 

1054 Arguments used for the tool search call.

1055 

1056 - `call_id: string`

1057 

1058 The unique ID of the tool search call generated by the model.

1059 

1060 - `execution: "server" or "client"`

1061 

1062 Whether tool search was executed by the server or by the client.

1063 

1064 - `"server"`

1065 

1066 - `"client"`

1067 

1068 - `status: "in_progress" or "completed" or "incomplete"`

1069 

1070 The status of the tool search call item that was recorded.

1071 

1072 - `"in_progress"`

1073 

1074 - `"completed"`

1075 

1076 - `"incomplete"`

1077 

1078 - `type: "tool_search_call"`

1079 

1080 The type of the item. Always `tool_search_call`.

1081 

1082 - `created_by: optional string`

1083 

1084 The identifier of the actor that created the item.

1085 

1086 - `response_tool_search_output_item: object { id, call_id, execution, 4 more }`

1087 

1088 - `id: string`

1089 

1090 The unique ID of the tool search output item.

1091 

1092 - `call_id: string`

1093 

1094 The unique ID of the tool search call generated by the model.

1095 

1096 - `execution: "server" or "client"`

1097 

1098 Whether tool search was executed by the server or by the client.

1099 

1100 - `"server"`

1101 

1102 - `"client"`

1103 

1104 - `status: "in_progress" or "completed" or "incomplete"`

1105 

1106 The status of the tool search output item that was recorded.

1107 

1108 - `"in_progress"`

1109 

1110 - `"completed"`

1111 

1112 - `"incomplete"`

1113 

1114 - `tools: array of Tool`

1115 

1116 The loaded tool definitions returned by tool search.

1117 

1118 - `function_tool: object { name, parameters, strict, 3 more }`

1119 

1120 Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

1121 

1122 - `name: string`

1123 

1124 The name of the function to call.

1125 

1126 - `parameters: map[unknown]`

1127 

1128 A JSON schema object describing the parameters of the function.

1129 

1130 - `strict: boolean`

1131 

1132 Whether to enforce strict parameter validation. Default `true`.

1133 

1134 - `type: "function"`

1135 

1136 The type of the function tool. Always `function`.

1137 

1138 - `defer_loading: optional boolean`

1139 

1140 Whether this function is deferred and loaded via tool search.

1141 

1142 - `description: optional string`

1143 

1144 A description of the function. Used by the model to determine whether or not to call the function.

1145 

1146 - `file_search_tool: object { type, vector_store_ids, filters, 2 more }`

1147 

1148 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

1149 

1150 - `type: "file_search"`

1151 

1152 The type of the file search tool. Always `file_search`.

1153 

1154 - `vector_store_ids: array of string`

1155 

1156 The IDs of the vector stores to search.

1157 

1158 - `filters: optional ComparisonFilter or CompoundFilter`

1159 

1160 A filter to apply.

1161 

1162 - `comparison_filter: object { key, type, value }`

1163 

1164 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

1165 

1166 - `key: string`

1167 

1168 The key to compare against the value.

1169 

1170 - `type: "eq" or "ne" or "gt" or 5 more`

1171 

1172 Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.

1173 

1174 - `eq`: equals

1175 - `ne`: not equal

1176 - `gt`: greater than

1177 - `gte`: greater than or equal

1178 - `lt`: less than

1179 - `lte`: less than or equal

1180 - `in`: in

1181 - `nin`: not in

1182 

1183 - `"eq"`

1184 

1185 - `"ne"`

1186 

1187 - `"gt"`

1188 

1189 - `"gte"`

1190 

1191 - `"lt"`

1192 

1193 - `"lte"`

1194 

1195 - `"in"`

1196 

1197 - `"nin"`

1198 

1199 - `value: string or number or boolean or array of string or number`

1200 

1201 The value to compare against the attribute key; supports string, number, or boolean types.

1202 

1203 - `union_member_0: string`

1204 

1205 - `union_member_1: number`

1206 

1207 - `union_member_2: boolean`

1208 

1209 - `union_member_3: array of string or number`

1210 

1211 - `union_member_0: string`

1212 

1213 - `union_member_1: number`

1214 

1215 - `compound_filter: object { filters, type }`

1216 

1217 Combine multiple filters using `and` or `or`.

1218 

1219 - `filters: array of ComparisonFilter or unknown`

1220 

1221 Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

1222 

1223 - `comparison_filter: object { key, type, value }`

1224 

1225 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

1226 

1227 - `union_member_1: unknown`

1228 

1229 - `type: "and" or "or"`

1230 

1231 Type of operation: `and` or `or`.

1232 

1233 - `"and"`

1234 

1235 - `"or"`

1236 

1237 - `max_num_results: optional number`

1238 

1239 The maximum number of results to return. This number should be between 1 and 50 inclusive.

1240 

1241 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }`

1242 

1243 Ranking options for search.

1244 

1245 - `hybrid_search: optional object { embedding_weight, text_weight }`

1246 

1247 Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

1248 

1249 - `embedding_weight: number`

1250 

1251 The weight of the embedding in the reciprocal ranking fusion.

1252 

1253 - `text_weight: number`

1254 

1255 The weight of the text in the reciprocal ranking fusion.

1256 

1257 - `ranker: optional "auto" or "default-2024-11-15"`

1258 

1259 The ranker to use for the file search.

1260 

1261 - `"auto"`

1262 

1263 - `"default-2024-11-15"`

1264 

1265 - `score_threshold: optional number`

1266 

1267 The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.

1268 

1269 - `computer_tool: object { type }`

1270 

1271 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1272 

1273 - `type: "computer"`

1274 

1275 The type of the computer tool. Always `computer`.

1276 

1277 - `computer_use_preview_tool: object { display_height, display_width, environment, type }`

1278 

1279 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1280 

1281 - `display_height: number`

1282 

1283 The height of the computer display.

1284 

1285 - `display_width: number`

1286 

1287 The width of the computer display.

1288 

1289 - `environment: "windows" or "mac" or "linux" or 2 more`

1290 

1291 The type of computer environment to control.

1292 

1293 - `"windows"`

1294 

1295 - `"mac"`

1296 

1297 - `"linux"`

1298 

1299 - `"ubuntu"`

1300 

1301 - `"browser"`

1302 

1303 - `type: "computer_use_preview"`

1304 

1305 The type of the computer use tool. Always `computer_use_preview`.

1306 

1307 - `web_search_tool: object { type, filters, search_context_size, user_location }`

1308 

1309 Search the Internet for sources related to the prompt. Learn more about the

1310 [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

1311 

1312 - `type: "web_search" or "web_search_2025_08_26"`

1313 

1314 The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.

1315 

1316 - `"web_search"`

1317 

1318 - `"web_search_2025_08_26"`

1319 

1320 - `filters: optional object { allowed_domains }`

1321 

1322 Filters for the search.

1323 

1324 - `allowed_domains: optional array of string`

1325 

1326 Allowed domains for the search. If not provided, all domains are allowed.

1327 Subdomains of the provided domains are allowed as well.

1328 

1329 Example: `["pubmed.ncbi.nlm.nih.gov"]`

1330 

1331 - `search_context_size: optional "low" or "medium" or "high"`

1332 

1333 High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.

1334 

1335 - `"low"`

1336 

1337 - `"medium"`

1338 

1339 - `"high"`

1340 

1341 - `user_location: optional object { city, country, region, 2 more }`

1342 

1343 The approximate location of the user.

1344 

1345 - `city: optional string`

1346 

1347 Free text input for the city of the user, e.g. `San Francisco`.

1348 

1349 - `country: optional string`

1350 

1351 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

1352 

1353 - `region: optional string`

1354 

1355 Free text input for the region of the user, e.g. `California`.

1356 

1357 - `timezone: optional string`

1358 

1359 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

1360 

1361 - `type: optional "approximate"`

1362 

1363 The type of location approximation. Always `approximate`.

1364 

1365 - `"approximate"`

1366 

1367 - `mcp: object { server_label, type, allowed_tools, 7 more }`

1368 

1369 Give the model access to additional tools via remote Model Context Protocol

1370 (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).

1371 

1372 - `server_label: string`

1373 

1374 A label for this MCP server, used to identify it in tool calls.

1375 

1376 - `type: "mcp"`

1377 

1378 The type of the MCP tool. Always `mcp`.

1379 

1380 - `allowed_tools: optional array of string or object { read_only, tool_names }`

1381 

1382 List of allowed tool names or a filter object.

1383 

1384 - `MCP allowed tools: array of string`

1385 

1386 A string array of allowed tool names

1387 

1388 - `MCP tool filter: object { read_only, tool_names }`

1389 

1390 A filter object to specify which tools are allowed.

1391 

1392 - `read_only: optional boolean`

1393 

1394 Indicates whether or not a tool modifies data or is read-only. If an

1395 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1396 it will match this filter.

1397 

1398 - `tool_names: optional array of string`

1399 

1400 List of allowed tool names.

1401 

1402 - `authorization: optional string`

1403 

1404 An OAuth access token that can be used with a remote MCP server, either

1405 with a custom MCP server URL or a service connector. Your application

1406 must handle the OAuth authorization flow and provide the token here.

1407 

1408 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more`

1409 

1410 Identifier for service connectors, like those available in ChatGPT. One of

1411 `server_url` or `connector_id` must be provided. Learn more about service

1412 connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).

1413 

1414 Currently supported `connector_id` values are:

1415 

1416 - Dropbox: `connector_dropbox`

1417 - Gmail: `connector_gmail`

1418 - Google Calendar: `connector_googlecalendar`

1419 - Google Drive: `connector_googledrive`

1420 - Microsoft Teams: `connector_microsoftteams`

1421 - Outlook Calendar: `connector_outlookcalendar`

1422 - Outlook Email: `connector_outlookemail`

1423 - SharePoint: `connector_sharepoint`

1424 

1425 - `"connector_dropbox"`

1426 

1427 - `"connector_gmail"`

1428 

1429 - `"connector_googlecalendar"`

1430 

1431 - `"connector_googledrive"`

1432 

1433 - `"connector_microsoftteams"`

1434 

1435 - `"connector_outlookcalendar"`

1436 

1437 - `"connector_outlookemail"`

1438 

1439 - `"connector_sharepoint"`

1440 

1441 - `defer_loading: optional boolean`

1442 

1443 Whether this MCP tool is deferred and discovered via tool search.

1444 

1445 - `headers: optional map[string]`

1446 

1447 Optional HTTP headers to send to the MCP server. Use for authentication

1448 or other purposes.

1449 

1450 - `require_approval: optional object { always, never } or "always" or "never"`

1451 

1452 Specify which of the MCP server's tools require approval.

1453 

1454 - `MCP tool approval filter: object { always, never }`

1455 

1456 Specify which of the MCP server's tools require approval. Can be

1457 `always`, `never`, or a filter object associated with tools

1458 that require approval.

1459 

1460 - `always: optional object { read_only, tool_names }`

1461 

1462 A filter object to specify which tools are allowed.

1463 

1464 - `read_only: optional boolean`

1465 

1466 Indicates whether or not a tool modifies data or is read-only. If an

1467 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1468 it will match this filter.

1469 

1470 - `tool_names: optional array of string`

1471 

1472 List of allowed tool names.

1473 

1474 - `never: optional object { read_only, tool_names }`

1475 

1476 A filter object to specify which tools are allowed.

1477 

1478 - `read_only: optional boolean`

1479 

1480 Indicates whether or not a tool modifies data or is read-only. If an

1481 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1482 it will match this filter.

1483 

1484 - `tool_names: optional array of string`

1485 

1486 List of allowed tool names.

1487 

1488 - `MCP tool approval setting: "always" or "never"`

1489 

1490 Specify a single approval policy for all tools. One of `always` or

1491 `never`. When set to `always`, all tools will require approval. When

1492 set to `never`, all tools will not require approval.

1493 

1494 - `"always"`

1495 

1496 - `"never"`

1497 

1498 - `server_description: optional string`

1499 

1500 Optional description of the MCP server, used to provide more context.

1501 

1502 - `server_url: optional string`

1503 

1504 The URL for the MCP server. One of `server_url` or `connector_id` must be

1505 provided.

1506 

1507 - `code_interpreter: object { container, type }`

1508 

1509 A tool that runs Python code to help generate a response to a prompt.

1510 

1511 - `container: string or object { type, file_ids, memory_limit, network_policy }`

1512 

1513 The code interpreter container. Can be a container ID or an object that

1514 specifies uploaded file IDs to make available to your code, along with an

1515 optional `memory_limit` setting.

1516 

1517 - `union_member_0: string`

1518 

1519 The container ID.

1520 

1521 - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }`

1522 

1523 Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

1524 

1525 - `type: "auto"`

1526 

1527 Always `auto`.

1528 

1529 - `file_ids: optional array of string`

1530 

1531 An optional list of uploaded files to make available to your code.

1532 

1533 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

1534 

1535 The memory limit for the code interpreter container.

1536 

1537 - `"1g"`

1538 

1539 - `"4g"`

1540 

1541 - `"16g"`

1542 

1543 - `"64g"`

1544 

1545 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1546 

1547 Network access policy for the container.

1548 

1549 - `container_network_policy_disabled: object { type }`

1550 

1551 - `type: "disabled"`

1552 

1553 Disable outbound network access. Always `disabled`.

1554 

1555 - `container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }`

1556 

1557 - `allowed_domains: array of string`

1558 

1559 A list of allowed domains when type is `allowlist`.

1560 

1561 - `type: "allowlist"`

1562 

1563 Allow outbound network access only to specified domains. Always `allowlist`.

1564 

1565 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1566 

1567 Optional domain-scoped secrets for allowlisted domains.

1568 

1569 - `domain: string`

1570 

1571 The domain associated with the secret.

1572 

1573 - `name: string`

1574 

1575 The name of the secret to inject for the domain.

1576 

1577 - `value: string`

1578 

1579 The secret value to inject for the domain.

1580 

1581 - `type: "code_interpreter"`

1582 

1583 The type of the code interpreter tool. Always `code_interpreter`.

1584 

1585 - `image_generation: object { type, action, background, 9 more }`

1586 

1587 A tool that generates images using the GPT image models.

1588 

1589 - `type: "image_generation"`

1590 

1591 The type of the image generation tool. Always `image_generation`.

1592 

1593 - `action: optional "generate" or "edit" or "auto"`

1594 

1595 Whether to generate a new image or edit an existing image. Default: `auto`.

1596 

1597 - `"generate"`

1598 

1599 - `"edit"`

1600 

1601 - `"auto"`

1602 

1603 - `background: optional "transparent" or "opaque" or "auto"`

1604 

1605 Allows to set transparency for the background of the generated image(s).

1606 This parameter is only supported for GPT image models that support

1607 transparent backgrounds. Must be one of `transparent`, `opaque`, or

1608 `auto` (default value). When `auto` is used, the model will

1609 automatically determine the best background for the image.

1610 

1611 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support

1612 transparent backgrounds. Requests with `background` set to

1613 `transparent` will return an error for these models; use `opaque` or

1614 `auto` instead.

1615 

1616 If `transparent`, the output format needs to support transparency,

1617 so it should be set to either `png` (default value) or `webp`.

1618 

1619 - `"transparent"`

1620 

1621 - `"opaque"`

1622 

1623 - `"auto"`

1624 

1625 - `input_fidelity: optional "high" or "low"`

1626 

1627 Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.

1628 

1629 - `"high"`

1630 

1631 - `"low"`

1632 

1633 - `input_image_mask: optional object { file_id, image_url }`

1634 

1635 Optional mask for inpainting. Contains `image_url`

1636 (string, optional) and `file_id` (string, optional).

1637 

1638 - `file_id: optional string`

1639 

1640 File ID for the mask image.

1641 

1642 - `image_url: optional string`

1643 

1644 Base64-encoded mask image.

1645 

1646 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more`

1647 

1648 The image generation model to use. Default: `gpt-image-1`.

1649 

1650 - `"gpt-image-1"`

1651 

1652 - `"gpt-image-1-mini"`

1653 

1654 - `"gpt-image-2"`

1655 

1656 - `"gpt-image-2-2026-04-21"`

1657 

1658 - `"gpt-image-1.5"`

1659 

1660 - `"chatgpt-image-latest"`

1661 

1662 - `moderation: optional "auto" or "low"`

1663 

1664 Moderation level for the generated image. Default: `auto`.

1665 

1666 - `"auto"`

1667 

1668 - `"low"`

1669 

1670 - `output_compression: optional number`

1671 

1672 Compression level for the output image. Default: 100.

1673 

1674 - `output_format: optional "png" or "webp" or "jpeg"`

1675 

1676 The output format of the generated image. One of `png`, `webp`, or

1677 `jpeg`. Default: `png`.

1678 

1679 - `"png"`

1680 

1681 - `"webp"`

1682 

1683 - `"jpeg"`

1684 

1685 - `partial_images: optional number`

1686 

1687 Number of partial images to generate in streaming mode, from 0 (default value) to 3.

1688 

1689 - `quality: optional "low" or "medium" or "high" or "auto"`

1690 

1691 The quality of the generated image. One of `low`, `medium`, `high`,

1692 or `auto`. Default: `auto`.

1693 

1694 - `"low"`

1695 

1696 - `"medium"`

1697 

1698 - `"high"`

1699 

1700 - `"auto"`

1701 

1702 - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1703 

1704 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1705 

1706 - `"1024x1024"`

1707 

1708 - `"1024x1536"`

1709 

1710 - `"1536x1024"`

1711 

1712 - `"auto"`

1713 

1714 - `local_shell: object { type }`

1715 

1716 A tool that allows the model to execute shell commands in a local environment.

1717 

1718 - `function_shell_tool: object { type, environment }`

1719 

1720 A tool that allows the model to execute shell commands.

1721 

1722 - `type: "shell"`

1723 

1724 The type of the shell tool. Always `shell`.

1725 

1726 - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference`

1727 

1728 - `container_auto: object { type, file_ids, memory_limit, 2 more }`

1729 

1730 - `type: "container_auto"`

1731 

1732 Automatically creates a container for this request

1733 

1734 - `file_ids: optional array of string`

1735 

1736 An optional list of uploaded files to make available to your code.

1737 

1738 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

1739 

1740 The memory limit for the container.

1741 

1742 - `"1g"`

1743 

1744 - `"4g"`

1745 

1746 - `"16g"`

1747 

1748 - `"64g"`

1749 

1750 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1751 

1752 Network access policy for the container.

1753 

1754 - `container_network_policy_disabled: object { type }`

1755 

1756 - `container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }`

1757 

1758 - `skills: optional array of SkillReference or InlineSkill`

1759 

1760 An optional list of skills referenced by id or inline data.

1761 

1762 - `skill_reference: object { skill_id, type, version }`

1763 

1764 - `skill_id: string`

1765 

1766 The ID of the referenced skill.

1767 

1768 - `type: "skill_reference"`

1769 

1770 References a skill created with the /v1/skills endpoint.

1771 

1772 - `version: optional string`

1773 

1774 Optional skill version. Use a positive integer or 'latest'. Omit for default.

1775 

1776 - `inline_skill: object { description, name, source, type }`

1777 

1778 - `description: string`

1779 

1780 The description of the skill.

1781 

1782 - `name: string`

1783 

1784 The name of the skill.

1785 

1786 - `source: object { data, media_type, type }`

1787 

1788 Inline skill payload

1789 

1790 - `data: string`

1791 

1792 Base64-encoded skill zip bundle.

1793 

1794 - `media_type: "application/zip"`

1795 

1796 The media type of the inline skill payload. Must be `application/zip`.

1797 

1798 - `type: "base64"`

1799 

1800 The type of the inline skill source. Must be `base64`.

1801 

1802 - `type: "inline"`

1803 

1804 Defines an inline skill for this request.

1805 

1806 - `local_environment: object { type, skills }`

1807 

1808 - `type: "local"`

1809 

1810 Use a local computer environment.

1811 

1812 - `skills: optional array of LocalSkill`

1813 

1814 An optional list of skills.

1815 

1816 - `description: string`

1817 

1818 The description of the skill.

1819 

1820 - `name: string`

1821 

1822 The name of the skill.

1823 

1824 - `path: string`

1825 

1826 The path to the directory containing the skill.

1827 

1828 - `container_reference: object { container_id, type }`

1829 

1830 - `container_id: string`

1831 

1832 The ID of the referenced container.

1833 

1834 - `type: "container_reference"`

1835 

1836 References a container created with the /v1/containers endpoint

1837 

1838 - `custom_tool: object { name, type, defer_loading, 2 more }`

1839 

1840 A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)

1841 

1842 - `name: string`

1843 

1844 The name of the custom tool, used to identify it in tool calls.

1845 

1846 - `type: "custom"`

1847 

1848 The type of the custom tool. Always `custom`.

1849 

1850 - `defer_loading: optional boolean`

1851 

1852 Whether this tool should be deferred and discovered via tool search.

1853 

1854 - `description: optional string`

1855 

1856 Optional description of the custom tool, used to provide more context.

1857 

1858 - `format: optional object { type } or object { definition, syntax, type }`

1859 

1860 The input format for the custom tool. Default is unconstrained text.

1861 

1862 - `text: object { type }`

1863 

1864 Unconstrained free-form text.

1865 

1866 - `grammar: object { definition, syntax, type }`

1867 

1868 A grammar defined by the user.

1869 

1870 - `definition: string`

1871 

1872 The grammar definition.

1873 

1874 - `syntax: "lark" or "regex"`

1875 

1876 The syntax of the grammar definition. One of `lark` or `regex`.

1877 

1878 - `"lark"`

1879 

1880 - `"regex"`

1881 

1882 - `type: "grammar"`

1883 

1884 Grammar format. Always `grammar`.

1885 

1886 - `namespace_tool: object { description, name, tools, type }`

1887 

1888 Groups function/custom tools under a shared namespace.

1889 

1890 - `description: string`

1891 

1892 A description of the namespace shown to the model.

1893 

1894 - `name: string`

1895 

1896 The namespace name used in tool calls (for example, `crm`).

1897 

1898 - `tools: array of object { name, type, defer_loading, 3 more } or CustomTool`

1899 

1900 The function/custom tools available inside this namespace.

1901 

1902 - `function: object { name, type, defer_loading, 3 more }`

1903 

1904 - `name: string`

1905 

1906 - `type: "function"`

1907 

1908 - `defer_loading: optional boolean`

1909 

1910 Whether this function should be deferred and discovered via tool search.

1911 

1912 - `description: optional string`

1913 

1914 - `parameters: optional unknown`

1915 

1916 - `strict: optional boolean`

1917 

1918 - `custom_tool: object { name, type, defer_loading, 2 more }`

1919 

1920 A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)

1921 

1922 - `name: string`

1923 

1924 The name of the custom tool, used to identify it in tool calls.

1925 

1926 - `type: "custom"`

1927 

1928 The type of the custom tool. Always `custom`.

1929 

1930 - `defer_loading: optional boolean`

1931 

1932 Whether this tool should be deferred and discovered via tool search.

1933 

1934 - `description: optional string`

1935 

1936 Optional description of the custom tool, used to provide more context.

1937 

1938 - `format: optional object { type } or object { definition, syntax, type }`

1939 

1940 The input format for the custom tool. Default is unconstrained text.

1941 

1942 - `type: "namespace"`

1943 

1944 The type of the tool. Always `namespace`.

1945 

1946 - `tool_search_tool: object { type, description, execution, parameters }`

1947 

1948 Hosted or BYOT tool search configuration for deferred tools.

1949 

1950 - `type: "tool_search"`

1951 

1952 The type of the tool. Always `tool_search`.

1953 

1954 - `description: optional string`

1955 

1956 Description shown to the model for a client-executed tool search tool.

1957 

1958 - `execution: optional "server" or "client"`

1959 

1960 Whether tool search is executed by the server or by the client.

1961 

1962 - `"server"`

1963 

1964 - `"client"`

1965 

1966 - `parameters: optional unknown`

1967 

1968 Parameter schema for a client-executed tool search tool.

1969 

1970 - `web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }`

1971 

1972 This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

1973 

1974 - `type: "web_search_preview" or "web_search_preview_2025_03_11"`

1975 

1976 The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.

1977 

1978 - `"web_search_preview"`

1979 

1980 - `"web_search_preview_2025_03_11"`

1981 

1982 - `search_content_types: optional array of "text" or "image"`

1983 

1984 - `"text"`

1985 

1986 - `"image"`

1987 

1988 - `search_context_size: optional "low" or "medium" or "high"`

1989 

1990 High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.

1991 

1992 - `"low"`

1993 

1994 - `"medium"`

1995 

1996 - `"high"`