How to Find Undocumented API Endpoints in Your Codebase

A security questionnaire arrives from a prospective enterprise customer. Question 14 asks for a list of every API endpoint that handles personal data, along with its authentication method.

The platform lead starts in the spec repo. The gateway dashboard reports a different total, because two internal services were wired up before the gateway existed and never moved behind it. Someone greps for route decorators across the monorepo and gets a third number, this one including a debug replay handler a contractor added two years ago that still resolves in production.

Four hours later there is a spreadsheet and an uncomfortable answer at the bottom of it: nobody knows. Not through negligence. The information was never in one place, and the place it came closest to complete was the source code, which nobody was reading as an inventory.

The short answer. An undocumented API endpoint, often called a shadow API, is a route that exists in running code but appears in no specification, catalog, or gateway configuration. The dependable way to find them is to analyze the repository itself: parse route registrations from source, recover request and response schemas from validators and serializers, and generate an OpenAPI 3.1 document for anything that has no spec.

Key takeaways

• Cloudflare's 2024 API Security and Management Report found that machine learning discovery surfaced 30.7% more API endpoints than organizations self-reported.
• OWASP ranks the problem directly: API9:2023 Improper Inventory Management covers shadow, deprecated, and undocumented endpoints.
• Salt Security research published in June 2023 reported a gap of up to 40% between hand-written OpenAPI definitions and what is actually deployed.
• Postman's 2025 State of the API Report, surveying more than 5,700 respondents, found only 24% of developers design APIs with AI agents in mind.
• A complete inventory has to answer four things: what exists, how good each endpoint is, who calls it, and how the answer stays current after the next commit.

Why are undocumented API endpoints a bigger problem now?

For a decade the standard complaint about API documentation was that it lagged the code. That is a developer experience problem with a developer experience cost: an engineer loses an afternoon, files a ticket, moves on. Three shifts turned the same gap into something a security or platform team owns.

Agents read specifications literally. A developer who hits an endpoint with a missing description reads the handler or asks in Slack. An agent does neither. Under the Model Context Protocol specification, a client discovers what a server offers through a tools/list call and selects a tool by reading its name, title, description, and input schema. Where a description is thin or a type is loose, the model chooses wrong, at machine rate rather than once. That is the substance behind the term agent-ready API: complete schemas, documented auth, and descriptions written for a reader who cannot ask a follow-up question. It is also where most specs break for agents, usually well before anyone gets to an MCP launch.

Response size became a cost line. An endpoint returning an unbounded array is a pagination bug when a browser calls it. When an agent calls it, every returned field is tokens in a context window on every invocation. Payload design became a budget decision as much as a latency one, and it stays invisible until someone measures it per endpoint.

Inventory is a control, not a nicety. OWASP's API9:2023 entry covers hosts and endpoints that exist without documentation or oversight, including old versions still connected to live data. Salt Security's June 2023 analysis of the same category found undocumented endpoints exposing PII in real deployments.

Stack those together and the failure mode changes shape. A stale doc costs an hour. An endpoint that no inventory lists, no owner claims, and no auth guards is an unbounded surface, and once a hosted MCP server sits in front of the same service, it is a surface reachable by anything holding a key.

What should an API inventory actually tell you?

This framework holds regardless of tooling. An inventory that cannot answer all four leaves you guessing during an incident or a migration.

1. What exists. Every route in every service, including internal admin handlers, debug endpoints, and v1 paths still serving traffic. Coverage has to be exhaustive rather than curated, because the endpoints nobody remembers are exactly the ones that generate incidents.
2. How good each endpoint is. A route appearing in a catalog says nothing about whether it can be safely consumed. Design quality, auth posture, schema completeness, and payload behavior need per-endpoint measurement rather than a project-level maturity score.
3. Who calls it. Deprecation without a caller list is a guess, and so is a breaking change. The inventory has to map each endpoint to the frontend pages, internal services, partners, and agents that depend on it, and flag the ones with no callers at all.
4. How it stays current. Any inventory maintained by hand is stale by the second sprint, because updating it is a second job nobody is measured on. It has to be derived from something that cannot fall out of date, which in practice means the code.

Question one is the only one most teams attempt, and they usually attempt it with a spreadsheet.

How do you build an API catalog from source code?

Answering all four questions from code rather than from a spec file is the design principle behind Elva by Theneo, which builds an API catalog directly from repository code. It maps cleanly onto the framework above.

Discovery runs in three passes. First it fingerprints the frameworks in use. Second it walks every route registration it can prove is reachable. Third it recovers request and response schemas from validators and serializers. Where a specification already exists it is imported and diffed; where none exists, one is written, and the output is OpenAPI 3.1 you can commit. Framework coverage includes Express, NestJS, FastAPI, Flask, Spring, Go via net/http, chi and gin, and Rails. Monorepos activate several extractors at once, and Elva reports that the average repository activates 2.3 of them.

That produces question one. Questions two and three come from what happens afterward. Endpoints are labeled automatically by domain, authentication requirement, and data sensitivity, with labels such as PII, no auth, unpaginated, deprecated, and breaking change, then grouped into collections; the labels are editable. Consumption mapping traces each endpoint to the frontend pages, internal services, and MCP clients calling it, and flags endpoints with no callers anywhere. Each endpoint then receives an A–F grade across design, developer experience, AI readiness, security, and performance, with a concrete suggested fix attached to each finding.

Elva's published example scan of a demo repository shows the shape of a first result: 214 endpoints found, 131 existing specs imported, 83 generated, 31 endpoints with no callers, 4 exposing PII with no auth defined, and one unpaginated list endpoint costing roughly 4,100 tokens per agent call. Those are figures from Elva's own example scan rather than customer benchmarks.

Spec-first inventory versus code-derived inventory

• Undocumented endpoints. A spec-first inventory cannot see them, because absent from the spec means absent from the inventory. A code-derived one finds them, because discovery starts at route registrations rather than at a file.
• Drift. Spec-first drift accumulates quietly between the document and the deployed service. A spec regenerated from source cannot drift from the code it was built from.
• Maintenance. Spec-first is a recurring manual task competing with feature work. Code-derived is a rescan, with no human step in the loop.
• Consumer visibility. Spec-first does not model callers at all; they are tracked separately or not tracked. Code-derived reads them from call sites.
• Agent readiness. Spec-first tells you the specification is valid, and a lint-clean spec can still be unusable by an agent. Code-derived scores each endpoint on whether an agent could actually use it.

One honest limitation. Static analysis cannot see routes registered dynamically at runtime, and consumption is only ever as complete as its inputs, so a caller that touches neither your connected repositories nor your gateway stays invisible. Runtime traffic analysis covers part of that blind spot, and the two approaches complement each other rather than compete.

What can you do once every endpoint is in one place?

Deprecation gets a caller list. Retiring a v1 endpoint stops being an announcement followed by a wait. You know which services and agents still call it, so the conversation happens with named owners, and the strategies you use for safer API releases get a real dependency list to work from rather than an assumption.

Breaking changes get attached to commits. When the catalog rescans on every commit, every added, changed, and removed endpoint is recorded against the commit that caused it, with breaking changes flagged. A changelog becomes a byproduct of merging rather than a document someone remembers to write, which is the whole case for automating changelogs.

Scoring becomes a backlog rather than an audit. An organization-level maturity score tells you how you are doing and gives you nothing to do on Monday. A per-endpoint grade with a suggested fix sorts the surface weakest-first, which is a queue. That matters most where agent traffic concentrates, because any tool schema an agent reads is only as reliable as the endpoint definition underneath it.

A catalog should also be an origin rather than a destination. Scored endpoints export to OpenAPI 3.1, Postman collections, SDKs, documentation sites, and hosted MCP servers, which keeps a derived inventory from becoming one more place that has to be kept in sync by hand.

Is an API catalog the same thing as API documentation?

No, and the two get conflated constantly. A catalog is the internal inventory; documentation is the published surface. Theneo covers API documentation: API references, guides, developer portals including private per-customer portals, changelogs, real-time co-editing, llms.txt, and Ask AI for developers who want an answer instead of a search result. Elva covers API management: discovering endpoints, scoring them, mapping consumers, and governing what each audience can reach. The announcement post explaining how Elva fits alongside Theneo covers the split in more detail.

The distinction matters operationally, not just commercially. Publishing excellent documentation for the endpoints you know about tells your readers something true about a subset and nothing at all about the rest, and the endpoints missing from your documentation are usually the ones missing from your security review too.

Where to start

Pick the security questionnaire, the deprecation you keep postponing, or the agent integration a partner is asking for, and try to answer it from what you have today. The gap between the answer you can produce and the answer you need is the size of your inventory problem, and it is usually larger than the team's estimate.

Elva is currently in waitlist access. If you want to see this run against your own repository, you can join the Elva waitlist and connect a repo.