Why models hallucinate your API
When Claude or Cursor invents a method your protocol does not have, the cause is usually structural and fixable. Here are the four patterns that produce it.
The short answer
A model does not know your API. It produces the most plausible continuation given what it has read. When it invents a method, it has usually found your surface ambiguous, contradictory, or thin, and filled the gap with the conventions of every other API it has seen.
That makes most hallucinations about your protocol a property of your documentation rather than a property of the model. Which is good news, because it means they are fixable.
Pattern one. The same fact stated more than once
A parameter documented in the quickstart, the reference, and a tutorial will eventually be documented three different ways. One of them was updated, two were not. A human notices the newest page wins. A model sees three variants of a pattern and averages them, or picks the one that appears most often, which is frequently the oldest.
The fix is structural. One canonical statement per fact, everything else links to it. This is the single highest-value change on most documentation sites and it is invisible in a style guide.
Pattern two. Prose where a schema belongs
Describing a response as returning the block with its transactions and a status field asks the reader to construct a shape. A human constructs it approximately and checks against reality. A model constructs it approximately and does not check.
Typed schemas remove the guess. A model given a schema calls the field that exists. A model given a paragraph calls the field that would make sense, which is how you end up supporting questions about methods you never shipped.
Pattern three. Examples that stopped being true
Every documentation site has an example that was correct when it was written. If nothing executes it, nothing tells you when it stopped being correct. It keeps sitting there, getting crawled, teaching an old interface to every model that reads it.
Examples wired into CI fail the release they become wrong. That converts a silent, compounding source of hallucination into an ordinary broken build, which your team already knows how to handle.
Pattern four. Coverage thin enough to interpolate
Where your surface is silent, a model does not stop. It generalises from the hundreds of similar APIs in its training data. If your protocol does something unconventional and you never say so explicitly, the convention wins, and the model confidently describes behaviour you deliberately did not implement.
The fix is to state the unusual thing plainly, in the canonical place, in the words a developer would search for. Silence is not neutral. It is an invitation to interpolate.
Measure it rather than argue about it
All four patterns are testable. Write down the questions your support channel actually receives, ask the models, and count. The wrong answers point at exactly which of the four patterns is producing them, and the count gives you a number to improve against on every release.
That is the whole loop. Baseline, fix the structure, re-measure, keep the measurement in CI. It is unremarkable engineering practice applied to a surface that usually never gets any.
Common questions
- Why does Claude or Cursor invent methods my protocol does not have?
- Because a model produces the most plausible continuation from what it has read. Where your surface is ambiguous, contradictory, or silent, it fills the gap with conventions from other APIs. The invented method is usually the one a conventional API would have.
- Is this the model's fault or my documentation's fault?
- Usually the documentation's. Duplicated facts, prose instead of schemas, untested examples, and thin coverage each produce predictable hallucinations. If a model answers wrong about your API, that is your surface failing, and it is fixable.
- What is the fastest way to reduce hallucinations about my API?
- Deduplicate. Find every fact stated in more than one place, pick one canonical statement, and link everything else to it. Drift across duplicates is the most common cause and consolidation is the cheapest fix.
- How do I know whether it is getting better?
- Count correct answers to a fixed question set drawn from real support questions, before and after. Keep the question set in CI so a release that breaks the surface shows up the same way a failing test does.
Working on something like this?
This is the layer we work in. If you have a hard problem underneath a product, tell us the hard part.