Why Codex Calls the Wrong API, and How to Ground It in Real Schemas

Codex calls the wrong API when it writes or runs integration code from what it remembers about an API instead of from the provider's current schema. The output is usually plausible: an endpoint that follows the provider's naming style, a parameter that sounds right, a helper function that should exist. The fix is to give Codex a source of truth it can query, a short AGENTS.md that tells it to use that source, and an execution step that validates every external call against the real schema before sending it.

This article covers what wrong API calls look like in Codex, what users report, why they happen, what Codex's own configuration can do about it, and how to connect Codex to an operation catalog so invented calls fail closed. It applies to the Codex CLI, the IDE extension, and the desktop app, which share the same configuration. Checked against OpenAI's Codex documentation and public GitHub issues in October 2026.

What does a wrong API call from Codex look like?

• Guessed endpoints. A path that matches the provider's style but does not exist, or an old path the provider has since moved.
• Invented parameters. Query or body fields from a different version of the API, or from a similar API by another provider.
• Wrong payload shape. A request body built for one endpoint or API version sent to another that expects a different structure.
• Functions that do not exist. Helper or SDK functions the model names confidently and then calls, in a codebase where they were never defined.

What Codex users report

Reports on the openai/codex GitHub repository and the r/codex community show the pattern:

• Issue #41311, an invented function. Filed in August 2026: Codex referred to a renderAssetsView() function that did not exist in the file or anywhere in the repository. The expected behavior the reporter wrote down was simply "to actually check the repository".
• "How do you verify Codex isn't hallucinating your API integrations?" A thread on r/codex where the most practical replies converge on two habits: keep a small contract file for each risky provider (exact endpoint, auth scope, fields the agent may write, fields it must never infer, and one known-good request), and run integration tests against a sandbox account before trusting new integration code.
• Issue #14242, a server the agent did not use. Codex checked a tool-only MCP server for resources, found none, and treated the server as unavailable even though its tools worked. A source of truth only helps when the agent actually reaches it.

Codex shares this problem with other coding agents. Claude Code, Cursor, Gemini CLI, and GitHub Copilot users report the same class of failure, and research on tool calling finds that most wrong calls are well-formed but carry wrong values (ParamBench, arXiv 2608.03071), which is why a format check alone misses them.

Why Codex gets API calls wrong

• It works from memory unless told otherwise. Without a reference in context, the model fills in endpoints and fields from patterns it learned, which mixes versions and providers.
• The long tail is thin. Popular APIs appear often in training data. Internal APIs and smaller providers barely appear, so guesses get worse exactly where teams have the least documentation.
• Instructions have a size limit. Codex concatenates AGENTS.md files from the project root down to the working directory and stops at project_doc_max_bytes, 32 KiB by default. Full API references do not fit, and long ones crowd out other guidance.
• The default sandbox leaves calls untested. In workspace-write mode, network access is off unless you turn it on. That is a sensible default, and it also means Codex often writes API code it cannot run, so mistakes surface later.
• Long sessions drift. As context fills with code and output, early instructions carry less weight. Several r/codex replies recommend re-grounding the agent from a written spec or starting a fresh session.

What Codex configuration can do

An AGENTS.md section for external APIs

Keep it short so it fits within the size limit and holds up in long sessions. Name the tools and say what to do on failure.

## External APIs

- Never write an endpoint, parameter, or request body from memory.
- For third-party APIs, use the Swytchcode MCP tools: discover the operation,
  read its schema with info, then exec. Preview writes with dry_run=true.
- For internal APIs, read the route handler or the contract file in docs/contracts/.
- If a call fails validation, report the error and stop. Do not try other
  endpoints, versions, or providers to make it pass.

How Swytchcode grounds Codex in real API schemas

Swytchcode is an execution layer between agents and the APIs they call. Codex describes the job, Swytchcode returns real operations from its catalog, and every call runs through one pipeline: resolve the tool, validate inputs, evaluate policies, resolve credentials, execute, and normalize the response. An invented operation or a field the schema does not define fails at validation, before any request leaves the machine. Credentials are resolved at execution time and never pass through the model's context.

With the codex editor option, swy init writes Swytchcode guidance into AGENTS.md and merges a stdio MCP entry into ~/.codex/config.toml. The Codex CLI, IDE extension, and desktop app pick it up from there.

# Initialize the project for Codex in sandbox mode
npm install -g swytchcode
swy init --editor=codex --mode=sandbox
swy doctor

# The loop Codex follows for any third-party call
swy discover "create an invoice for a customer" --json
swy get <project>
swy add <canonical_id>
swy info <canonical_id>
swy exec <canonical_id>

To keep a person in front of every live call, require approval for the exec tool only. Lookups such as swytchcode_discover and swytchcode_info stay automatic.

# ~/.codex/config.toml
[mcp_servers.swytchcode]
command = "swytchcode"
args = ["mcp", "serve"]

[mcp_servers.swytchcode.tools.swytchcode_exec]
approval_mode = "prompt"

If Codex calls the swytchcode CLI from its shell instead of over MCP, that command needs network access, which the default workspace-write sandbox turns off. Either set network_access = true under [sandbox_workspace_write] for that project or use the MCP server.

What happens when Codex guesses anyway:

• Unknown or not-enabled operations are rejected. An invented canonical ID, or a real one that has not been added to the project, exits with code 2 and no request is sent.
• Invalid inputs fail validation. A missing required field, a wrong type, or a field the schema does not define exits with code 1 before the provider sees the request.
• Provider errors come back structured. Each error includes the status code, an error category, and whether it is retryable, so Codex can stop or retry on facts. A 200 response with an error in the body counts as a failure.
• Schema changes are flagged. swy sync compares stored method hashes and warns when an installed operation has changed, so Codex keeps working against the current definition.
• Writes can be held. dry_run=true previews the request without sending it. For production, allow and deny rules are available from the Pro plan, and approval rules that route a call to Slack or Telegram are available on Business and Enterprise.

Where this does not help

Swytchcode checks calls to external APIs and to internal APIs you add from an OpenAPI spec. It does not catch an invented helper function inside your own repository, like the one in issue #41311. Type checking, tests, and asking Codex to search the repository before calling a function cover that case. Swytchcode also cannot tell whether a valid ID or value is the right one for your task, so keep dry runs and approvals on writes.

Frequently asked questions

Why does Codex hallucinate API endpoints?
Codex fills gaps from patterns it learned when the real schema is missing from its context. Results are worst for internal APIs and smaller providers, which barely appear in training data.

How do I add an MCP server to Codex?
Run codex mcp add, or add an [mcp_servers.<name>] table with command and args to ~/.codex/config.toml. Trusted projects can also use a project-level .codex/config.toml. The CLI, IDE extension, and desktop app share this configuration.

Codex says my MCP server is unavailable. What should I check?
Run /mcp to confirm the server is enabled and connected. Issue #14242 describes Codex treating a server that offers tools but no resources as unavailable. Asking Codex to call the server's tools directly usually works around it.

Can Codex call external APIs from its sandbox?
Only if you allow it. The workspace-write sandbox keeps network access off unless you set network_access = true under [sandbox_workspace_write].

Does Swytchcode work with Codex?
Yes. Run swy init --editor=codex to add the Swytchcode MCP server to ~/.codex/config.toml and guidance to AGENTS.md.

Swytchcode resources

• Why AI agents call the wrong API: https://www.swytchcode.com/content/why-your-ai-agent-calls-the-wrong-api-and-how-to-fix-it
• Why Claude Code guesses API endpoints: https://www.swytchcode.com/content/why-claude-code-guesses-api-endpoints
• Why Cursor writes outdated API calls: https://www.swytchcode.com/content/cursor-outdated-api-calls
• GitHub Copilot hallucinated API methods: https://www.swytchcode.com/content/github-copilot-hallucinated-api-methods
• Swytchcode MCP server docs: https://docs.swytchcode.com/cli/mcp/
• CLI command reference: https://docs.swytchcode.com/reference/commands/
• Supported APIs: https://www.swytchcode.com/apis