Skip to main content
Microsoft Foundry
Start building
View as Markdown
Conversations

Create conversation items

POST
/openai/v1/conversations/{conversation_id}/items

Adds one or more items to the specified conversation.

Path Parameters
conversation_idstringrequired
The id of the conversation on which the item needs to be created.
Query Parameters
includearrayoptional
Additional fields to include in the response. See the include parameter for listing Conversation items for more information.
Header Parameters
x-ms-user-identitystringoptional
Opaque per-user identity string used to scope endpoint-scoped data to a specific end user. The caller must have the agents/endpoints/UserIdentityImpersonation/action RBAC permission.
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 | additional_tools | 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 for more information.
computer_callOpenAI.ItemComputerToolCall
A tool call to a computer use tool. See the computer use guide 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 for more information.
function_callOpenAI.ItemFunctionToolCall
A tool call to run a function. See the function calling guide 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.
additional_toolsOpenAI.ItemAdditionalToolsItemParam
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.
compactionOpenAI.ItemCompactionSummaryItemParam
A compaction item generated by the v1/responses/compact API.
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 | additional_tools | 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 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 for more information.
web_search_callOpenAI.ConversationItemWebSearchToolCall
The results of a web search tool call. See the web search guide 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 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.
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.
additional_toolsOpenAI.ConversationItemAdditionalTools
A single item within a conversation. The set of possible types are the same as the output type of a Response object.
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.
compactionOpenAI.ConversationItemCompactionBody
A compaction item generated by the v1/responses/compact API.
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.
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.
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.
View as Markdown
Request
curl https://api.openai.com/v1/conversations/conv_123/items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Hello!"}
        ]
      },
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "How are you?"}
        ]
      }
    ]
  }'
Response
{
  "object": "list",
  "data": [
    {
      "type": "message",
      "id": "msg_abc",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Hello!"}
      ]
    },
    {
      "type": "message",
      "id": "msg_def",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "How are you?"}
      ]
    }
  ],
  "first_id": "msg_abc",
  "last_id": "msg_def",
  "has_more": false
}