OpenAI Conversations API
Manage conversations and conversation items.
OpenAI Conversations API is one of 62 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 218 schemas. It is described by OpenAPI 3.2.0, at version 2.3.0.
Requests are made against a single base URL, https://api.openai.com/v1.
8 operations
4 paths
218 schemas
2 DELETE3 GET3 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
OpenAI Conversations API declares
2 security schemes
for authenticating requests.
It accepts HTTP bearer tokens (ApiKeyAuth).
It accepts HTTP bearer tokens (AdminApiKeyAuth).
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
GET
/conversations/{conversation_id}/items
List items
GET
/conversations/{conversation_id}/items/{item_id}
Retrieve an item
DELETE
/conversations/{conversation_id}/items/{item_id}
Delete an item
POST
/conversations
Create a conversation
GET
/conversations/{conversation_id}
Retrieve a conversation
DELETE
/conversations/{conversation_id}
Delete a conversation
POST
/conversations/{conversation_id}
Update a conversation
Schemas 218
The contract defines 218 schemas that model the data the API accepts and returns. The most detailed are MCPTool (12 properties), ImageGenTool (12 properties), ImageGenToolCall (10 properties), FunctionToolParam (9 properties). Each schema is shown below with its type and property counts.
FunctionCallItemStatus
string
InlineSkillSourceParam
object
Inline skill payload
3 properties
3 required
ToolSearchOutput
object
7 properties
6 required
FunctionShellCallOutputExitOutcomeParam
object
Indicates that the shell commands finished and returned an exit code.
2 properties
2 required
CustomToolParam
object
A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-callingcust…
7 properties
2 required
FunctionShellCallItemParam
object
A tool representing a request to execute one or more shell commands.
7 properties
3 required
DetailEnum
string
WebSearchActionSearch
object
Action type "search" - Performs a web search query.
4 properties
1 required
ComputerUsePreviewTool
object
A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).
4 properties
4 required
MessageRole
string
OutputMessage
object
An output message from the model.
6 properties
5 required
ContainerReferenceResource
object
Represents a container created with /v1/containers.
2 properties
2 required
ProgramOutputStatus
string
HybridSearchOptions
object
2 properties
2 required
FunctionCallOutputStatusEnum
string
FunctionShellCallOutputContent
object
The content of a shell tool call output that was emitted.
4 properties
3 required
CompactionTriggerItemParam
object
Compacts the current context. Must be the final input item.
2 properties
1 required
InlineSkillParam
object
4 properties
4 required
FunctionAndCustomToolCallOutput
ApplyPatchUpdateFileOperation
object
Instruction describing how to update a file via the applypatch tool.
3 properties
3 required
ImageGenToolCall
object
An image generation request made by the model.
10 properties
4 required
MessagePhase-2
string
ApplyPatchCallOutputStatus
string
DoubleClickAction
object
A double click action.
4 properties
4 required
ContainerMemoryLimit
string
ApplyPatchToolCallOutput
object
The output emitted by an apply patch tool call.
7 properties
4 required
InputMessageContentList
array
A list of one or many input items to the model, containing different content types.
CodeInterpreterOutputImage
object
The image output from the code interpreter.
2 properties
2 required
ComputerAction
Program
object
5 properties
5 required
FunctionTool
object
Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-ca…
9 properties
4 required
FunctionToolCall
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.
9 properties
4 required
ProgramToolCallCallerParam
object
2 properties
2 required
OutputMessageContent
ComputerCallOutputItemParam
object
The output of a computer tool call.
6 properties
3 required
MCPApprovalResponseResource
object
A response to an MCP approval request.
5 properties
5 required
ContainerReferenceParam
object
2 properties
2 required
ImageOutputFormat
string
ReasoningTextContent
object
Reasoning text from the model.
2 properties
2 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
ApplyPatchToolCallOutputItemParam
object
The streamed output emitted by an apply patch tool call.
6 properties
3 required
FunctionShellCallOutputContentParam
object
Captured stdout and stderr for a portion of a shell tool call output.
3 properties
3 required
WaitParam
object
A wait action.
1 property
1 required
FunctionToolParam
object
9 properties
2 required
MCPToolExecutionError
object
2 properties
2 required
InputFileContent
object
A file input to the model.
7 properties
1 required
ComputerToolCall
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.
7 properties
5 required
ApplyPatchCreateFileOperation
object
Instruction describing how to create a file via the applypatch tool.
3 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
ImageGenTool
object
A tool that generates images using the GPT image models.
12 properties
1 required
MessageStatus
string
ApplyPatchCreateFileOperationParam
object
Instruction for creating a new file via the applypatch tool.
3 properties
3 required
ErrorResponse
object
1 property
1 required
CodeInterpreterTool
object
A tool that runs Python code to help generate a response to a prompt.
3 properties
2 required
FunctionShellActionParam
object
Commands and limits describing how to run the shell tool call.
3 properties
1 required
MoveParam
object
A mouse move action.
4 properties
3 required
ProgramOutputItemParam
object
5 properties
5 required
OutputTextContent
object
A text output from the model.
4 properties
4 required
ContainerNetworkPolicyDisabledParam
object
1 property
1 required
ImageBackground
string
ToolSearchOutputItemParam
object
6 properties
2 required
ProgramItemParam
object
5 properties
5 required
ClickButtonType
string
CustomGrammarFormatParam
object
A grammar defined by the user.
3 properties
3 required
MCPToolCallStatus
string
MCPProtocolError
object
3 properties
3 required
ApplyPatchCallStatus
string
LocalShellToolCallOutput
object
The output of a local shell tool call.
4 properties
4 required
DragParam
object
A drag action.
3 properties
2 required
HTTPError
object
3 properties
3 required
WebSearchActionFind
object
Action type "findinpage": Searches for a pattern within a loaded page.
3 properties
3 required
GrammarSyntax1
string
ApplyPatchCallOutputStatusParam
string
Outcome values reported for applypatch tool call outputs.
ComputerCallSafetyCheckParam
object
A pending safety check for the computer call.
3 properties
1 required
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
MisalignmentErrorDetailsResource
object
3 properties
Tool
A tool that can be used to generate a response.
LocalShellToolCall
object
A tool call to run a command on the local shell.
5 properties
5 required
CreateConversationBody
object
2 properties
CustomToolCall
object
A call to a custom tool created by the model.
8 properties
4 required
FunctionShellToolParam
object
A tool that allows the model to execute shell commands.
3 properties
1 required
InputImageContent
object
An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision).
5 properties
2 required
ToolSearchCallItemParam
object
6 properties
2 required
CompactionSummaryItemParam
object
A compaction item generated by the [v1/responses/compact API](https://developers.openai.com/api/reference/resources/responses/methods/compact).
3 properties
2 required
UrlCitationBody
object
A citation for a web resource used to generate a model response.
5 properties
5 required
KeyPressAction
object
A collection of keypresses the model would like to perform.
2 properties
2 required
ApplyPatchToolParam
object
Allows the assistant to create, delete, or update files using unified diffs.
2 properties
1 required
ComputerEnvironment
string
AdditionalTools
object
4 properties
4 required
NamespaceToolParam
object
Groups function/custom tools under a shared namespace.
4 properties
4 required
FilePath
object
A path to a file.
3 properties
3 required
LocalSkillParam
object
3 properties
3 required
FileSearchTool
object
A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file…
5 properties
2 required
UpdateConversationBody
object
1 property
1 required
VectorStoreFileAttributes
MCPToolCallError
RankerVersionType
string
CustomToolCallOutput
object
The output of a custom tool call from your code, being sent back to the model.
5 properties
3 required
FunctionShellCallOutputTimeoutOutcomeParam
object
Indicates that the shell call exceeded its configured time limit.
1 property
1 required
LogProb
object
The log probability of a token.
4 properties
4 required
LocalShellToolParam
object
A tool that allows the model to execute shell commands in a local environment.
1 property
1 required
FunctionShellCallOutputOutcomeParam
The exit or timeout outcome associated with this shell call.
_MisalignmentSteer
object
1 property
1 required
ComputerScreenshotContent
object
A screenshot of a computer.
5 properties
4 required
ComputerActionList
array
Flattened batched actions for computeruse. Each action includes an type discriminator and action-specific fields.
ClickParam
object
A click action.
5 properties
4 required
ComputerToolCallOutputResource
ReasoningEffort
FunctionShellCallOutputExitOutcome
object
Indicates that the shell commands finished and returned an exit code.
2 properties
2 required
ComputerToolCallOutput
object
The output of a computer tool call.
6 properties
3 required
ComparisonFilter
object
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
3 properties
3 required
MCPListTools
object
A list of tools available on an MCP server.
5 properties
4 required
ProgramOutputItemStatus
string
FileCitationBody
object
A citation to a file.
4 properties
4 required
ComputerScreenshotImage
object
A computer screenshot image used with the computer use tool.
3 properties
1 required
SearchContextSize
string
MCPToolCall
object
An invocation of a tool on an MCP server.
9 properties
5 required
FunctionCallOutputItemParam
object
The output of a function tool call.
8 properties
2 required
InputFileContentParam
object
A file input to the model.
7 properties
1 required
ResponseConfigurationUpdateItemParam
object
An update to the conversation's response configuration. The configuration remains in effect for subsequent responses until it is replaced by another configurat…
3 properties
1 required
MCPApprovalRequest
object
A request for human approval of a tool invocation.
5 properties
5 required
CallableToolAllowedCaller
string
FunctionShellCallOutputItemParam
object
The streamed output items emitted by a shell tool call.
7 properties
3 required
ToolSearchToolParam
object
Hosted or BYOT tool search configuration for deferred tools.
4 properties
1 required
ItemReferenceParam
object
An internal identifier for an item to reference.
2 properties
1 required
ApplyPatchOperationParam
One of the createfile, deletefile, or updatefile operations supplied to the applypatch tool.
WebSearchActionOpenPage
object
Action type "openpage" - Opens a specific URL from search results.
2 properties
1 required
DirectToolCallCallerParam
object
1 property
1 required
ConversationResource
object
4 properties
4 required
TypeParam
object
An action to type in text.
2 properties
2 required
MCPToolFilter
object
A filter object to specify which tools are allowed.
2 properties
LocalShellExecAction
object
Execute a shell command on the server.
6 properties
3 required
ApproximateLocation
object
5 properties
1 required
CodeInterpreterOutputLogs
object
The logs output from the code interpreter.
2 properties
2 required
FunctionShellCallOutputStatusEnum
string
RankingOptions
object
3 properties
PromptCacheBreakpointParam
object
Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's promptcacheoptions.ttl; the boundary is not rounded to a to…
1 property
1 required
Error
object
5 properties
4 required
Filters
ToolSearchCall
object
7 properties
6 required
ComputerCallOutputStatus
string
SkillReferenceParam
object
3 properties
2 required
FunctionShellCallStatus
string
WebSearchCallStatus
string
InputContent
EmptyModelParam
object
ApplyPatchToolCall
object
A tool call that applies file diffs by creating, deleting, or updating files.
7 properties
5 required
FunctionShellCallItemStatus
string
Status values reported for shell tool calls.
ApplyPatchToolCallItemParam
object
A tool call representing a request to create, delete, or update files using diff patches.
6 properties
4 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…
FunctionShellCallOutputTimeoutOutcome
object
Indicates that the shell call exceeded its configured time limit.
1 property
1 required
ToolCallCaller
The execution context that produced this tool call.
Item
object
Content item used to generate a response.
Metadata
InputTextContent
object
A text input to the model.
3 properties
2 required
ProgramToolCallCaller
object
2 properties
2 required
ContainerNetworkPolicyAllowlistParam
object
3 properties
2 required
ConversationItem
A single item within a conversation. The set of possible types are the same as the output type of a [Response object](https://developers.openai.com/api/referen…
PromptCacheBreakpointConfig
object
Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's promptcacheoptions.ttl; the boundary is not rounded to a to…
1 property
1 required
FunctionCallStatus
string
WebSearchApproximateLocation
FunctionToolCallOutput
object
The output of a function tool call.
8 properties
2 required
MCPTool
object
Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides…
12 properties
2 required
FunctionToolCallResource
LocalEnvironmentParam
object
2 properties
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…
ContainerNetworkPolicyDomainSecretParam
object
3 properties
3 required
ImageDetail
string
FunctionShellCall
object
A tool call that executes one or more shell commands in a managed environment.
8 properties
6 required
ProgramOutput
object
5 properties
5 required
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…
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
_MisalignmentErrorType
FileSearchToolCall
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.
5 properties
4 required
MCPApprovalResponse
object
A response to an MCP approval request.
5 properties
4 required
FunctionShellCallOutput
object
The output of a shell tool call that was emitted.
8 properties
6 required
ScrollParam
object
A scroll action.
6 properties
5 required
CompoundFilter
object
Combine multiple filters using and or or.
2 properties
2 required
ProgrammaticToolCallingParam
object
1 property
1 required
CustomTextFormatParam
object
Unconstrained free-form text.
1 property
1 required
FunctionShellAction
object
Execute a shell command.
3 properties
3 required
SummaryTextContent
object
A summary text from the model.
2 properties
2 required
DirectToolCallCaller
object
1 property
1 required
ImageGenActionEnum
string
WebSearchTool
object
Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).
5 properties
1 required
ContainerFileCitationBody
object
A citation for a container file used to generate a model response.
6 properties
6 required
ToolCallCallerParam
The execution context that produced this tool call.
CompactionBody
object
A compaction item generated by the [v1/responses/compact API](https://developers.openai.com/api/reference/resources/responses/methods/compact).
4 properties
3 required
Annotation
An annotation that applies to a span of output text.
ToolSearchExecutionType
string
RefusalContent
object
A refusal from the model.
2 properties
2 required
ComputerTool
object
A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).
1 property
1 required
ContainerAutoParam
object
5 properties
1 required
InputTextContentParam
object
A text input to the model.
3 properties
2 required
MCPListToolsTool
object
A tool available on an MCP server.
4 properties
2 required
ApplyPatchDeleteFileOperation
object
Instruction describing how to delete a file via the applypatch tool.
2 properties
2 required
FunctionToolCallOutputResource
TextContent
object
A text content.
2 properties
2 required
WebSearchPreviewTool
object
This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tool…
4 properties
1 required
ApplyPatchCallStatusParam
string
Status values reported for applypatch tool calls.
AdditionalToolsItemParam
object
4 properties
3 required
TopLogProb
object
The top log probability of a token.
3 properties
3 required
AutoCodeInterpreterToolParam
object
Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
4 properties
1 required
ConversationItemList
object
A list of Conversation items.
5 properties
5 required
LocalEnvironmentResource
object
Represents the use of a local environment to perform shell actions.
1 property
1 required
InputItem
ApplyPatchUpdateFileOperationParam
object
Instruction for updating an existing file via the applypatch tool.
3 properties
3 required
CodeInterpreterToolCall
object
A tool call to run code.
6 properties
6 required
DeletedConversationResource
object
3 properties
3 required
SearchContentType
string
FileDetailEnum
string
WebSearchToolCall
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.
4 properties
4 required
Message
object
A message to or from the model.
6 properties
5 required
InputImageContentParamAutoParam
object
An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)
5 properties
1 required
FileInputDetail
string
CoordParam
object
An x/y coordinate pair, e.g. { x: 100, y: 200 }.
2 properties
2 required
ResponseConfigurationUpdate
object
A configuration update that applies to subsequent responses until it is replaced by another configuration update.
3 properties
2 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.