Is Your API Estate Ready for AI?
The API Legacy
There was a moment, roughly a decade ago, when APIs were the answer to everything.
Large organisations were facing a genuine crisis. Mobile had arrived. Digital channels were multiplying. The legacy estate, mainframes, MQ bridges, batch processes, point-to-point integrations, was never designed to be consumed by an app on someone’s phone. APIs were the decoupling layer. The thing that sat between the old world and the new one and made them talk to each other without either side having to fundamentally change.
So organisations built. Bronze, silver, gold tiers. Process APIs that encapsulated sequences of business logic. System APIs that managed CRUD operations against a database or wrapped a mainframe interface behind a REST endpoint. It was pragmatic, it was necessary, and it worked well enough for what it was solving at the time.
Organisational reality took over.
The API estate grew. Teams organised around it. Governance structures formed. Skills concentrated. Politics took root. And the design decisions baked into those early APIs, the bounded contexts that never quite got drawn, the business logic that leaked into process APIs because it had nowhere else to go, the system APIs that became the de facto interface to data nobody fully understood, those decisions calcified.
What large organisations are sitting on today is not a modern API estate. The tooling is modern. API gateways like Apigee, Kong, and AWS API Gateway. Developer portals built on Backstage. OpenAPI specs generated from code. Rate limiting, OAuth flows, usage dashboards. The instrumentation looks current.
What is not modern is what sits behind it. The design thinking, the bounded contexts, the data contracts, the ownership models, the governance approach. Those were set in a different era and have not meaningfully changed. The organisation built a modern front door and left everything behind it exactly as it was.
That is not a modern API estate. That is a new layer of legacy.
The mainframe did not disappear when APIs arrived. It just got a REST interface in front of it.
And now, AI has arrived. The ambitions are real. The investment is flowing. The roadmaps are being drawn. And somewhere in almost every large organisation, a quiet assumption is being made that the API estate is ready for what comes next.
The Assumption
AI has arrived in large organisations the same way most things arrive. With ambition at the top, enthusiasm in the middle, and a set of implicit assumptions that nobody has written down because nobody has thought to question them.
The ambition is genuine. Agents in customer channels. AI-assisted journeys. Intelligent features that reduce friction and increase capability. The investment is real, the roadmaps are published, and the pressure to deliver is building.
What is also real, and almost entirely unexamined, is what those ambitions are sitting on.
A product owner wants to introduce agents into customer-facing channels. The conversation centres almost entirely on the experience layer. What the agent will say, how it will behave, what journeys it will support. The underlying question of what the agent will actually call, what data it needs, what APIs it will depend on, and whether those APIs can support that kind of consumption, rarely gets asked. Not because the product owner is careless. Because the assumption is already made. The APIs exist. They work. That part is solved.
Senior leadership sets the direction. AI capabilities landing within the year. Agents in production. Measurable outcomes against customer metrics. The roadmap is credible and the intent is serious. What is absent from almost every version of this conversation is any mention of API remediation. No workstream to assess fitness for purpose. No investment in refactoring what needs to change before anything meaningful can be built on top of it. The foundation is assumed to be ready because nobody has looked closely enough to discover that it is not.
Engineering leaders carry a different version of the same assumption. An API is an API. The endpoint exists, it returns data, it has been working for years. What difference does it make whether the consumer is a mobile app or an AI agent? The promise gets made. The timeline gets set.
The same assumption plays out across every layer of the organisation, just wearing different clothes depending on who is making it.
The gap between what was promised and what the estate can actually deliver is not even anticipated. And anyone who raises it is not heard as someone identifying a real risk. They are seen as a blocker. This is the messy middle that architecture functions have always occupied, accountable for outcomes they do not fully control, carrying the weight of decisions made above them, and expected to make it work regardless. Edition 1 of this newsletter called it out. Edition 3 named the specific pain of being accountable without authority. The AI wave has not changed that dynamic. It has intensified it.
Part of why the assumption forms so easily is that the visible layer of the API estate looks credible. Modern gateways. Developer portals. OpenAPI specs. OAuth flows. The instrumentation is current because technology upgrades are tangible. You can see them, fund them, and point to them in a slide. What never gets the same treatment are the intangibles. The operating model, the governance, the ownership boundaries, the data contracts. These are harder to visualise, harder to crystallise, and harder to organise against. So they do not get tackled. The front door looks modern. The assumption follows naturally. And the deeper structural reality stays exactly where it has always been.
What Breaks
Here is what nobody is putting in the roadmap.
The process APIs that exist in most large organisations were built for a specific journey. A specific sequence of calls, a specific outcome, a specific consumer. They do not scale functionally beyond the process they were designed for. An AI agent does not follow a predetermined sequence. It reasons, it branches, it retries, it approaches the same endpoint from a different direction depending on what it is trying to accomplish. The process API has no answer for that. It was never asked the question.
Behind those process APIs, the system APIs are doing something that looks clean on a diagram but is not. The back end is returning system codes, status values, and attributes that carry meaning only if you know how to decode them. That decoding logic has no single home. Sometimes it lives in the API layer. Sometimes in the channel. Sometimes split across both in ways that made sense to the team that built it and nobody else. It was never placed in the right layer or the right context deliberately. It accumulated. And the knowledge of how to interpret it lives not in documentation but in the organisation itself. In teams, in individuals, in the institutional memory of people who have been there long enough to remember why a particular code means what it means. An AI agent cannot inherit any of that.
Which brings the documentation problem into sharper focus. In most large organisations the API documentation is a legacy artefact. Written at the point of build, not maintained as the implementation evolved, and authored for a human developer who could read between the lines, raise a ticket, and ask someone on Slack. It is not machine readable in any meaningful sense. It is not precise enough to reason from. And because the implicit knowledge was never externalised, the documentation does not even know what it is missing.
Compounding this is a problem of bounded context and semantics. The APIs in most large estates were not designed around clear domain boundaries. A customer in one API is not necessarily the same concept as a customer in another. An account balance means something subtly different depending on which system API you are calling and what processing has or has not been applied to it. These ambiguities were navigable when a developer could investigate and a product team could define the rules for their specific journey. They are not navigable when an agent needs to reason across multiple APIs and draw reliable conclusions from what it gets back. Semantic clarity was never a design requirement. It is about to become one.
When something goes wrong, the error model compounds the problem further. Enterprise APIs return errors designed for a developer to debug manually. Generic codes, unhelpful messages, and the particular pattern of returning a 200 with an error buried in the payload. A developer learns to look for it. An agent reasoning about whether to retry, escalate, or take a different path has nothing useful to work with.
The rate limiting adds another layer. APIs were throttled for human-paced mobile traffic. Predictable call volumes, predictable sequences, predictable timing. An agent orchestrating across multiple APIs within a single reasoning loop does not behave that way. It will hit limits that were never designed for this kind of consumption, in ways that are difficult to predict and harder to diagnose.
And underneath all of this sits a more structural problem. The security and consent models were built assuming a human is in the loop. OAuth flows, token scopes, delegated access, consent frameworks. They were designed for a person authorising an action. An agent acting autonomously on behalf of a user breaks those assumptions in ways most organisations have not yet confronted, let alone resolved.
None of these are engineering problems in isolation. They are the accumulated result of an API estate built for one era being asked to carry the weight of the next one. The ambition is real. The gap is also real. And the distance between the two is not going to close by pointing agents at endpoints and hoping for the best.
The Foundations
None of what follows is an exhaustive list. The full scope of what needs to change across a large organisation’s API estate to make it genuinely fit for AI consumption cannot be covered in a single edition. What is laid out here are five foundations. The things that have to be worked through before anything else can be reliably built on top.
Bounded context and semantic clarity
What does this API actually represent? Is a customer here the same concept as a customer in the next system? What processing has been applied to this balance before it was returned? These questions were always present. They were navigable by humans who knew where to look. A machine reasoning across multiple APIs cannot navigate ambiguity. It will either get it wrong or fail. Semantic clarity is not a nice to have. It is a prerequisite.
Contract integrity
The documentation was written at the point of build, has drifted from the implementation, and was never designed to be machine readable or precise. Closing that gap is not a documentation exercise. It is a question of trust. Can an AI agent depend on what this API says it will do? Until the answer is yes, reliably and verifiably, the API is not a foundation. It is a risk.
Externalising implicit knowledge
The decoding logic, the system codes, the interpretation rules that make the API estate intelligible live in people and teams, not in the right layer of the architecture. Surfacing that knowledge, deciding where it belongs, and keeping it there requires organisational will and governance discipline. In large organisations that is consistently harder than any engineering work that follows it.
Consumption-aware design
A mobile app calls specific endpoints in a specific sequence at human pace. An AI agent reasons, branches, retries, and orchestrates across multiple APIs in ways the current estate was never designed for. Granularity, error semantics, response structures, and rate limiting all need to be reconsidered for a non-deterministic, machine-paced consumer. Some of that is configuration. Some of it is a rebuild.
Security and identity for autonomous consumers
The current models assume a human is in the loop. A person authenticates, consents, and takes responsibility. An agent acting autonomously breaks every one of those assumptions. Who is it acting as? What is it permitted to do? What happens when it acts on something it should not have? These are not questions an adjusted OAuth flow can answer. They require a rethink of how access, consent, and accountability work when the consumer is a machine.
These five are the starting point, not the full picture. Before a large organisation’s API estate becomes genuinely consumable for an AI-first application or agent-based architecture, there is a wider set of structural considerations that also need to be confronted.
Data quality and consistency. APIs return data but the quality, completeness, and consistency of that data was never a hard requirement when a human was interpreting it on a screen. An agent reasoning from poor or inconsistent data will not flag that something looks wrong. It will just proceed.
Discoverability. Current API catalogues and developer portals were built for human browsing. An agent needs to find the right API for the right purpose programmatically. That requires a level of metadata, tagging, and semantic description that most enterprise catalogues do not have.
Support and observability model. When an agent fails mid-journey the current support model, built around developer tickets and human-paced debugging, has no meaningful answer. Real-time observability and the ability to trace what an agent was doing at the point of failure are not optional additions. They are operational requirements.
Testing and validation frameworks. Current QA models were designed for predictable, human-defined test cases. Testing an API that will be consumed by a non-deterministic agent requires a fundamentally different approach. Most organisations do not have one.
Auditability and lineage. When an agent takes an action through an API, the organisation needs to be able to trace exactly what was called, with what data, and what was returned. In regulated industries this is not a technical preference. It is a compliance requirement that the current estate is largely unprepared for.
The Long Haul
None of what has been laid out in this edition is a quick fix. Working through the five foundations, let alone the broader set of structural considerations, is a multi-year undertaking for most large organisations. It requires a strategy with real commitment behind it, clear accountability, and the organisational clarity to sustain effort through the inevitable friction of touching things that have not been touched in a decade.
That is hard. It will be resisted. The same forces that calcified the API estate in the first place, the politics, the ownership ambiguity, the instinct to add rather than change, will show up again. And the pressure to deliver AI capabilities quickly will make it tempting to work around the problem rather than through it.
Which is where the real risk sits. Not in failing to adopt AI. But in adopting it in a way that papers over what was never fixed. A capable AI layer sat on top of an unreformed API estate is not transformation. It is the same pattern repeated. The mainframe got a REST interface in front of it. The legacy APIs get an AI interface in front of them. People congratulate themselves for delivering AI instrumentation. The organisation believes it has achieved AI transformation.
The promised outcomes remain as far away as ever. The debt stays.
