API Versioning for an AI-First Platform

API versioning is a solved problem, right? Stick a version number in the URL, maintain backward compatibility for a deprecation period, document breaking changes, sunset old versions after giving consumers time to migrate. Straightforward.

It is straightforward when your API consumers are human developers who can read a changelog and update their code. It is less straightforward when one of your primary API consumers is an AI agent whose "code" is a prompt with tool definitions that behave differently from traditional software consumers.

Our APIs serve three distinct consumers, and each has a different relationship with breaking changes.

The three consumers

Mobile apps. Our iOS and Android apps consume APIs through a typed client library. When we make a breaking change, we release a new app version that uses the updated API. Users update at their own pace. Some update immediately. Some do not update for months. This means old API versions must stay alive for a long time. Mobile app update cycles mean old API versions persist for months after a new version ships.

Web app. Our the web framework web client is always on the latest version because we deploy it centrally. Breaking changes take effect as soon as we deploy. No backward compatibility window needed for this consumer.

AI agent. The agent consumes APIs through tool definitions in its prompt. When an API changes, the tool definition must be updated to match. But here is the wrinkle: the AI agent is more sensitive to response format changes than human UIs are.

A human UI can tolerate a new field in an API response. The UI simply ignores fields it does not know about. An AI agent might not ignore them. If a new field appears in the response and the agent's tool definition does not mention it, the agent might misinterpret the response, hallucinate meaning for the new field, or change its behavior in unpredictable ways.

Conversely, if we remove a field that the agent's tool definition expects, the agent might fail silently (ignoring the missing data) or fail loudly (producing an error response). Neither failure mode is acceptable for a system that handles financial transactions.

Our versioning strategy

We use an additive-only approach for response formats. We add new fields but never remove or rename existing ones. When a field needs to change semantically, we add a new field with the new semantics and deprecate the old one. The deprecated field continues to return data for the entire deprecation period.

This is more conservative than what most API versioning guides recommend, but it is necessary when an AI agent is in the consumer set. The cost of a subtle agent behavior change caused by a response format tweak is much higher than the cost of carrying an extra deprecated field for a few months.

For request formats, we are similarly conservative. New optional parameters are fine. New required parameters are never added to existing endpoints. If a new required parameter is needed, we create a new endpoint version.

Feature flags over version numbers

For AI-specific changes, we prefer feature flags over API versions. Here is why.

When we want to test a new behavior in the AI agent (a different ranking algorithm, a new search strategy, a modified response format), creating a new API version is heavy. It requires updating the agent's tool definitions, testing the integration, and managing two versions simultaneously.

Feature flags are lighter. We can enable new behavior for a percentage of requests, monitor the results, and roll back instantly if something goes wrong. Feature flags enable AI experiments without API version changes.

For example, when we tested a new flight ranking algorithm, we did not create a v3 of the search endpoint. We added a feature flag that toggled between the old and new ranking on the server side. The API contract stayed the same. The response format was identical. Only the ordering of results within the response changed. The agent's tool definition did not need updating.

This approach works because the flag controls server-side behavior, not the API contract. The consumer (whether human UI or AI agent) sees the same response structure regardless of which flag variant is active.

Deprecation with the mobile tail

Our deprecation timeline is driven by our slowest-updating consumer: the mobile app. When we mark an API version for deprecation, we set a timeline of at least six months. During that time, we monitor which app versions are still calling the deprecated API. We send push notifications to users on old app versions encouraging them to update. We only shut down the deprecated version when active usage drops below a threshold.

For the AI agent, updates happen much faster. When we update a tool definition, the change takes effect on the next agent invocation. There is no update cycle to wait for. This asymmetry means the agent is always on the latest API version while mobile apps may be several versions behind.

We maintain a compatibility matrix that tracks which API version each consumer is using. The matrix makes it easy to see which deprecated APIs still have active consumers and which can be safely shut down.

Documentation for two audiences

API documentation must be machine-readable for AI tool calling. This is the requirement that most API teams do not think about.

Human developers read documentation to understand how to use an API. They look at examples, read descriptions, and use the API reference to construct requests. They can handle ambiguity and fill in gaps with common sense.

AI agent tool definitions need precision. Every parameter must have an exact type, a clear description of valid values, and explicit optionality. Enum values must be listed exhaustively. Default values must be specified. Constraints (minimum, maximum, format) must be documented in the schema, not just in the prose.

We auto-generate tool definitions from our API schema. This ensures the tool definition always matches the actual API behavior. When an engineer adds a new parameter to an endpoint, the schema update automatically propagates to the tool definition. No manual synchronization. No drift.

The auto-generation has a downside: the generated descriptions are sometimes too terse for the AI agent to use effectively. We supplement the auto-generated definitions with hand-written descriptions that give the agent richer context about when and why to use each tool. These descriptions live alongside the schema and are reviewed as part of any API change.

Versioning an API for an AI-first platform is not a fundamentally new problem. It is the same old versioning problem with a new, unusually demanding consumer. The principles are familiar: be conservative about breaking changes, maintain backward compatibility, communicate deprecation clearly, and test thoroughly. The difference is that your most demanding consumer cannot read a changelog, cannot tolerate ambiguity, and will fail in subtle, hard-to-detect ways if you get it wrong.

Treat the AI agent as the consumer you design for first, and every other consumer benefits from the rigor.

Nowah is an AI travel agent that searches and books real flights and hotels through conversation — no filters, no thirty open tabs. Plan your next trip.