Fix 31 dead links to OpenAI documentation

[TusharND12]

Summary

Fixes 31 dead links to OpenAI documentation, appearing 40 times across 25 files.

What's broken

platform.openai.com/docs/* now 301-redirects to developers.openai.com/api/docs/*, but the redirect is path-preserving. Pages that were restructured in the move land on a 404 rather than their new location:

platform.openai.com/docs/models/overview
  → 301 → developers.openai.com/api/docs/models/overview → 404

I extracted all 2167 URLs from examples/, tested the 227 pointing at platform.openai.com and cookbook.openai.com, and found 31 that return a hard 404. The 63 that return 403 are Cloudflare bot-blocking rather than real breakage, and are excluded.

The fixes

• 24 — the old anchor became part of its parent page, so dropping the stale trailing segment resolves it (docs/models/overview → docs/models)
• 5 — Assistants API pages, repointed at the current tool guides (assistants/tools/file-search → guides/tools-file-search)
• 2 — broken internal cookbook.openai.com links, corrected to the slugs those notebooks are published under; one is a gpt4v → gpt4o rename

Links are kept on platform.openai.com rather than rewritten to developers.openai.com. Both hosts serve the corrected paths with a 200, so keeping the existing host limits the diff strictly to what is broken. Happy to switch to the new host if you would rather standardise on it.

Deliberately not changed

The same URLs appear 38 more times inside saved cell outputs and 19 times in examples/data/. Both are left exactly as they are:

• Cell outputs record what a notebook printed on a real run. Rewriting them would misrepresent that run.
• In Parse_PDF_docs_for_RAG.ipynb those output URLs are pages the notebook scraped, and they must stay consistent with examples/data/parsed_pdf_docs.json and parsed_pdf_docs_with_embeddings.csv, whose embeddings are computed over that text.

Only notebook cell source and markdown prose are touched.

Verification

• All 31 original URLs confirmed returning 404; all 20 distinct replacement targets confirmed returning 200
• Structural comparison of every changed notebook against its pre-change version: cell counts, cell types, cell metadata, execution_count and outputs are byte-identical, and each cell's new source equals the URL mapping applied to its old source — 0 deviations
• No lines changed that do not contain openai.com; no lines inside output blocks touched
• 22 changed notebooks pass nbformat.validate and parse as valid JSON
• .github/scripts/check_notebooks.py passes

Known limitation

Where a link pointed at a subsection whose anchor no longer exists, it now resolves to the parent page rather than the exact section — readers land in the right place but may need to scroll. Restoring section-level precision would require anchors that the new docs site does not expose.

Only OpenAI-owned hosts were audited. The remaining ~1940 external URLs in examples/ are out of scope here and may contain further breakage.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3d2ffd32dc

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[TusharND12]

Both applied in a176b35 — thanks, these were real regressions in intent rather than just link rot.

• Agent Builder now points at docs/guides/agent-builder. You're right that the dedicated page is live and already linked further down the same notebook; sending readers to the general Agents guide lost what the link text promised.
• Actions getting-started now points at docs/actions/getting-started rather than the docs root.

Both were cases where my "drop the stale trailing segment" heuristic produced a live URL but a worse destination. Since that's a class of error rather than two isolated slips, I audited the other 29 replacements for the same thing — checking whether a more specific live page exists for each link's text. It doesn't in any remaining case:

docs/guides/parallel-function-calling   404
docs/actions/returning-files            404
docs/actions/timeouts                   404
docs/guides/model-upgrades              404
docs/guides/annotations                 404

Those subsections no longer have standalone pages, so the parent page is the closest live target and readers land on the right page but may need to scroll — the limitation noted in the PR description. If you'd rather I drop the links whose text names a section that no longer exists, rather than repointing them at the parent, happy to do that instead.