Conversations
Create conversation items
POST
/openai/v1/conversations/{conversation_id}/itemsAdds one or more items to the specified conversation.
Path ParametersQuery ParametersHeader Parameters
conversation_idstringrequired
The id of the conversation on which the item needs to be created.includearrayoptional
Additional fields to include in the response.
See the `include` parameter for listing Conversation items for more information.x-ms-user-isolation-keystringoptional
Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user.Request BodyContent-Type: application/json
items(message | output_message | file_search_call | computer_call | computer_call_output | web_search_call | function_call | function_call_output | tool_search_call | tool_search_output | reasoning | compaction | image_generation_call | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call_output | custom_tool_call)[]required
The items to add to the conversation. You may add up to 20 items at a time.One of the following:
messageOpenAI.ItemInputMessage
A message input to the model with a role indicating instruction following
hierarchy. Instructions given with the `developer` or `system` role take
precedence over instructions given with the `user` role.output_messageOpenAI.ItemOutputMessage
An output message from the model.file_search_callOpenAI.ItemFileSearchToolCall
The results of a file search tool call. See the
[file search guide](/docs/guides/tools-file-search) for more information.computer_callOpenAI.ItemComputerToolCall
A tool call to a computer use tool. See the
[computer use guide](/docs/guides/tools-computer-use) for more information.computer_call_outputOpenAI.ItemComputerCallOutputItemParam
The output of a computer tool call.web_search_callOpenAI.ItemWebSearchToolCall
The results of a web search tool call. See the
[web search guide](/docs/guides/tools-web-search) for more information.function_callOpenAI.ItemFunctionToolCall
A tool call to run a function. See the
[function calling guide](/docs/guides/function-calling) for more information.function_call_outputOpenAI.ItemFunctionCallOutputItemParam
The output of a function tool call.tool_search_callOpenAI.ItemToolSearchCallItemParam
Content item used to generate a response.tool_search_outputOpenAI.ItemToolSearchOutputItemParam
Content item used to generate a response.reasoningOpenAI.ItemReasoningItem
A description of the chain of thought used by a reasoning model while generating
a response. Be sure to include these items in your `input` to the Responses API
for subsequent turns of a conversation if you are manually
[managing context](/docs/guides/conversation-state).compactionOpenAI.ItemCompactionSummaryItemParam
A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact).image_generation_callOpenAI.ItemImageGenToolCall
An image generation request made by the model.code_interpreter_callOpenAI.ItemCodeInterpreterToolCall
A tool call to run code.local_shell_callOpenAI.ItemLocalShellToolCall
A tool call to run a command on the local shell.local_shell_call_outputOpenAI.ItemLocalShellToolCallOutput
The output of a local shell tool call.shell_callOpenAI.ItemFunctionShellCallItemParam
A tool representing a request to execute one or more shell commands.shell_call_outputOpenAI.ItemFunctionShellCallOutputItemParam
The streamed output items emitted by a shell tool call.apply_patch_callOpenAI.ItemApplyPatchToolCallItemParam
A tool call representing a request to create, delete, or update files using diff patches.apply_patch_call_outputOpenAI.ItemApplyPatchToolCallOutputItemParam
The streamed output emitted by an apply patch tool call.mcp_list_toolsOpenAI.ItemMcpListTools
A list of tools available on an MCP server.mcp_approval_requestOpenAI.ItemMcpApprovalRequest
A request for human approval of a tool invocation.mcp_approval_responseOpenAI.ItemMcpApprovalResponse
A response to an MCP approval request.mcp_callOpenAI.ItemMcpToolCall
An invocation of a tool on an MCP server.custom_tool_call_outputOpenAI.ItemCustomToolCallOutput
The output of a custom tool call from your code, being sent back to the model.custom_tool_callOpenAI.ItemCustomToolCall
A call to a custom tool created by the model.Responses
objectenumrequired
The type of object returned, must be `list`.list
data(message | function_call | function_call_output | file_search_call | web_search_call | image_generation_call | computer_call | computer_call_output | tool_search_call | tool_search_output | reasoning | compaction | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call | custom_tool_call_output)[]required
A list of conversation items.One of the following:
messageOpenAI.ConversationItemMessage
A message to or from the model.function_callOpenAI.ConversationItemFunctionToolCall
A tool call to run a function. See the
[function calling guide](/docs/guides/function-calling) for more information.function_call_outputOpenAI.ConversationItemFunctionToolCallOutput
The output of a function tool call.file_search_callOpenAI.ConversationItemFileSearchToolCall
The results of a file search tool call. See the
[file search guide](/docs/guides/tools-file-search) for more information.web_search_callOpenAI.ConversationItemWebSearchToolCall
The results of a web search tool call. See the
[web search guide](/docs/guides/tools-web-search) for more information.image_generation_callOpenAI.ConversationItemImageGenToolCall
An image generation request made by the model.computer_callOpenAI.ConversationItemComputerToolCall
A tool call to a computer use tool. See the
[computer use guide](/docs/guides/tools-computer-use) for more information.computer_call_outputOpenAI.ConversationItemComputerToolCallOutput
The output of a computer tool call.tool_search_callOpenAI.ConversationItemToolSearchCall
A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output).tool_search_outputOpenAI.ConversationItemToolSearchOutput
A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output).reasoningOpenAI.ConversationItemReasoningItem
A description of the chain of thought used by a reasoning model while generating
a response. Be sure to include these items in your `input` to the Responses API
for subsequent turns of a conversation if you are manually
[managing context](/docs/guides/conversation-state).compactionOpenAI.ConversationItemCompactionBody
A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact).code_interpreter_callOpenAI.ConversationItemCodeInterpreterToolCall
A tool call to run code.local_shell_callOpenAI.ConversationItemLocalShellToolCall
A tool call to run a command on the local shell.local_shell_call_outputOpenAI.ConversationItemLocalShellToolCallOutput
The output of a local shell tool call.shell_callOpenAI.ConversationItemFunctionShellCall
A tool call that executes one or more shell commands in a managed environment.shell_call_outputOpenAI.ConversationItemFunctionShellCallOutput
The output of a shell tool call that was emitted.apply_patch_callOpenAI.ConversationItemApplyPatchToolCall
A tool call that applies file diffs by creating, deleting, or updating files.apply_patch_call_outputOpenAI.ConversationItemApplyPatchToolCallOutput
The output emitted by an apply patch tool call.mcp_list_toolsOpenAI.ConversationItemMcpListTools
A list of tools available on an MCP server.mcp_approval_requestOpenAI.ConversationItemMcpApprovalRequest
A request for human approval of a tool invocation.mcp_approval_responseOpenAI.ConversationItemMcpApprovalResponseResource
A response to an MCP approval request.mcp_callOpenAI.ConversationItemMcpToolCall
An invocation of a tool on an MCP server.custom_tool_callOpenAI.ConversationItemCustomToolCallResource
A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output).custom_tool_call_outputOpenAI.ConversationItemCustomToolCallOutputResource
A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output).has_morebooleanrequired
Whether there are more items available.first_idstringrequired
The ID of the first item in the list.last_idstringrequired
The ID of the last item in the list.