{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to find duplicate and underused APIs in your codebase","description":"Combine Reef API Scout discovery with structured AI review to spot overlapping endpoints and low-use services before you consolidate.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-find-duplicate-and-underused-apis-in-your-codebase","__idx":0},"children":["Use AI to find duplicate and underused APIs in your codebase"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Large organizations often discover the same capability twice because teams ship in parallel. You can run a discovery audit that starts with inventory from Reef API Scout, then uses a model to group similar endpoints and flag APIs with weak ownership or usage signals. The pairing keeps facts grounded while AI handles pattern matching at scale, which matches the broader lifecycle in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-modern-api-docs"},"children":["How AI fits into modern API documentation"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-api-sprawl-shows-up-late","__idx":1},"children":["Why API sprawl shows up late"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Microservices, acquisitions, and partner integrations all add routes. Without a catalog, duplicate payment or profile APIs can coexist for years. Underused services still incur security review and on-call load. The pain appears when a new team rebuilds something that already exists, or when compliance asks for a complete API list you cannot produce quickly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sprawl is rarely malicious. Two product lines may both need a customer record, so each ships a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/customers"]}," surface with slightly different fields. A partner integration copies an internal spec and never syncs again. Platform teams inherit repos they did not author, so nobody feels safe deleting the older variant. Discovery work pays off when you can show overlap with evidence instead of asking teams to merge on faith alone."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-scout-gives-you-before-ai","__idx":2},"children":["What Scout gives you before AI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/scout/what-is-scout"},"children":["What is Scout?"]}," describes how Redocly Scout collects API definitions from repositories so you are not guessing from memory. Deploy and operate collection using the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/scout"},"children":["Scout documentation"]}," and review ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/scout/use-cases"},"children":["Scout use cases"]}," for common estate layouts. Scout answers which APIs exist and where their specs live. It does not by itself decide which duplicates to retire."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat Scout output as the allowlist for AI review. If a path never appears in inventory, the model should not invent it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"inputs-for-an-ai-assisted-duplicate-review","__idx":3},"children":["Inputs for an AI-assisted duplicate review"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Export or paste a table of services with path prefixes, OpenAPI titles, owners, and optional traffic or consumer counts when your platform provides them. Add business context in a short paragraph: which domains are strategic, which systems are legacy-only, and whether multiple versions are intentional."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example row: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payments-v2"]}," POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/charges"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing-legacy"]}," POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payment/charges"]}," both owned by different teams, last deploy 18 months apart."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prompt-skeleton-for-overlap-and-usage-signals","__idx":4},"children":["Prompt skeleton for overlap and usage signals"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are reviewing an API inventory for duplicate or underused APIs.\n\nGiven the table below:\n1. Group endpoints that appear to implement the same capability (name the cluster).\n2. Flag APIs with no clear owner or stale metadata.\n3. Note version pairs that look like unmigrated duplicates.\n4. List APIs that look underused based on the usage column (if present).\n5. Suggest one consolidation question per cluster for human owners.\n\n[paste inventory table]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep clusters small enough that owners can respond in one meeting."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signals-models-often-surface","__idx":5},"children":["Signals models often surface"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models frequently cluster near-duplicate paths that differ only by prefix or verb choice. They also highlight parallel major versions when v1 and v2 both accept writes. Shadow APIs appear when OpenAPI exists in a repo but the service is not linked from any catalog entry. Underuse shows up when consumer counts are zero or when an API has rich spec text but no recent deploys. Treat every cluster as a hypothesis until owners confirm."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"duplicate-patterns-worth-naming-in-the-prompt","__idx":6},"children":["Duplicate patterns worth naming in the prompt"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ask the model to label clusters so owners recognize the pattern quickly:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Pattern"},"children":["Pattern"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it looks like"},"children":["What it looks like"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Typical owner action"},"children":["Typical owner action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Twin resources"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Two CRUD surfaces on the same noun"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pick one canonical API, deprecate the other"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Version fork"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["v1 and v2 both writable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Freeze v1, document migration"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shadow spec"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OpenAPI in git, no runtime owner"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Archive or attach to a service"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dormant API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No consumers in telemetry"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sunset or merge into a shared platform API"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When telemetry is missing, say so in the prompt. The model should flag uncertainty instead of ranking APIs as unused without data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"turning-findings-into-a-consolidation-backlog","__idx":7},"children":["Turning findings into a consolidation backlog"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rank clusters by customer impact and operational cost, not by spec similarity alone. For each accepted duplicate, record the canonical API, the deprecation window, and the doc redirect plan. Publish the result in your catalog configuration so search surfaces the winner, as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/config/catalog-classic"},"children":["API catalog configuration"]},". The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/blog/api-catalogs-agentic-software"},"children":["API catalogs for agentic software"]}," article explains why a single searchable layer matters when both humans and agents consume your estate."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n A[Scout inventory] --> B[AI cluster review]\n B --> C[Owner decisions]\n C --> D[Reef catalog update]\n D --> E[Deprecate duplicates]\n","diagramHtml":"","diagramHtmlDark":""},"children":["graph LR\n A[Scout inventory] --> B[AI cluster review]\n B --> C[Owner decisions]\n C --> D[Reef catalog update]\n D --> E[Deprecate duplicates]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The loop runs quarterly or after major acquisitions, not only once."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":8},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start from collected specs, not from chat memory about what exists."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ask owners for one sentence on why two similar APIs both exist before you schedule decommission."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Track consumer migrations explicitly when you retire a duplicate."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log model clusters with links to spec files so auditors can reproduce the review."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Share audit results in the same channel where architects already discuss standards, so consolidation does not feel like an surprise security review."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Time-box AI review to clusters under twenty APIs per pass. Larger batches produce vague groupings."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you publish winners in the catalog, add a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["successor"]}," field in metadata so search surfaces the replacement immediately."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-discovery-cannot-replace","__idx":9},"children":["What discovery cannot replace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["AI does not see private traffic dashboards unless you paste aggregates, and it cannot sign deprecation notices for partner APIs. Scout coverage is only as complete as the repositories you connect. Political ownership disputes still need human negotiation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":10},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Scout to inventory the estate, use structured AI passes to propose duplicate and underuse clusters, then let owners decide what to merge. Publish the canonical APIs in Reef so the next team finds one front door instead of three."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":11},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/reef"},"children":["Reef"]}," brings API Scout discovery and catalog publishing together so duplicate reviews turn into a maintained source of truth rather than a one-off spreadsheet."]}]},"headings":[{"value":"Use AI to find duplicate and underused APIs in your codebase","id":"use-ai-to-find-duplicate-and-underused-apis-in-your-codebase","depth":1},{"value":"Why API sprawl shows up late","id":"why-api-sprawl-shows-up-late","depth":2},{"value":"What Scout gives you before AI","id":"what-scout-gives-you-before-ai","depth":2},{"value":"Inputs for an AI-assisted duplicate review","id":"inputs-for-an-ai-assisted-duplicate-review","depth":2},{"value":"Prompt skeleton for overlap and usage signals","id":"prompt-skeleton-for-overlap-and-usage-signals","depth":2},{"value":"Signals models often surface","id":"signals-models-often-surface","depth":2},{"value":"Duplicate patterns worth naming in the prompt","id":"duplicate-patterns-worth-naming-in-the-prompt","depth":3},{"value":"Turning findings into a consolidation backlog","id":"turning-findings-into-a-consolidation-backlog","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What discovery cannot replace","id":"what-discovery-cannot-replace","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to find duplicate and underused APIs in your codebase","description":"Combine Reef API Scout discovery with structured AI review to spot overlapping endpoints and low-use services before you consolidate."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-find-duplicate-underused-apis","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}