Windsurf Cascade Calls API Endpoints That Don't Exist: How to Fix It

Windsurf's Cascade agent calls API endpoints that do not exist when it writes code from what it remembers instead of from the provider's spec or your own route definitions. On the external side, that means invented paths, fields from another API version, or a deprecated method. On the internal side, it means new endpoints that duplicate existing ones or drift from the response shapes the rest of the app expects. The fix combines rules that point Cascade at a source of truth, the actual OpenAPI spec in the workspace, and an execution step that validates every external call before it is sent.

This article covers both failure modes, why they happen, what Windsurf's rules, memories, and MCP settings can do, and how to connect Cascade to an operation catalog so invented calls fail closed. Windsurf's documentation is now published alongside Devin's and several paths have moved, so the configuration notes below use the locations documented in October 2026.

Two ways Cascade gets APIs wrong

What Windsurf users report

• No live access to external docs. A thread on the r/Codeium subreddit asked how to give Windsurf API documentation because it could not reach external docs on its own. The suggested workarounds were downloading docs into the workspace, referencing them with @, putting API rules in rules files, and using the provider's OpenAPI spec as the reference.
• Duplicate and unprotected routes. Troubleshooting guides on humansfix.ai describe Cascade generating duplicate API endpoints with the same path and method, which causes routing conflicts, and generating CRUD and admin routes without authentication checks.
• Endpoints that ignore existing patterns. A Windsurf backend tutorial on Markaicode lists scaffolded endpoints that do not match the response schema of existing ones among the problems to watch for, and recommends describing the stack to Cascade before generating code.

The same class of problem appears in Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot. 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 Cascade calls APIs that don't exist

• Training data stands in for the spec. Without the provider's spec in context, Cascade fills in endpoints and fields from patterns it learned.
• Existing code gets skipped. Generating a new route without reading the existing ones is how duplicates and mismatched response shapes appear.
• Memories are local and automatic. Cascade's auto-generated memories live only on the machine where they were created, so one developer's corrections never reach teammates.
• Rules have budgets. Workspace rule files are limited to 12,000 characters each and the global rules file to 6,000, so full API references do not fit.
• Nothing validates the call before it runs. An invented endpoint looks like a real one until the provider responds.

What Windsurf configuration can do

A Cascade rule for API work

Save this as .devin/rules/apis.md, or .windsurf/rules/apis.md on builds that use the older location. The glob trigger applies it when Cascade reads or edits matching files. Adjust the pattern to where your API code lives.

---
trigger: glob
globs: src/api/**
---

- Before adding an endpoint, list the existing routes and reuse their auth
  middleware and response shapes. Never create a route that already exists.
- For internal APIs, follow openapi.yaml in the repo root.
- Never call a third-party endpoint or field from memory. Use the Swytchcode
  MCP tools: discover the operation, read its schema with info, then exec.
  Preview writes with dry_run=true.
- If a call fails validation, show the error and stop.

How Swytchcode grounds Cascade in real API schemas

Swytchcode is an execution layer between agents and the APIs they call. Cascade 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 endpoint or field 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 windsurf editor option, swy init merges a stdio MCP entry into ~/.codeium/windsurf/mcp_config.json and writes a WINDSURF.md guidance file. Windsurf's MCP file location now varies by build and agent, so open Cascade's MCP panel to confirm the server appears. If your build reads a different file, use Cascade's option to open the MCP config file and add the same entry there. Reference WINDSURF.md from a rule or AGENTS.md so Cascade loads the guidance.

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

# The loop Cascade follows for any third-party call
swy discover "create a support ticket" --json
swy get <project>
swy add <canonical_id>
swy info <canonical_id>
swy exec <canonical_id>

{
  "mcpServers": {
    "swytchcode": {
      "command": "swytchcode",
      "args": ["mcp", "serve"]
    }
  }
}

On Teams and Enterprise plans, an admin allowlist changes the rules: once any MCP server is allowlisted, every server missing from the list is blocked, and the server ID in the allowlist must match the key in the user's config exactly, including case. Add swytchcode to the allowlist before rolling it out.

What happens when Cascade 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. 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.
• 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.

For internal services, bring the OpenAPI spec. Swytchcode generates a manifest from it, and calls to that service get the same validation and policy checks as catalog APIs.

Where this does not help

Swytchcode validates calls that go out to APIs. It does not review the routes Cascade writes in your own server code. Duplicate endpoints and missing auth middleware are caught by reading existing routes first, contract tests against your OpenAPI spec, and code review. Swytchcode also cannot tell whether a valid value is the right one for your task, so keep dry runs and approvals on writes.

Frequently asked questions

Why does Windsurf Cascade hallucinate API endpoints?
Cascade fills in endpoints and fields from patterns it learned when the provider's spec or your existing routes are missing from its context. Rules and specs in the workspace make a correct first attempt more likely.

Where do Windsurf rules go now?
Workspace rules go in .devin/rules/, with .windsurf/rules/ as the fallback location. The global rules file is ~/.codeium/windsurf/memories/global_rules.md. Each workspace rule sets a trigger in its frontmatter.

Are Cascade memories shared with my team?
No. Auto-generated memories live only on your machine. Put anything the team needs in a rules file or AGENTS.md.

Why is my MCP server blocked in Windsurf?
If your team admin has allowlisted any MCP server, all others are blocked. Ask the admin to add the server using the exact key name from your config.

Does Swytchcode work with Windsurf?
Yes. Run swy init --editor=windsurf to register the Swytchcode MCP server, then confirm it appears in Cascade's MCP panel.

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 Cursor writes outdated API calls: https://www.swytchcode.com/content/cursor-outdated-api-calls
• Why Codex calls the wrong API: https://www.swytchcode.com/content/codex-wrong-api-calls
• Gemini CLI invents API parameters: https://www.swytchcode.com/content/gemini-cli-hallucinated-api-parameters
• 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