OpenAI Conversations API
Manage conversations and conversation items.
OpenAI Conversations API is one of 51 APIs that OpenAI publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 2 JSON Schema definitions.
Tagged areas include Conversations. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, a JSON-LD context, and 2 JSON Schemas.
This API exposes 8 operations across 4 paths, and defines 184 schemas. It is described by OpenAPI 3.0.0, at version 2.0.0.
Requests are made against a single base URL, https://api.openai.com/v1.
8 operations
4 paths
184 schemas
2 DELETE3 GET3 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
OpenAI Conversations API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (ApiKeyAuth).
By default, every request must be authenticated.
Paths & Operations 8
Across 4 paths, the API surfaces 8 operations — 2 DELETE, 3 GET, 3 POST. Each is listed below with its method, path, parameters, and response codes.
Conversations 8
Manage conversations and conversation items.
POST
/conversations/{conversation_id}/items
Create items in a conversation with the given ID.
GET
/conversations/{conversation_id}/items
List all items for a conversation with the given ID.
GET
/conversations/{conversation_id}/items/{item_id}
Get a single item from a conversation with the given IDs.
DELETE
/conversations/{conversation_id}/items/{item_id}
Delete an item from a conversation with the given IDs.
POST
/conversations
Create a conversation.
GET
/conversations/{conversation_id}
Get a conversation
DELETE
/conversations/{conversation_id}
Delete a conversation. Items in the conversation will not be deleted.
POST
/conversations/{conversation_id}
Update a conversation
Schemas 184
The contract defines 184 schemas that model the data the API accepts and returns. The most detailed are ImageGenTool (12 properties), MCPTool (10 properties), MCPToolCall (9 properties), FunctionShellCall (7 properties). Each schema is shown below with its type and property counts.
Annotation
An annotation that applies to a span of output text.
ApplyPatchUpdateFileOperation
object
Instruction describing how to update a file via the applypatch tool.
3 properties
3 required
ConversationItem
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/objectrespo…
FileCitationBody
object
A citation to a file.
4 properties
4 required
FunctionShellCallOutputContentParam
object
Captured stdout and stderr for a portion of a shell tool call output.
3 properties
3 required
FileSearchToolCall
object
The results of a file search tool call. See the [file search guide](/docs/guides/tools-file-search) for more information.
5 properties
4 required
WebSearchTool
object
Search the Internet for sources related to the prompt. Learn more about the [web search tool](/docs/guides/tools-web-search).
4 properties
1 required
WebSearchActionSearch
object
Action type "search" - Performs a web search query.
4 properties
2 required
InlineSkillParam
object
4 properties
4 required
FunctionShellCallOutput
object
The output of a shell tool call that was emitted.
7 properties
6 required
ImageGenActionEnum
string
FunctionShellCall
object
A tool call that executes one or more shell commands in a managed environment.
7 properties
6 required
CustomToolCall
object
A call to a custom tool created by the model.
6 properties
4 required
FileInputDetail
string
CodeInterpreterOutputLogs
object
The logs output from the code interpreter.
2 properties
2 required
ReasoningTextContent
object
Reasoning text from the model.
2 properties
2 required
DeletedConversationResource
object
3 properties
3 required
Item
object
Content item used to generate a response.
ToolSearchOutputItemParam
object
6 properties
2 required
SearchContentType
string
OutputMessage
object
An output message from the model.
6 properties
5 required
ComputerCallSafetyCheckParam
object
A pending safety check for the computer call.
3 properties
1 required
FunctionCallItemStatus
string
TypeParam
object
An action to type in text.
2 properties
2 required
KeyPressAction
object
A collection of keypresses the model would like to perform.
2 properties
2 required
ToolSearchToolParam
object
Hosted or BYOT tool search configuration for deferred tools.
4 properties
1 required
ComputerAction
ReasoningItem
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…
6 properties
3 required
CodeInterpreterOutputImage
object
The image output from the code interpreter.
2 properties
2 required
FunctionCallOutputStatusEnum
string
GrammarSyntax1
string
ImageGenToolCall
object
An image generation request made by the model.
4 properties
4 required
Filters
ComputerToolCall
object
A tool call to a computer use tool. See the [computer use guide](/docs/guides/tools-computer-use) for more information.
7 properties
5 required
WebSearchActionFind
object
Action type "findinpage": Searches for a pattern within a loaded page.
3 properties
3 required
WebSearchActionOpenPage
object
Action type "openpage" - Opens a specific URL from search results.
2 properties
1 required
FunctionShellCallItemStatus
string
Status values reported for shell tool calls.
MessageRole
string
ContainerNetworkPolicyDisabledParam
object
1 property
1 required
ComputerActionList
array
Flattened batched actions for computeruse. Each action includes an type discriminator and action-specific fields.
ContainerAutoParam
object
5 properties
1 required
RankerVersionType
string
ToolSearchOutput
object
7 properties
6 required
OutputMessageContent
CreateConversationBody
object
2 properties
MessagePhase
string
Labels an assistant message as intermediate commentary (commentary) or the final answer (finalanswer). For models like gpt-5.3-codex and beyond, when sending f…
CoordParam
object
An x/y coordinate pair, e.g. { x: 100, y: 200 }.
2 properties
2 required
CustomToolCallOutput
object
The output of a custom tool call from your code, being sent back to the model.
4 properties
3 required
ApplyPatchCreateFileOperation
object
Instruction describing how to create a file via the applypatch tool.
3 properties
3 required
MCPListToolsTool
object
A tool available on an MCP server.
4 properties
2 required
ComputerScreenshotImage
object
A computer screenshot image used with the computer use tool.
3 properties
1 required
FunctionToolCallOutput
object
The output of a function tool call.
5 properties
3 required
EmptyModelParam
object
InputMessageContentList
array
A list of one or many input items to the model, containing different content types.
ComputerUsePreviewTool
object
A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
4 properties
4 required
DoubleClickAction
object
A double click action.
4 properties
4 required
InlineSkillSourceParam
object
Inline skill payload
3 properties
3 required
ApplyPatchToolParam
object
Allows the assistant to create, delete, or update files using unified diffs.
1 property
1 required
ContainerFileCitationBody
object
A citation for a container file used to generate a model response.
6 properties
6 required
FileDetailEnum
string
ComparisonFilter
object
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
3 properties
3 required
ToolSearchCall
object
7 properties
6 required
LocalSkillParam
object
3 properties
3 required
LogProb
object
The log probability of a token.
4 properties
4 required
ContainerReferenceResource
object
Represents a container created with /v1/containers.
2 properties
2 required
ComputerCallOutputItemParam
object
The output of a computer tool call.
6 properties
3 required
InputMessage
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…
4 properties
2 required
ApplyPatchCallOutputStatusParam
string
Outcome values reported for applypatch tool call outputs.
ApplyPatchToolCallOutputItemParam
object
The streamed output emitted by an apply patch tool call.
5 properties
3 required
ComputerEnvironment
string
FunctionShellCallItemParam
object
A tool representing a request to execute one or more shell commands.
6 properties
3 required
ContainerNetworkPolicyAllowlistParam
object
3 properties
2 required
FunctionShellActionParam
object
Commands and limits describing how to run the shell tool call.
3 properties
1 required
FunctionToolCall
object
A tool call to run a function. See the [function calling guide](/docs/guides/function-calling) for more information.
7 properties
4 required
ClickButtonType
string
CompactionBody
object
A compaction item generated by the [v1/responses/compact API](/docs/api-reference/responses/compact).
4 properties
3 required
MCPToolFilter
object
A filter object to specify which tools are allowed.
2 properties
ComputerToolCallOutput
object
The output of a computer tool call.
6 properties
3 required
NamespaceToolParam
object
Groups function/custom tools under a shared namespace.
4 properties
4 required
FunctionShellAction
object
Execute a shell command.
3 properties
3 required
EasyInputMessage
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…
4 properties
2 required
MoveParam
object
A mouse move action.
4 properties
3 required
FunctionShellCallOutputExitOutcome
object
Indicates that the shell commands finished and returned an exit code.
2 properties
2 required
FunctionShellCallOutputItemParam
object
The streamed output items emitted by a shell tool call.
6 properties
3 required
FunctionShellCallStatus
string
CodeInterpreterToolCall
object
A tool call to run code.
6 properties
6 required
FunctionAndCustomToolCallOutput
Tool
A tool that can be used to generate a response.
LocalShellToolParam
object
A tool that allows the model to execute shell commands in a local environment.
1 property
1 required
InputImageContentParamAutoParam
object
An image input to the model. Learn about [image inputs](/docs/guides/vision)
4 properties
1 required
RefusalContent
object
A refusal from the model.
2 properties
2 required
ApplyPatchCallStatus
string
SummaryTextContent
object
A summary text from the model.
2 properties
2 required
ScrollParam
object
A scroll action.
6 properties
5 required
CustomTextFormatParam
object
Unconstrained free-form text.
1 property
1 required
MCPTool
object
Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp).
10 properties
2 required
ApplyPatchOperationParam
One of the createfile, deletefile, or updatefile operations supplied to the applypatch tool.
InputImageContent
object
An image input to the model. Learn about [image inputs](/docs/guides/vision).
4 properties
2 required
LocalEnvironmentParam
object
2 properties
1 required
SearchContextSize
string
ApproximateLocation
object
5 properties
1 required
ItemReferenceParam
object
An internal identifier for an item to reference.
2 properties
1 required
CompactionSummaryItemParam
object
A compaction item generated by the [v1/responses/compact API](/docs/api-reference/responses/compact).
3 properties
2 required
WebSearchToolCall
object
The results of a web search tool call. See the [web search guide](/docs/guides/tools-web-search) for more information.
4 properties
4 required
LocalEnvironmentResource
object
Represents the use of a local environment to perform shell actions.
1 property
1 required
InputTextContent
object
A text input to the model.
2 properties
2 required
UrlCitationBody
object
A citation for a web resource used to generate a model response.
5 properties
5 required
MCPApprovalResponseResource
object
A response to an MCP approval request.
5 properties
5 required
InputItem
ApplyPatchDeleteFileOperation
object
Instruction describing how to delete a file via the applypatch tool.
2 properties
2 required
MCPListTools
object
A list of tools available on an MCP server.
5 properties
4 required
RankingOptions
object
3 properties
FunctionShellCallOutputExitOutcomeParam
object
Indicates that the shell commands finished and returned an exit code.
2 properties
2 required
FileSearchTool
object
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-searc…
5 properties
2 required
FunctionCallOutputItemParam
object
The output of a function tool call.
5 properties
3 required
LocalShellToolCallOutput
object
The output of a local shell tool call.
4 properties
4 required
ApplyPatchCreateFileOperationParam
object
Instruction for creating a new file via the applypatch tool.
3 properties
3 required
ContainerMemoryLimit
string
FunctionShellToolParam
object
A tool that allows the model to execute shell commands.
2 properties
1 required
ToolSearchCallItemParam
object
6 properties
2 required
SkillReferenceParam
object
3 properties
2 required
InputContent
FunctionShellCallOutputStatusEnum
string
WebSearchPreviewTool
object
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-…
4 properties
1 required
ApplyPatchToolCallItemParam
object
A tool call representing a request to create, delete, or update files using diff patches.
5 properties
4 required
DragParam
object
A drag action.
3 properties
2 required
CompoundFilter
object
Combine multiple filters using and or or.
2 properties
2 required
CodeInterpreterTool
object
A tool that runs Python code to help generate a response to a prompt.
2 properties
2 required
ComputerTool
object
A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
1 property
1 required
ApplyPatchUpdateFileOperationParam
object
Instruction for updating an existing file via the applypatch tool.
3 properties
3 required
MessageStatus
string
AutoCodeInterpreterToolParam
object
Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
4 properties
1 required
ConversationResource
object
4 properties
4 required
CustomToolParam
object
A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-callingcustom-tools)
5 properties
2 required
MCPApprovalRequest
object
A request for human approval of a tool invocation.
5 properties
5 required
FunctionToolCallResource
FunctionTool
object
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).
6 properties
4 required
ContainerNetworkPolicyDomainSecretParam
object
3 properties
3 required
FunctionShellCallOutputTimeoutOutcome
object
Indicates that the shell call exceeded its configured time limit.
1 property
1 required
InputFileContent
object
A file input to the model.
6 properties
1 required
HybridSearchOptions
object
2 properties
2 required
LocalShellExecAction
object
Execute a shell command on the server.
6 properties
3 required
LocalShellToolCall
object
A tool call to run a command on the local shell.
5 properties
5 required
FunctionCallStatus
string
DetailEnum
string
FunctionShellCallOutputTimeoutOutcomeParam
object
Indicates that the shell call exceeded its configured time limit.
1 property
1 required
FunctionShellCallOutputOutcomeParam
The exit or timeout outcome associated with this shell call.
ClickParam
object
A click action.
5 properties
4 required
InputTextContentParam
object
A text input to the model.
2 properties
2 required
OutputTextContent
object
A text output from the model.
4 properties
4 required
ApplyPatchCallOutputStatus
string
ConversationItemList
object
A list of Conversation items.
5 properties
5 required
MCPApprovalResponse
object
A response to an MCP approval request.
5 properties
4 required
ApplyPatchToolCallOutput
object
The output emitted by an apply patch tool call.
6 properties
4 required
FunctionToolCallOutputResource
FunctionShellCallOutputContent
object
The content of a shell tool call output that was emitted.
4 properties
3 required
InputFileContentParam
object
A file input to the model.
6 properties
1 required
TopLogProb
object
The top log probability of a token.
3 properties
3 required
ToolSearchExecutionType
string
VectorStoreFileAttributes
MCPToolCallStatus
string
Message
object
A message to or from the model.
6 properties
5 required
MCPToolCall
object
An invocation of a tool on an MCP server.
9 properties
5 required
ComputerToolCallOutputResource
ComputerCallOutputStatus
string
FilePath
object
A path to a file.
3 properties
3 required
FunctionToolParam
object
6 properties
2 required
Metadata
WaitParam
object
A wait action.
1 property
1 required
InputFidelity
string
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…
ComputerScreenshotContent
object
A screenshot of a computer.
4 properties
4 required
ApplyPatchToolCall
object
A tool call that applies file diffs by creating, deleting, or updating files.
6 properties
5 required
ImageDetail
string
WebSearchApproximateLocation
UpdateConversationBody
object
1 property
1 required
IncludeEnum
string
Specify additional output data to include in the model response. Currently supported values are: - websearchcall.results: Include the search results of the web…
ScreenshotParam
object
A screenshot action.
1 property
1 required
ApplyPatchDeleteFileOperationParam
object
Instruction for deleting an existing file via the applypatch tool.
2 properties
2 required
ContainerReferenceParam
object
2 properties
2 required
MessagePhase-2
string
TextContent
object
A text content.
2 properties
2 required
ApplyPatchCallStatusParam
string
Status values reported for applypatch tool calls.
CustomGrammarFormatParam
object
A grammar defined by the user.
3 properties
3 required
ImageGenTool
object
A tool that generates images using the GPT image models.
12 properties
1 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from OpenAI 12
Other APIs OpenAI publishes across the network.
OpenAI Responses API
OpenAI Moderations API
OpenAI Batch API
OpenAI Vector Stores API
OpenAI Uploads API
OpenAI Realtime API
OpenAI Evals API
OpenAI Videos API
OpenAI Containers API
OpenAI ChatKit API
OpenAI Skills API
OpenAI Agents SDK
#Conversations
Where this information came from
This is an independent, third-party profile of OpenAI Conversations API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.