# Why Cursor Hallucinates API Calls Without a Spec

**Short answer:** An agent hallucinates an API call because it is predicting the next token, not reading your server. Without a contract, it fills in the endpoint, parameters, and body from patterns and partial code. The call is the most plausible guess, not knowledge. Giving it a machine-readable contract is the direct fix.

## Why the guesses are so convincing

REST APIs follow conventions. Paths are plural nouns, methods are predictable, and bodies mirror the resource. A model trained on millions of codebases produces a call that fits the convention perfectly, which is why it passes review and fails at runtime. The convention is the camouflage.

## Where the guesses break

- **Paths:** the real endpoint is `/v2/orders` or uses a verb the model did not expect.
- **Field names:** the API uses `billing_address` and the model writes `address`.
- **Types:** an id is a string in the API and a number in the guess.
- **Auth:** the header name or scheme is different from the default.

## Why a contract changes the behavior

With the OpenAPI file compiled into tools, the agent does not predict the endpoint. It reads the operation, takes the typed arguments, and makes a call that is valid by construction. The model is still predicting, but it is predicting over a correct description instead of a remembered pattern.

## What does not fix it

More chat context helps only if it is current and complete, which it rarely is. A maintained contract is the only artifact that is both authoritative and machine-readable.

This is part of the [Powerduck vs Cursor comparison](https://www.powerduck.com/blog/powerduck-vs-cursor/). Continue with [the API testing workflow](https://www.powerduck.com/blog/cursor-api-testing-workflow/).