use-cases/api-integration-migrations.md +74 −0 added
1---
2name: Upgrade your API integration
3tagline: Upgrade your app to the latest OpenAI API models.
4summary: Use Codex to update your existing OpenAI API integration to the latest
5 recommended models and API features, while checking for regressions before you
6 ship.
7skills:
8 - token: $openai-docs
9 url: https://github.com/openai/skills/tree/main/skills/.curated/openai-docs
10 description: Pull the current model, migration, and API guidance before Codex
11 makes edits to your implementation.
12bestFor:
13 - Teams upgrading from older models or API surfaces
14 - Repos that need behavior-preserving migrations with explicit validation
15starterPrompt:
16 title: Upgrade the Integration Safely
17 body: >-
18 Use $openai-docs to upgrade this OpenAI integration to the latest
19 recommended model and API features.
20
21
22 Specifically, look for the latest model and prompt guidance for this
23 specific model.
24
25
26 Requirements:
27
28 - Start by inventorying the current models, endpoints, and tool assumptions
29 in the repo.
30
31 - Identify the smallest migration plan that gets us onto the latest
32 supported path.
33
34 - Preserve behavior unless a change is required by the new API or model.
35
36 - Update prompts using the latest model prompt guidance.
37
38 - Call out any prompt, tool, or response-shape changes we need to review
39 manually.
40relatedLinks:
41 - label: Latest model guide
42 url: /api/docs/guides/latest-model
43 - label: Prompt guidance
44 url: /api/docs/guides/prompt-guidance
45 - label: OpenAI Docs MCP
46 url: /learn/docs-mcp
47 - label: Evals guide
48 url: /api/docs/guides/evals
49---
50
51## Introduction
52
53As we release new models and API features, we recommend upgrading your integration to benefit from the latest improvements.
54Changing from one model to another is often not as simple as just updating the model name.
55
56There might be changes to the API–for example, for the GPT-5.4 model, we added a new `phase` parameter to the assistant message that is important to include in your integration–but most importantly, model behavior can be different and require changes to your existing prompts.
57
58When migrating to a new model, you should make sure to not only make the necessary code changes, but also evaluate the impact on your workflows.
59
60## Leverage the OpenAI Docs skill
61
62All the specifics about the new API features and model behavior are documented in our docs, in the [latest model](https://developers.openai.com/api/docs/guides/latest-model) and [prompt guidance](https://developers.openai.com/api/docs/guides/prompt-guidance) guides.
63
64The OpenAI Docs skill also includes [specific guidance](https://github.com/openai/codex/blob/6323f0104d17d211029faab149231ba787f7da37/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-5p4.md) as reference, codifying how to upgrade to the latest model–currently [GPT-5.4](https://developers.openai.com/api/docs/models/gpt-5.4).
65
66Codex now automatically comes with the OpenAI Docs skill, so make sure to mention it in your prompt to access all the latest documentation and guidance when building with the OpenAI API.
67
68## Build a robust evals pipeline
69
70Codex can automatically update your prompts based on the latest prompt guidance, but you should have a way to automate verifying your integration is working as expected.
71
72Make sure to build an evals pipeline that you can run every time you make changes to your integration, to verify there is no regression in behavior.
73
74This [cookbook guide](https://developers.openai.com/cookbook/examples/evaluation/building_resilient_prompts_using_an_evaluation_flywheel) covers in detail how to do this using our [Evals API](https://developers.openai.com/api/docs/guides/evals).