API versioning
API versioning is the practice of publishing changes to an API under explicit version identifiers — a URL path segment like /v2/, a request header, or a date-based version — so existing integrations keep working while the interface evolves. A versioning policy defines what counts as a breaking change, how versions are selected per request, and how long older versions remain supported.
Version drift is a leading cause of agent hallucination against real APIs. A model's training data contains older documentation; if the current docs do not state the version prominently and mark deprecated surfaces clearly, an agent will confidently generate calls against endpoints that no longer exist. The hallucinated-endpoint support ticket often traces back to exactly this gap.
Agents need version mechanics stated as facts they can act on: which identifier selects a version, what the default is when none is sent, and where the changelog records what moved between versions. A changelog written as concrete before-and-after changes doubles as a correction signal — it tells a model precisely which of its priors are stale.
Date-based versioning with per-account pinning adds a subtlety worth documenting explicitly: two integrators can hit the same URL and get different behavior, which an agent cannot discover empirically.
What does an AI agent make of your API?
Find out in about a minute — no signup.
Discry your API — free