Search the API docs Using GPT-6 Astra Conversation state Background mode Mid-turn steering Counting tokens Supported countries OpenAI Crawlers Terms and policies Agent Builder Overview Migration guide Node reference Safety in building agents Migration guide Safety in building agents Evals Getting started Working with evals Prompt optimizer External models Best practices Graders Getting started Working with evals Prompt optimizer External models Fine-tuning Optimization cycle Supervised fine-tuning Vision fine-tuning Direct preference optimization Reinforcement fine-tuning RFT use cases Best practices Optimization cycle Supervised fine-tuning Vision fine-tuning Direct preference optimization Reinforcement fine-tuning Assistants API Migration guide Migration guide Model selection Text generation Code generation Structured output Prompt engineering Citation formatting Migration guide Prompt generation Frontend prompting Reasoning models Reasoning best practices Images and video Images and vision Image input cost calculator Image input cost calculator Image generation Overview Image prompting Image prompting Video generation Realtime and audio Audio and speech Getting started Specialized models Configuring Agents Sessions Run and continue sessions Events and items Manage sessions Webhooks Run and continue sessions Events and items Manage sessions Environments and sandboxes OpenAI-hosted sandboxes Self-hosted sandboxes Sandbox lifecycle Sandbox security Files and artifacts OpenAI-hosted sandboxes Self-hosted sandboxes Sandbox lifecycle Sandbox security Files and artifacts Tools and integrations Web search Functions MCP connections Plugins Vaults MCP connections Observability and usage Agent definitions Models and providers Results and state Integrations and observability Evaluate agent workflows Advanced integrations Function calling Search and retrieval Connect tools and data Secure MCP Tunnel Build tool workflows Programmatic tool calling Async tool calling Computer and code Code interpreter Image generation Getting started Managing sessions Delegation and tools Migrate to GPT-Live Partner integrations Getting started Managing conversations Voice activity detection Build with voice Cost optimization Telephony and SIP Server-side controls Audio processing File transcription Live transcription Live translation Audio in Chat Completions Production best practices Deployment checklist Performance and quality Latency optimization Predicted Outputs Accuracy optimization Cost and throughput Cost optimization Prompt caching Prompt cache diagnostics Prompt cache diagnostics Flex processing Safety and governance Safety best practices Safety checks Safety classifiers Cybersecurity checks Misalignment monitoring Safety classifiers Cybersecurity checks Misalignment monitoring Under-18 guidance Content provenance Infrastructure and access Terraform provider Overview Projects and access Service accounts Rate limits and spend Model, tool, and data controls Import and reconciliation Projects and access Service accounts Rate limits and spend Model, tool, and data controls Import and reconciliation Workload identity federation Federation rules X.509 certificates Kubernetes AWS Microsoft Azure Google Cloud Oracle Cloud Infrastructure GitHub Actions SPIFFE Federation rules X.509 certificates Microsoft Azure Oracle Cloud Infrastructure IP egress ranges Plugin architecture Brainstorm use cases Build an MCP server Add UI to your MCP server (optional) Authenticate users Package your plugin Test and publish Connect and test your plugin Submit and publish Submission error reference Conversion specs Restaurant reservation spec Product checkout spec Optimize Metadata Submit a Claude Code plugin Security & Privacy Troubleshooting Plugin guidelines MCP server review requirements Plugin UI reference Checkout API reference Trigger workspace agent runs Authenticate with Workspace Agent access tokens Measurement Pixel Multiple Pixels (Advanced) Conversions API Supported Events Campaign Management Bidding & Budgets Conversion Tracking Troubleshooting Account Management Conversion Setup Get started with Work Import from another agent Personalize ChatGPT Skills & Plugins ChatGPT desktop app ChatGPT on the web Codex IDE extension Feature Maturity Projects and chats Scheduled tasks Long-running work Image generation Browser extension Work with files Troubleshooting Computer History Advanced Config Config Reference Environment Variables Agent configuration Extend ChatGPT and Codex Record & Replay Windows sandbox Development workflows

Integrated terminal Extend and automate Site tools (WebMCP) Local environments Cloud environment Build with Codex Non-interactive mode Third-party integrations CLI customization Developer commands Developer settings Agent approvals & security Internet access Codex Security plugin Quickstart Run a security scan Run a deep scan Review code changes Use the Security workbench Triage a backlog Fix findings Propose security hardening Write vulnerability reports Export and track findings Changelog Run a security scan Run a deep scan Review code changes Use the Security workbench Triage a backlog Propose security hardening Write vulnerability reports Export and track findings Codex Security CLI Quickstart Run bulk scans Run scans in CI GitLab CI/CD Reference FAQ Run scans in CI Codex Security cloud Setup Security Review Improving the threat model FAQ Security Review Improving the threat model Models & Trusted Access Recommended configuration Getting started Admin rollout guide ChatGPT Work Overview ChatGPT Work cloud security ChatGPT Work local security ChatGPT Work admin FAQ ChatGPT Work: usage and cost Identity and authentication Authentication overview Personal Access Tokens Service accounts Workspace access, policy, and models Groups and provisioning User lifecycle management Roles and workspace permissions GPTs and Sharing Managed configuration HIPAA configuration Workspace model availability Plugin and connector controls Plugin controls Plugin management Usage, governance, and compliance Workspace analytics Compliance API and audit events Deployment and model providers Manage app updates Windows app deployment Remote connections Explore use cases Online trainings Codex Ambassadors Codex for Students Codex for Open Source Explore use cases Online trainings Codex Ambassadors Codex for Students Codex for Open Source Rethinking skills and prompts for GPT-6 Astra Architectural visualization with Astra Building games with Astra Meet Rosalind Workbench: Empowering every scientist to be their own research team Automating repetitive work at OpenAI with Codex Cookbook on GitHub OpenAI Developers plugin Image generation Video generation Codex Ambassadors Codex for Students Codex for Open Source OpenAI for Startups Developer Forum The Responses API is our new API primitive, an evolution of Chat Completions which brings added simplicity and powerful agentic primitives to your integrations. While Chat Completions remains supported, Responses is recommended for all new projects. About the Responses API The Responses API is a unified interface for building powerful, agent-like applications. It contains: Built-in tools like web search , file search , computer use , code interpreter , and remote MCPs . Seamless multi-turn interactions that allow you to pass previous responses for higher accuracy reasoning results. Native multimodal support for text and images. Responses benefits The Responses API contains several benefits over Chat Completions: Better performance : Using reasoning models, like GPT-5, with Responses will result in better model intelligence when compared to Chat Completions. Our internal evals reveal a 3% improvement in SWE-bench with same prompt and setup. Agentic by default : The Responses API is an agentic loop, allowing the model to call multiple tools, like web_search , image_generation , file_search , code_interpreter , remote MCP servers, as well as your own custom functions, within the span of one API request. Lower costs : Results in lower costs due to improved cache utilization (40% to 80% improvement when compared to Chat Completions in internal tests). Stateful context : Use store: true to maintain state from turn to turn, preserving reasoning and tool context from turn-to-turn. Flexible inputs : Pass a string with input or a list of messages; use instructions for system-level guidance. Encrypted reasoning : Opt-out of statefulness while still benefiting from advanced reasoning. Future-proof : Future-proofed for upcoming models. See how the Responses API compares to the Chat Completions API in specific scenarios. Messages vs. Items Both APIs make it easy to generate output from our models. The input to, and result of, a call to Chat completions is an array of Messages , while the Responses API uses Items . An Item is a union of many types, representing the range of possibilities of model actions. A message is a type of Item, as is a function_call or function_call_output . Unlike a Chat Completions Message, where many concerns are glued together into one object, Items are distinct from one another and better represent the basic unit of model context. Additionally, Chat Completions can return multiple parallel generations as choices , using the n param. In Responses, we’ve removed this param, leaving only one generation. When you get a response back from the Responses API, the fields differ slightly. Instead of a message , you receive a typed response object with its own id . Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage when using either API, set store: false . The objects you receive back from these APIs will differ slightly. In Chat Completions, you receive an array of choices , each containing a message . In Responses, you receive an array of Items labeled output . Additional differences Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage in either API, set store: false . Reasoning models have a richer experience in the Responses API with improved tool usage . Starting with GPT-5.4, Chat Completions does not support tool calling with reasoning_effort values other than none . Structured Outputs API shape is different. Instead of response_format , use text.format in Responses. Learn more in the Structured Outputs guide. The function-calling API shape is different, both for the function config on the request, and function calls sent back in the response. See the full difference in the function calling guide . The Responses SDK has an output_text helper, which the Chat Completions SDK does not have. In Chat Completions, conversation state must be managed manually. The Responses API has compatibility with the Conversations API for persistent conversations, or the ability to pass a previous_response_id to easily chain Responses together. Migrating from Chat Completions Treat migration as three related changes: send requests to /v1/responses , read output from a typed output array, and choose how your application will carry state between turns. 1. Update generation endpoints Start by updating your generation endpoints from post /v1/chat/completions to post /v1/responses . If you are not using functions or multimodal inputs, simple message inputs are compatible from one API to the other: Chat Completions With Chat Completions, you create a messages array and read the model text from completion.choices[0].message.content . Responses With Responses, you can separate instructions and input at the top level and read generated text from response.output_text . 2. Map Messages to Items Chat Completions uses messages as both input and output. Responses uses input and output arrays of typed Items. A message is one Item type, alongside Items such as reasoning , function_call , and function_call_output . When you only need the final text, use the SDK output_text helper. When your flow uses reasoning, tools, or multimodal output, iterate over response.output and handle each Item by its type . 3. Update multi-turn conversations If you have multi-turn conversations in your application, update your context logic. Responses gives you three common state-management options: Use previous_response_id when you want OpenAI to manage prior response context. Resend stable instructions on each request, because previous_response_id does not carry over the previous response’s top-level instructions . Pass prior output Items back into the next request when you need to manage or trim context yourself. Use the Conversations API when you need a persistent conversation object. Chat Completions In Chat Completions, you store the transcript and send the accumulated messages array on each request. Responses With Responses, you can manually pass outputs from one response into the input of another. You can also use previous_response_id to reference the previous response and create response chains or forks. Even when using previous_response_id , all previous input tokens for responses in the chain are billed as input tokens in the API. 4. Decide when to use statefulness Responses are stored by default. Chat Completions are stored by default for new accounts. To disable storage in either API, set store: false . Some organizations, such as those with Zero Data Retention (ZDR) requirements, cannot use the Responses API in a stateful way due to compliance or data retention policies. To support these cases, OpenAI offers encrypted reasoning items, allowing you to keep your workflow stateless while still benefiting from reasoning items. To disable statefulness but still take advantage of reasoning: Set store: false in the store field . Preserve and replay every returned reasoning item. Each item includes encrypted_content by default when you create a response. The API will then return an encrypted version of the reasoning tokens, which you can pass back in future requests just like regular reasoning items. For ZDR organizations, OpenAI enforces store: false automatically. When a request includes encrypted_content , it is decrypted in memory, used for generating the next response, and then securely discarded. Any new reasoning tokens are immediately encrypted and returned to you, ensuring no intermediate state is persisted. 5. Update function definitions and outputs There are two minor, but notable, differences in how functions are defined between Chat Completions and Responses. In Chat Completions, function definitions are externally tagged. In Responses, they are internally tagged. In Chat Completions, functions are non-strict by default. In Responses, omitting strict attempts strict mode; if the schema cannot be made compatible, Responses falls back to non-strict, best-effort function calling and returns the resolved tool with strict: false . To keep non-strict behavior in Responses explicitly, set strict: false . The Responses API function example on the right is functionally equivalent to the Chat Completions example on the left. Follow function-calling best practices In Responses, tool calls and their outputs are two distinct types of Items that are correlated using a call_id . See the function calling docs for more detail on how function calling works in Responses. 6. Update Structured Outputs definitions In the Responses API, Structured Outputs definitions have moved from response_format to text.format : 7. Update streaming consumers Chat Completions streaming returns incremental chunks with a delta field. Responses streaming uses typed server-sent events. Update stream consumers to branch on each event’s type and handle the events your UI or orchestration layer needs. For text streaming, listen for events such as: response.created response.output_text.delta response.completed Function-calling streams can also emit events such as response.function_call_arguments.delta and response.function_call_arguments.done . See the streaming Responses guide and Responses streaming events reference . 8. Upgrade to native tools If your application has use cases that would benefit from OpenAI’s native tools , you can update your tool calls to use OpenAI’s tools out of the box. Chat Completions With Chat Completions, you cannot use OpenAI-hosted tools natively and have to write your own tool integration. This example uses GPT-5.6 because GPT-6 Astra requires the Responses API for tool calling. Responses With Responses, you can specify the tools that you want the model to use. 9. Check common migration errors Watch for these issues when moving code from Chat Completions to Responses: Reading choices[0].message.content instead of response.output_text or response.output . Treating every output entry as a message. Reasoning, tool, and function calls are separate Item types. Dropping reasoning, function call, or function call output Items when manually carrying context into the next response. Sending a function result without the matching call_id . Using response_format in a Responses request instead of text.format . Reusing Chat Completions streaming chunk handlers without handling typed Responses events. Assuming previous_response_id removes billing for prior context. Previous input tokens in the response chain are still billed as input tokens. Incremental rollout checklist Chat Completions remains supported, so you can migrate one user flow at a time. Start with a simple text-generation flow. Update the endpoint, request body, and output handling. Decide whether the flow uses previous_response_id , manual Item replay, or the Conversations API. If the flow is stateless or ZDR, add store: false and include encrypted reasoning items when reasoning context must continue across turns. Migrate function definitions and verify function call outputs include the correct call_id . Move Structured Outputs schemas from response_format to text.format . Update streaming consumers to handle typed Responses events. Replace custom orchestration with OpenAI-hosted tools where they fit the workflow. Compare behavior, latency, token usage, and errors before routing more traffic to Responses. We recommend migrating all flows to the Responses API over time to take advantage of the latest OpenAI features and improvements. Based on developer feedback from the Assistants API beta, we’ve incorporated key improvements into the Responses API to make it more flexible, faster, and easier to use. The Responses API represents the future direction for building agents on OpenAI. The Assistants API was officially sunset on August 26, 2026, and is no longer available. Follow the migration guide to update your integration to the Responses API. Loading docs agent...