--- title: "Create a conversation" method: POST path: "/conversations" tags: ["Conversations"] --- # Create a conversation `POST /conversations` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/conversations` - Auth: HTTP bearer Create a conversation. ## Request body - CreateConversationBody - `metadata` Metadata, nullable: Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - `items` InputItem[], nullable: Initial items to include in the conversation context. You may add up to 20 items at a time. - union - EasyInputMessage: 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. Messages with the `assistant` role are presumed to have been generated by the model in previous interactions. - `role` 'user' | 'assistant' | 'system' | 'developer', required: The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `content` union, required: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - string: A text input to the model. - InputContent[]: A list of one or many input items to the model, containing different content types. - union - … - `phase` 'commentary' | 'final_answer': Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `type` 'message': The type of the message input. Always `message`. - union: Content item used to generate a response. - object: 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. - `type` 'message': The type of the message input. Always set to `message`. - `role` 'user' | 'system' | 'developer', required: The role of the message input. One of `user`, `system`, or `developer`. - `status` 'in_progress' | 'completed' | 'incomplete': The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `content` InputContent[], required: A list of one or many input items to the model, containing different content types. - union - … - object: An output message from the model. - `id` string, required: The unique ID of the output message. - `type` 'message', required: The type of the output message. Always `message`. - `role` 'assistant', required: The role of the output message. Always `assistant`. - `content` OutputMessageContent[], required: The content of the output message. - union - … - `phase` 'commentary' | 'final_answer': Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `status` 'in_progress' | 'completed' | 'incomplete', required: The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - object: The results of a file search tool call. See the [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information. - `id` string, required: The unique ID of the file search tool call. - `type` 'file_search_call', required: The type of the file search tool call. Always `file_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required: The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `queries` string[], required: The queries used to search for files. - `results` object[], nullable: The results of the file search tool call. - `file_id` string: The unique ID of the file. - `text` string: The text that was retrieved from the file. - `filename` string: The name of the file. - `attributes` VectorStoreFileAttributes, nullable: Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers. - `score` number, float: The relevance score of the file - a value between 0 and 1. - object: A tool call to a computer use tool. See the [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information. - `type` 'computer_call', required: The type of the computer call. Always `computer_call`. - `id` string, required: The unique ID of the computer call. - `call_id` string, required: An identifier used when responding to the tool call with output. - `action` union - ClickParam: A click action. - … - DoubleClickAction: A double click action. - … - DragParam: A drag action. - … - KeyPressAction: A collection of keypresses the model would like to perform. - … - MoveParam: A mouse move action. - … - ScreenshotParam: A screenshot action. - … - ScrollParam: A scroll action. - … - TypeParam: An action to type in text. - … - WaitParam: A wait action. - … - `actions` ComputerAction[]: Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - union - … - `pending_safety_checks` ComputerCallSafetyCheckParam[], required: The pending safety checks for the computer call. - `id` string, required: The ID of the pending safety check. - `code` string, nullable: The type of the pending safety check. - `message` string, nullable: Details about the pending safety check. - `status` 'in_progress' | 'completed' | 'incomplete', required: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object: The output of a computer tool call. - `id` string, nullable: The ID of the computer tool call output. - `call_id` string, required: The ID of the computer tool call that produced the output. - `type` 'computer_call_output', required: The type of the computer tool call output. Always `computer_call_output`. - `output` ComputerScreenshotImage, required: A computer screenshot image used with the computer use tool. - `type` 'computer_screenshot', required: Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `image_url` string, uri: The URL of the screenshot image. - `file_id` string: The identifier of an uploaded file that contains the screenshot. - `acknowledged_safety_checks` ComputerCallSafetyCheckParam[], nullable: The safety checks reported by the API that have been acknowledged by the developer. - `id` string, required: The ID of the pending safety check. - `code` string, nullable: The type of the pending safety check. - `message` string, nullable: Details about the pending safety check. - `status` 'in_progress' | 'completed' | 'incomplete' - object: The results of a web search tool call. See the [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information. - `id` string, required: The unique ID of the web search tool call. - `type` 'web_search_call', required: The type of the web search tool call. Always `web_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'failed' | 'incomplete', required - `action` union: An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - object: Action type "search" - Performs a web search query. - … - object: Action type "open_page" - Opens a specific URL from search results. - … - object: Action type "find_in_page": Searches for a pattern within a loaded page. - … - object: A tool call to run a function. See the [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information. - `id` string: The unique ID of the function tool call. - `type` 'function_call', required: The type of the function tool call. Always `function_call`. - `call_id` string, required: The unique ID of the function tool call generated by the model. - `caller` union: The execution context that produced this tool call. - DirectToolCallCaller - … - ProgramToolCallCaller - … - `namespace` string: The namespace of the function to run. - `name` string, required: The name of the function to run. - `arguments` string, required: A JSON string of the arguments to pass to the function. - `status` 'in_progress' | 'completed' | 'incomplete': The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `async` boolean: Whether the function tool call runs asynchronously. - object: The output of a function tool call. - `id` string, nullable: The unique ID of the function tool call output. Populated when this item is returned via API. - `call_id` string, nullable: The unique ID of the function tool call generated by the model. - `type` 'function_call_output', required: The type of the function tool call output. Always `function_call_output`. - `output` union, required: Text, image, or file output of the function tool call. - string: A JSON string of the output of the function tool call. - union[]: An array of content outputs (text, image, file) for the function tool call. - … - `name` string, nullable: The name of the tool that produced the output. - `namespace` string, nullable: The namespace of the tool that produced the output. - `caller` union: The execution context that produced this tool call. - DirectToolCallCallerParam - … - ProgramToolCallCallerParam - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable: The unique ID of this tool search call. - `call_id` string, nullable: The unique ID of the tool search call generated by the model. - `type` 'tool_search_call', required: The item type. Always `tool_search_call`. - `execution` 'server' | 'client' - `arguments` EmptyModelParam, required - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable: The unique ID of this tool search output. - `call_id` string, nullable: The unique ID of the tool search call generated by the model. - `type` 'tool_search_output', required: The item type. Always `tool_search_output`. - `execution` 'server' | 'client' - `tools` ToolSearchOutputTool[], required: The loaded tool definitions returned by the tool search output. - union: A tool definition returned by a tool search output. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable: The unique ID of this additional tools item. - `type` 'additional_tools', required: The item type. Always `additional_tools`. - `role` 'developer', required: The role that provided the additional tools. Only `developer` is supported. - `tools` Tool[], required: A list of additional tools made available at this item. - union: A tool that can be used to generate a response. - … - object: An update to the conversation's response configuration. The configuration remains in effect for subsequent responses until it is replaced by another configuration update. - `id` string, nullable: The unique ID of the configuration update item. - `type` 'configuration_update', required: The item type. Always `configuration_update`. - `reasoning` object: Updates to reasoning configuration. Only effort is supported. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Constrains effort on reasoning for reasoning models. Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not all reasoning models support every value. See the [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for model-specific support. - object: 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](https://developers.openai.com/api/docs/guides/conversation-state). - `type` 'reasoning', required: The type of the object. Always `reasoning`. - `id` string, required: The unique identifier of the reasoning content. - `encrypted_content` string, nullable: The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. When streaming, use the completed reasoning item and its `encrypted_content` from the `response.output_item.done` event in subsequent requests. The `encrypted_content` in `response.output_item.added` may be incomplete. This is especially important when `store` is `false` or when using Zero Data Retention. - `summary` SummaryTextContent[], required: Reasoning summary content. - `type` 'summary_text', required: The type of the object. Always `summary_text`. - `text` string, required: A summary of the reasoning output from the model so far. - `content` ReasoningTextContent[]: Reasoning text content. - `type` 'reasoning_text', required: The type of the reasoning text. Always `reasoning_text`. - `text` string, required: The reasoning text from the model. - `status` 'in_progress' | 'completed' | 'incomplete': The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). - `id` string, nullable: The ID of the compaction item. - `type` 'compaction', required: The type of the item. Always `compaction`. - `encrypted_content` string, required: The encrypted content of the compaction summary. - object: An image generation request made by the model. - `type` 'image_generation_call', required: The type of the image generation call. Always `image_generation_call`. - `id` string, required: The unique ID of the image generation call. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required: The status of the image generation call. - `result` string, nullable, required: The generated image encoded in base64. - `error` ImageGenToolCallError - `code` string, nullable, required: The error code. - `type` string, required: The error type. - `message` string, required: A description of the error. - `param` string, nullable, required: The related request parameter. - `moderation_details` ImageGenToolCallModerationDetails - … - `size` union - string - '1024x1024' | '1024x1536' | '1536x1024' - `quality` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto', nullable: The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. - `action` 'generate' | 'edit' | 'auto', nullable - `background` 'transparent' | 'opaque' | 'auto', nullable - `output_format` 'png' | 'webp' | 'jpeg', nullable - `revised_prompt` string, nullable: The prompt that was used after any model prompt rewriting. - object: A tool call to run code. - `type` 'code_interpreter_call', required: The type of the code interpreter tool call. Always `code_interpreter_call`. - `id` string, required: The unique ID of the code interpreter tool call. - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required: The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `container_id` string, required: The ID of the container used to run the code. - `code` string, nullable, required: The code to run, or null if not available. - `outputs` union[], nullable, required: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - union - … - object: A tool call to run a command on the local shell. - `type` 'local_shell_call', required: The type of the local shell call. Always `local_shell_call`. - `id` string, required: The unique ID of the local shell call. - `call_id` string, required: The unique ID of the local shell tool call generated by the model. - `action` LocalShellExecAction, required: Execute a shell command on the server. - `type` 'exec', required: The type of the local shell action. Always `exec`. - `command` string[], required: The command to run. - `timeout_ms` integer, nullable: Optional timeout in milliseconds for the command. - `working_directory` string, nullable: Optional working directory to run the command in. - `env` object, required: Environment variables to set for the command. - `user` string, nullable: Optional user to run the command as. - `status` 'in_progress' | 'completed' | 'incomplete', required: The status of the local shell call. - object: The output of a local shell tool call. - `type` 'local_shell_call_output', required: The type of the local shell tool call output. Always `local_shell_call_output`. - `id` string, required: The unique ID of the local shell tool call generated by the model. - `output` string, required: A JSON string of the output of the local shell tool call. - `status` 'in_progress' | 'completed' | 'incomplete', nullable: The status of the item. One of `in_progress`, `completed`, or `incomplete`. - object: A tool representing a request to execute one or more shell commands. - `id` string, nullable: The unique ID of the shell tool call. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the shell tool call generated by the model. - `caller` union: The execution context that produced this tool call. - DirectToolCallCallerParam - … - ProgramToolCallCallerParam - … - `type` 'shell_call', required: The type of the item. Always `shell_call`. - `action` FunctionShellActionParam, required: Commands and limits describing how to run the shell tool call. - `commands` string[], required: Ordered shell commands for the execution environment to run. - `timeout_ms` integer, nullable: Maximum wall-clock time in milliseconds to allow the shell commands to run. - `max_output_length` integer, nullable: Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `status` 'in_progress' | 'completed' | 'incomplete': Status values reported for shell tool calls. - `environment` union - LocalEnvironmentParam - … - ContainerReferenceParam - … - object: The streamed output items emitted by a shell tool call. - `id` string, nullable: The unique ID of the shell tool call output. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the shell tool call generated by the model. - `caller` union: The execution context that produced this tool call. - DirectToolCallCallerParam - … - ProgramToolCallCallerParam - … - `type` 'shell_call_output', required: The type of the item. Always `shell_call_output`. - `output` FunctionShellCallOutputContentParam[], required: Captured chunks of stdout and stderr output, along with their associated outcomes. - `stdout` string, required: Captured stdout output for the shell call. - `stderr` string, required: Captured stderr output for the shell call. - `outcome` union, required: The exit or timeout outcome associated with this shell call. - … - `status` 'in_progress' | 'completed' | 'incomplete': Status values reported for shell tool calls. - `max_output_length` integer, nullable: The maximum number of UTF-8 characters captured for this shell call's combined output. - object: A tool call representing a request to create, delete, or update files using diff patches. - `type` 'apply_patch_call', required: The type of the item. Always `apply_patch_call`. - `id` string, nullable: The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the apply patch tool call generated by the model. - `caller` union: The execution context that produced this tool call. - DirectToolCallCallerParam - … - ProgramToolCallCallerParam - … - `status` 'in_progress' | 'completed', required: Status values reported for apply_patch tool calls. - `operation` union, required: One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - ApplyPatchCreateFileOperationParam: Instruction for creating a new file via the apply_patch tool. - … - ApplyPatchDeleteFileOperationParam: Instruction for deleting an existing file via the apply_patch tool. - … - ApplyPatchUpdateFileOperationParam: Instruction for updating an existing file via the apply_patch tool. - … - object: The streamed output emitted by an apply patch tool call. - `type` 'apply_patch_call_output', required: The type of the item. Always `apply_patch_call_output`. - `id` string, nullable: The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the apply patch tool call generated by the model. - `caller` union: The execution context that produced this tool call. - DirectToolCallCallerParam - … - ProgramToolCallCallerParam - … - `status` 'completed' | 'failed', required: Outcome values reported for apply_patch tool call outputs. - `output` string, nullable: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - object: A list of tools available on an MCP server. - `type` 'mcp_list_tools', required: The type of the item. Always `mcp_list_tools`. - `id` string, required: The unique ID of the list. - `server_label` string, required: The label of the MCP server. - `tools` MCPListToolsTool[], required: The tools available on the server. - `name` string, required: The name of the tool. - `description` string, nullable: The description of the tool. - `input_schema` object, required: The JSON schema describing the tool's input. - `annotations` object, nullable: Additional annotations about the tool. - `error` string, nullable: Error message if the server could not list tools. - object: A request for human approval of a tool invocation. - `type` 'mcp_approval_request', required: The type of the item. Always `mcp_approval_request`. - `id` string, required: The unique ID of the approval request. - `server_label` string, required: The label of the MCP server making the request. - `name` string, required: The name of the tool to run. - `arguments` string, required: A JSON string of arguments for the tool. - object: A response to an MCP approval request. - `type` 'mcp_approval_response', required: The type of the item. Always `mcp_approval_response`. - `id` string, nullable: The unique ID of the approval response - `approval_request_id` string, required: The ID of the approval request being answered. - `approve` boolean, required: Whether the request was approved. - `reason` string, nullable: Optional reason for the decision. - object: An invocation of a tool on an MCP server. - `type` 'mcp_call', required: The type of the item. Always `mcp_call`. - `id` string, required: The unique ID of the tool call. - `server_label` string, required: The label of the MCP server running the tool. - `name` string, required: The name of the tool that was run. - `arguments` string, required: A JSON string of the arguments passed to the tool. - `output` string, nullable: The output from the tool call. - `error` union - MCPProtocolError - … - MCPToolExecutionError - … - HTTPError - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `approval_request_id` string, nullable: Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - object: The output of a custom tool call from your code, being sent back to the model. - `type` 'custom_tool_call_output', required: The type of the custom tool call output. Always `custom_tool_call_output`. - `id` string: The unique ID of the custom tool call output in the OpenAI platform. - `call_id` string, required: The call ID, used to map this custom tool call output to a custom tool call. - `caller` union: The execution context that produced this tool call. - DirectToolCallCallerParam - … - ProgramToolCallCallerParam - … - `output` union, required: The output from the custom tool call generated by your code. Can be a string or an list of output content. - string: A string of the output of the custom tool call. - FunctionAndCustomToolCallOutput[]: Text, image, or file output of the custom tool call. - … - object: A call to a custom tool created by the model. - `type` 'custom_tool_call', required: The type of the custom tool call. Always `custom_tool_call`. - `id` string: The unique ID of the custom tool call in the OpenAI platform. - `call_id` string, required: An identifier used to map this custom tool call to a tool call output. - `caller` union: The execution context that produced this tool call. - DirectToolCallCaller - … - ProgramToolCallCaller - … - `namespace` string: The namespace of the custom tool being called. - `name` string, required: The name of the custom tool being called. - `input` string, required: The input for the custom tool call generated by the model. - `async` boolean: Whether the custom tool call runs asynchronously. - CompactionTriggerItemParam: Compacts the current context. Must be the final input item. - `id` string, nullable: The unique ID of this compaction trigger. - `type` 'compaction_trigger', required: The type of the item. Always `compaction_trigger`. - ItemReferenceParam: An internal identifier for an item to reference. - `type` 'item_reference', nullable: The type of item to reference. Always `item_reference`. - `id` string, required: The ID of the item to reference. - ProgramItemParam - `id` string, required: The unique ID of this program item. - `type` 'program', required: The item type. Always `program`. - `call_id` string, required: The stable call ID of the program item. - `code` string, required: The JavaScript source executed by programmatic tool calling. - `fingerprint` string, required: Opaque program replay fingerprint that must be round-tripped. - ProgramOutputItemParam - `id` string, required: The unique ID of this program output item. - `type` 'program_output', required: The item type. Always `program_output`. - `call_id` string, required: The call ID of the program item. - `result` string, required: The result produced by the program item. - `status` 'completed' | 'incomplete', required ## Response `200` Success - ConversationResource - `id` string, required: The unique ID of the conversation. - `object` 'conversation', required: The object type, which is always `conversation`. - `metadata` object, required: Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - `created_at` integer, required: The time at which the conversation was created, measured in seconds since the Unix epoch. ## Other responses - `400`: The conversation input is invalid. - `429`: The request was rejected because a rate limit was exceeded. - `500`: The conversation update could not be finalized. ## Changes - **2026-10-26** `410e6429083a`: 9 info - added the new optional request property `items/anyOf[subschema #1]/items/oneOf[subschema #1: Input message]/content/oneOf[subschema #2: Input item content list]/items/oneOf[subschema #1: Input text]/prompt_cache_breakpoint/ttl` - added the new optional request property `items/anyOf[subschema #1]/items/oneOf[subschema #1: Input message]/content/oneOf[subschema #2: Input item content list]/items/oneOf[subschema #2: Input image]/prompt_cache_breakpoint/ttl` - added the new optional request property `items/anyOf[subschema #1]/items/oneOf[subschema #1: Input message]/content/oneOf[subschema #2: Input item content list]/items/oneOf[subschema #3: Input file]/prompt_cache_breakpoint/ttl` - added the new optional request property `items/anyOf[subschema #1]/items/oneOf[subschema #2: Item]/oneOf[subschema #1: Input message]/content/items/oneOf[subschema #1: Input text]/prompt_cache_breakpoint/ttl` - …5 more - **2026-10-23** `af780af62f70`: 2 info - the `` request property default value changed from `gpt-image-1` to `gpt-image-2` - the `` request property default value changed from `gpt-image-1` to `gpt-image-2` - …earlier changes not shown [Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/conversations/post.md) --- [API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)