API strategy
Agent infrastructure
A private API catalog is the internal register of every API a company owns. What it is, why agents change the requirements, and where standard catalogs break.
A private API catalog is the internal register of every API a company owns — its endpoints, owners, versions, auth requirements, and runtime behaviour. It's meant to be the answer to a simple question: what can our own systems do, and how does software reach it?
Most enterprises don't have a real answer. They have a partial answer in the API gateway, a different partial answer in the developer portal, a third one in a Confluence page nobody has updated since Q2, and a fourth one that lives in whichever senior engineer has been around longest. Now agents are calling into these systems, and the gaps are becoming operational problems instead of hygiene problems.
This piece covers what a private API catalog actually is, how it differs from adjacent tools, why the standard implementations break under agent load, and what a version built for the current decade needs to hold. Our view: the catalog is necessary but not sufficient. Cataloguing an API surface that only exposes a small fraction of what your product can do doesn't make agents work. It just makes the gap legible.
A private API catalog is a searchable, governed inventory of the APIs a single organisation owns and operates. "Private" distinguishes it from public developer portals — the catalog is for the company itself, not its customers. It typically holds the OpenAPI or GraphQL specifications, the owning team, environment endpoints, authentication method, rate limit posture, deprecation status, and any tags describing what the API does.
That definition sounds obvious. In practice the term overlaps with three adjacent things, and buyers routinely conflate them.
An API gateway sees what's flowing. A catalog is supposed to describe what exists. A gateway can inform a catalog — the traffic it observes is evidence — but they aren't the same layer.
The catalog is also not the same as internal API discovery, which is the process of finding APIs (often through scanning traffic, code repos, or gateways). Discovery feeds the catalog. The catalog is the durable record.
And it's not the same as an API inventory SaaS product, though several vendors sell tools with that name. Those tools are one way to build a catalog. Building one yourself against your own source-of-truth systems is another.
Internal API sprawl isn't new. What's new is the class of caller. When humans were the only ones reading API documentation, an incomplete catalog was an onboarding tax — annoying, expensive over time, but survivable. New engineers asked around, found the right team on Slack, and got the endpoint. The catalog gap was a productivity problem, not a reliability problem.
Agents don't ask around. When an AI agent needs to check inventory, update a customer record, or trigger a workflow, it consults whatever tool registry the agent runtime has been given. If the right API isn't in that registry — because nobody catalogued it, because the spec drifted, because the team that owns it moved on — the agent either fails, picks the wrong tool, or hallucinates a call that doesn't exist. We covered the specific failure mode in why agents pick the wrong tool.
This shifts the catalog from a nice-to-have to a runtime dependency. Three forces are compounding:
Enterprises didn't need a real catalog before because nothing broke visibly when it was wrong. That's changed.
Every organisation ends up in one of four patterns. Each has failure modes.
The catalog is generated from whatever the API gateway sees. Kong and Apigee natively support this pattern through their service catalog and shadow API discovery features; AWS API Gateway typically requires third-party tooling on top of CloudWatch logs to get equivalent behaviour. In each case, the gateway logs traffic and a discovery job populates the catalog.
This catches everything that flows through the gateway. It misses everything that doesn't — and in most enterprises, that's a significant fraction: internal service-to-service calls, admin endpoints, batch jobs, anything routed through a mesh instead of a gateway. It also confuses "has been called recently" with "exists." Dead APIs vanish from the catalog. Emergency APIs added last week don't appear until traffic hits them.
The catalog is a checked-in collection of OpenAPI specs, sometimes managed through tools like Backstage, Stoplight, or a home-grown Git-backed registry. Every team is supposed to check their spec in and update it on change.
The failure mode is OpenAPI spec drift. Specs go stale within weeks of the last careful update, and there's no runtime signal to prove it. The catalog looks complete; the specs it contains lie.
An agent scans code repositories, running clusters, and gateway logs, then reconciles what it finds. Vendors like Postman and various API security products offer this. It gets closer to a true inventory because it triangulates multiple sources.
It still misses undocumented internal APIs that live inside a monolith and were never designed to be called from outside. Those endpoints exist — they're the ones the UI uses — but they don't announce themselves to scanners. This is directly related to the problem we describe in your APIs expose 2% of what your product can do: the internal capability surface is far larger than the catalogued one.
A platform team owns the catalog and updates it through PRs, tickets, or a governance process. This is what most large enterprises still do behind whatever tool they've bought.
It works for as long as the platform team has the budget. It breaks the first time a reorg splits ownership, or a team ships an API without going through the intake process, or the person who maintained the catalog leaves. Manual catalogs decay at roughly the rate of organisational change, which in most enterprises is fast.
Most real environments use two or three of these in combination. The catalog is a union — which means the union of their failure modes too.
Agents change the shape of the demand on the catalog in ways worth naming.
Coverage becomes binary. A human engineer who can't find an API in the catalog asks a colleague. An agent that can't find a tool either gives up on that path or picks the closest match, which is often wrong. Partial catalog coverage — good enough for humans — is a reliability failure for agents.
Freshness becomes a first-class property. Humans notice when a spec is stale (the sample request 404s and they investigate). Agents don't — they get a JSON error and either retry, hallucinate, or return a wrong answer. The gap between "this catalog entry existed on Tuesday" and "this entry describes the API as it behaves right now" matters more when the caller is a model.
Semantic descriptions start to matter. Traditional catalogs describe the endpoint — path, method, schema. Agents need to know what the endpoint does in language a model can reason about. Tool descriptions for LLM agents is a different discipline from OpenAPI summaries, and most catalogs weren't designed to hold both.
Auth context has to travel. A catalog entry that says "authenticated" is fine for a human reading docs. An agent needs to know which identity to act as, which scopes it needs, and how to obtain the token. This connects to the agent identity vs user identity boundary — the catalog either supports delegated auth patterns or it doesn't, and if it doesn't, security review will find it.
Governance moves from advisory to enforcing. A catalog used for documentation can afford to be a suggestion. A catalog that agents consult at runtime becomes part of the control plane. Private API governance stops being a policy exercise and starts being an availability question.
Pontil doesn't sell a private API catalog, and we'd be sceptical of anyone claiming a catalog alone solves the agent access problem. What we do sell sits one layer up from the catalog: a Tools-as-a-Service platform that generates the tools agents actually invoke, runs them under the authenticated user's identity, and keeps them current as the underlying APIs change.
The connection to catalogs is direct. If the catalog is complete and accurate, tool generation works from clean inputs. If it isn't — and in most enterprises, it isn't — we operate on the systems you own directly: your codebase, your existing APIs, whatever runtime surface exists. That's how we close the gap between what your catalog lists and what your product does.
For teams whose agent projects have stalled at the tools layer rather than the model layer, we wrote up the pattern in why agent projects stall. If you want to see how tool generation works against your actual environment, book a walkthrough.
The honest answer is that most enterprises will spend the next two years rebuilding their private API catalog around agent load, and the ones that treat it as a documentation refresh will do the work twice. The catalog needs to move from a passive record to an active source of truth — one that carries enough semantic detail for agents to select correctly, enough auth context for delegated identity to work, and enough freshness signal that stale entries can't silently mislead a caller.
It also needs to acknowledge what it can't fix. The catalog describes the API surface that exists. It doesn't create the surface. If your product does 100 things and your APIs expose two of them, a perfect catalog of those two APIs doesn't unblock the agent project — it just makes the gap easier to measure. That's useful. It isn't sufficient.
The question worth sitting with: is the private API catalog you're planning going to describe what you have, or is it going to be honest about what you don't?
Stay up to date on the ever changing agentic landscape.
GET STARTED
Start with a 30-minute discovery call
contactus@pontil.com
