Migrating Off OpenAI Codex, Deep Research, and Computer Use Before the July 23 Shutdown

On April 22, 2026, OpenAI announced the retirement of a set of older model snapshots — covering Codex variants, deep-research models, computer-use previews, and legacy search-preview IDs. All of them shut down on July 23, 2026. As of today (July 3), that is 20 days away.

If your production code calls any of these model IDs, requests will start returning errors at shutdown. This is not a gradual degradation — the endpoint stops responding to the old name. You need to migrate, test, and deploy before July 23.

We route OpenAI-compatible requests through configured providers and support provider/model routing and fallback where the live product path supports it. We do not claim zero downtime, universal model availability, or guaranteed cheapest pricing. Every date and pricing figure in this guide is sourced from OpenAI's official documentation at retrieval time.

1. Swap three values, not three SDKs. Change api_key, base_url, and model in the existing OpenAI client. Keep your request/response code unchanged.
2. Map model IDs explicitly. The target provider's model id is almost never identical to the OpenAI id. Keep a single dict of { openai_id: target_id } outside business logic.
3. Verify streaming format. SSE chunks must follow the OpenAI data: {...} + data: [DONE] contract. Test one streaming call before moving production traffic.
4. Check rate-limit headers. Some providers omit x-ratelimit-* headers. Add a wrapper that defaults safely when headers are absent.
5. Keep a rollback path. Ship the swap behind a feature flag, run both endpoints in shadow for 24 hours, then cut over.

30-second answer

• Shutdown date: July 23, 2026. Zero grace period after this date (OpenAI Deprecations, retrieved 2026-07-03).
• Categories retiring: Codex variants (gpt-5-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini), deep-research models (o3-deep-research, o4-mini-deep-research), computer-use preview, legacy search-preview IDs, and audio/realtime mini snapshots.
• Primary replacements: gpt-5.5 (Codex/flagship), gpt-5.4-mini (mini/search-preview/computer-use), gpt-5.5-pro (deep research).
• Notice period: These are specialized variants (Codex, deep-research) and preview models — OpenAI's policy provides 3 months for variants and as little as 2 weeks for preview models. This is within policy.
• Action required now: Grep your codebase for the model IDs below. Shadow-test replacements. Deploy before July 20 to leave a safety buffer.

Full model replacement matrix

All data from OpenAI Deprecations, retrieved 2026-07-03.

Key pattern — three replacement targets: The Codex and flagship chat variants consolidate onto gpt-5.5. Mini and preview variants move to gpt-5.4-mini. Deep-research workloads land on gpt-5.5-pro. Audio/realtime get like-for-like snapshot upgrades.

Before/after code diffs

Codex variants (gpt-5-codex, gpt-5.1-codex, gpt-5.1-codex-max)

These IDs were used for coding-focused completions — typically in agentic coding pipelines, CI code review, or Codex CLI integrations. The replacement is gpt-5.5.

# Before
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5.1-codex",          # ← retiring Jul 23
    messages=[{"role": "user", "content": "Refactor this function: ..."}],
)

# After
response = client.chat.completions.create(
    model="gpt-5.5",                 # ✓ replacement
    messages=[{"role": "user", "content": "Refactor this function: ..."}],
)

For gpt-5.1-codex-mini (the cost-optimized Codex variant), use gpt-5.4-mini:

# After (mini workloads)
response = client.chat.completions.create(
    model="gpt-5.4-mini",            # ✓ replacement for codex-mini
    messages=[{"role": "user", "content": "..."}],
)

Deep research (o3-deep-research, o4-mini-deep-research)

Deep-research models are used for long-horizon research tasks via the Responses API. The replacement is gpt-5.5-pro.

# Before — using the Responses API with o3-deep-research
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="o3-deep-research",        # ← retiring Jul 23
    input="Summarize the state of quantum error correction in 2026.",
    tools=[{"type": "web_search_preview"}],
)

# After
response = client.responses.create(
    model="gpt-5.5-pro",             # ✓ replacement
    input="Summarize the state of quantum error correction in 2026.",
    tools=[{"type": "web_search_preview"}],
)

Note: gpt-5.5-pro is significantly more expensive than o3-deep-research. If the cost delta is a concern, test gpt-5.5 first — it handles many research workloads without requiring the Pro tier. See the pricing section below.

Computer use (computer-use-preview)

Computer-use applications used computer-use-preview to control browser/desktop environments. OpenAI maps this to gpt-5.4-mini. Note that computer-use-preview had special computer-use capability; the replacement is a general-purpose model with computer-use tool access.

# Before
response = client.responses.create(
    model="computer-use-preview",    # ← retiring Jul 23
    input=[{"type": "text", "text": "Open the terminal and run `ls -la`."}],
    tools=[{"type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser"}],
)

# After — use gpt-5.4-mini with computer_use tool
response = client.responses.create(
    model="gpt-5.4-mini",            # ✓ replacement per OpenAI deprecation notice
    input=[{"type": "text", "text": "Open the terminal and run `ls -la`."}],
    tools=[{"type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser"}],
)

Test thoroughly: gpt-5.4-mini is a general-purpose model. Validate that computer-use task completion rates match your baseline before deploying.

Web search previews (gpt-4o-search-preview, gpt-4o-mini-search-preview)

These were the web_search_preview tool-equipped models. They migrate to gpt-5.4-mini with the current non-preview web search tool.

# Before
response = client.chat.completions.create(
    model="gpt-4o-search-preview",   # ← retiring Jul 23
    messages=[{"role": "user", "content": "What are the latest OpenAI model prices?"}],
)

# After — gpt-5.4-mini with web_search tool via Responses API
response = client.responses.create(
    model="gpt-5.4-mini",            # ✓ replacement
    input="What are the latest OpenAI model prices?",
    tools=[{"type": "web_search_preview"}],
)

Note: The Responses API is the canonical home for web search going forward. If you are still on Chat Completions for search, this migration is also an opportunity to adopt Responses API — as covered in our Assistants to Responses migration guide.

Pricing delta

Pricing from OpenAI API Pricing, retrieved 2026-07-03.

Deep research cost warning: If your workload uses o3-deep-research at scale, gpt-5.5-pro at $30/$180 per million tokens is a significant step up. Evaluate whether gpt-5.5 at $5/$30 meets your quality bar before committing to Pro. Run the same batch of research tasks against both models and measure output quality before deploying.

Codex/mini cost change: gpt-5.4-mini at $0.75/$4.50 is in a similar cost band to what Codex-mini workflows typically used. Most teams will see a neutral-to-slight cost change here.

Search-preview models: These were essentially free to call beyond model token rates. The replacement gpt-5.4-mini with the web search tool bills at $10 per 1,000 search calls plus model token rates. If you run high-volume search queries, this is a meaningful cost increase — plan accordingly.

Gotchas and migration checklist

Auth and headers

No auth changes are required. All replacement models use the same Authorization: Bearer $OPENAI_API_KEY header and the same base URL (https://api.openai.com/v1).

Model ID casing and aliases

OpenAI accepts both the versioned snapshot (o3-deep-research-2025-06-26) and the unversioned alias (o3-deep-research). Both retire July 23. Grep for both forms.

API surface differences

• Codex → gpt-5.5: Same Chat Completions or Responses API surface. The model field is the only change for most callers.
• o3-deep-research → gpt-5.5-pro: Same Responses API surface. reasoning.effort parameter still applies on gpt-5.5-pro. No structural change required.
• computer-use-preview → gpt-5.4-mini: The computer_use_preview tool schema is unchanged. Only model changes.
• search-preview → gpt-5.4-mini + web_search: If you were on Chat Completions with the search-preview model, consider moving to Responses API for the web_search_preview tool. Chat Completions web search (enable_search: true) still works on gpt-5.4-mini where the provider supports it.

Snapshot pinning and rollback

If you need to hold a stable model response profile for a critical workload, you can pin to the date-stamped snapshot on the replacement model (e.g., gpt-5.5-2026-05-15 if available). Check the OpenAI models reference for available snapshots of each replacement.

Until July 23, you can also keep calling the old model IDs in non-critical paths while migrating production. After July 23 there is no rollback — the endpoints go offline.

Rollback path

We recommend a phased approach:

1. Now (Jul 3–Jul 10): Identify all callers of retired model IDs. Update model IDs in code. Deploy to staging.
2. Jul 10–Jul 17: Run shadow traffic against both old and new model IDs. Compare outputs and latency.
3. Jul 17–Jul 20: Ramp production traffic to new model IDs. Disable the old IDs in your router config.
4. Jul 20–Jul 23: Full production cutover. Monitor error rates on the old IDs — if you see zero errors, migration is complete.

If you discover a regression after deploying the new model IDs, your rollback is to revert the model field to the old ID — but only until July 23. After that date, there is no rollback option.

TheRouter integration: fallback configuration for the transition window

If you route OpenAI-compatible traffic through TheRouter, you can configure automatic fallback from the retiring model IDs to their replacements during the transition window. This provides a safety net for any callers that miss the July 20 deadline.

{
  "routes": [
    {
      "match": { "model": "gpt-5.1-codex" },
      "rewrite_model": "gpt-5.5",
      "provider": "openai",
      "comment": "gpt-5.1-codex retiring Jul 23 — rewrite to gpt-5.5"
    },
    {
      "match": { "model": "o3-deep-research" },
      "rewrite_model": "gpt-5.5-pro",
      "provider": "openai",
      "comment": "o3-deep-research retiring Jul 23 — rewrite to gpt-5.5-pro"
    },
    {
      "match": { "model": "computer-use-preview" },
      "rewrite_model": "gpt-5.4-mini",
      "provider": "openai",
      "comment": "computer-use-preview retiring Jul 23 — rewrite to gpt-5.4-mini"
    },
    {
      "match": { "model": "gpt-4o-search-preview" },
      "rewrite_model": "gpt-5.4-mini",
      "provider": "openai",
      "comment": "gpt-4o-search-preview retiring Jul 23 — rewrite to gpt-5.4-mini"
    }
  ]
}

TheRouter routes OpenAI-compatible requests through configured providers and supports provider/model routing and fallback where the live product path supports it. For fallback routing to work, the target model must be live and accessible on your configured provider. Verify that gpt-5.5, gpt-5.4-mini, and gpt-5.5-pro are available through your OpenAI provider configuration before relying on this as a safety net.

See our OpenAI migration guide and model fallback docs for more on routing configuration.

Relation to other deprecation waves

This July 23 wave is distinct from two other active OpenAI deprecation events:

• December 11, 2026: Six first-generation GPT-5 and O3 model snapshots (gpt-5-2025-08-07, o3-2025-04-16, etc.) — covered in our GPT-5 deprecation planning guide.
• November 30, 2026: OpenAI reusable prompts, Evals platform, and Agent Builder — announced June 3, 2026; not model IDs.

Focus on July 23 first. After that deadline passes, audit for the December wave.

Production checklist

Use this checklist before July 23:

• Grep codebase for all retiring model ID strings (see full list in the replacement matrix above)
• Identify API surface for each caller: Chat Completions vs Responses API vs legacy Assistants
• Map each deprecated ID to its replacement from the table above
• Update model fields in all callers and configuration files
• Deploy to staging and run your existing test suite
• Shadow-test production traffic against new model IDs (Jul 10–17)
• Cost audit: Compare estimated monthly token spend at new model pricing — especially if using deep-research
• TheRouter config: If applicable, add model-rewrite rules for any callers not yet migrated
• Deploy to production by July 20 (3-day safety buffer before shutdown)
• Monitor error rates on old model IDs — zero errors = clean migration
• Remove old model ID references from code after successful cutover

Related resources

• OpenAI Deprecations page — source of record, retrieved 2026-07-03
• OpenAI API Pricing — model pricing, retrieved 2026-07-03
• OpenAI models reference — snapshot availability
• Migrate from Assistants to Responses API — if your search-preview callers are on Chat Completions or Assistants
• GPT-5 December 2026 sunset guide — the next OpenAI deprecation wave
• OpenAI provider page — live model routing status on TheRouter
• model fallback docs — fallback routing configuration