API Versioning — AI Glossary

Reference details

Related terms

• Model Version
• OpenAI API
• Anthropic API

How it works

1. Providers pin behaviour differently: some version the model string while keeping the endpoint stable, others version the API itself via a header or path.
2. Model-string versioning means a dated snapshot is addressable, so behaviour is stable until the caller changes the string.
3. API versioning pins the request and response shape, which is a separate axis — the same model can be reached through two API versions.
4. An unpinned alias moves when the provider retires or updates a snapshot, so behaviour changes with no deploy on the caller's side.
5. Deprecation notices are the operative signal, and a pinned snapshot has a retirement date rather than lasting indefinitely.

Example: Two things to pin, and what each protects

Pinning the API version protects the request and response shape: a new field or a changed tool-call structure will not break parsing. Pinning the model snapshot protects behaviour: the same prompt keeps producing comparable output. Pin only the first and a model update changes answers while the code keeps working. Pin only the second and a shape change breaks parsing while answers stay stable. They fail independently, which is why both need pinning and why 'we pinned the version' is an ambiguous claim.

Commonly confused with

Collapsed into one concept when it is two independent axes. The API version governs the contract — fields, shapes, headers; the model version governs behaviour. A provider can hold the first stable for years while the second moves monthly. It is also distinct from a deployment, which some clouds add as a third layer: a named deployment pins a model version inside a resource, so the pin lives in infrastructure rather than in the request. Knowing which layer you pinned determines which class of surprise you are still exposed to.

When to use it

Reach for it when:

• Behaviour must be reproducible across time, which requires pinning the model snapshot.
• Parsing must survive provider changes, which requires pinning the API version.
• Planning for deprecation, since pinned snapshots have retirement dates.

Reach for something else when:

• Assuming one pin covers both axes, which leaves one class of change unprotected.
• Pinning indefinitely without tracking deprecation, which converts a stable pin into a future outage.
• Prototyping, where tracking the latest alias is usually what you want.

Continue your research

Use these connected ModelRefs sections to compare alternatives, inspect implementation paths, and review the evidence and governance boundaries relevant to API Versioning — AI Glossary.

• Browse models
• Review providers
• Inspect benchmarks
• Explore workflows
• Learn AI concepts
• Read decision guides
• Review trust and methodology
• Start a decision path