Add: Use AI to keep your API service catalog current

learn/ai-for-docs/ai-keep-api-service-catalog-current.md

@@ -0,0 +1,110 @@
+---
+seo:
+ title: Use AI to keep your API service catalog current
+ description: Use AI to flag stale, orphaned, and zombie catalog entries, then pair it with Scout ingestion and Reef publishing so your API catalog stays trustworthy.
+---
+
+# Use AI to keep your API service catalog current
+
+Most catalogs start out accurate. A team ships a first pass, tags every service, and finds an owner for each row. Then months pass: two teams merge, a service gets deprecated but keeps its `active` tag, and a new microservice never makes it into the inventory because nobody remembered to add it.
+
+None of this shows up as one dramatic failure. It shows up as a developer who calls a retired endpoint because the catalog still lists it, or an AI agent that picks the wrong version because both look equally current to a model that only reads what the catalog says.
+
+This article covers why catalogs decay after launch and how to use AI, alongside automated ingestion, to keep the catalog close enough to reality that people, and agents, can trust it again.
+
+## Why catalogs decay after launch
+
+Catalogs decay for predictable reasons: when a team reorganizes, the owner field on several services quietly points at someone who moved to a different group, and when two squads ship similar wrappers around the same datastore, nobody marks one as the canonical version. A service that gets deprecated in code often keeps its `active` tag in the catalog, because updating the catalog was never part of the deprecation checklist. [Why API catalogs are critical for agentic software development](https://redocly.com/blog/api-catalogs-agentic-software) argues that treating a catalog as static documentation turns it into a liability once AI agents rely on it: an agent will call whatever the catalog says is available, including a "zombie API" that a human developer would have known to avoid.
+
+The stakes are real even before agents enter the picture: that same post models return on investment for a well-maintained catalog at roughly 24:1 to 52:1, and cites Australia Post cutting its developer portal bounce rate from 30 percent to under 2 percent after automating catalog updates. Neither number depends on AI, but both depend on the catalog staying accurate enough that people trust it on the first visit.
+
+## Signals that a catalog entry has drifted from reality
+
+A handful of concrete tells separate a current catalog from a decaying one. Watch for:
+
+- The last deploy date on a service is newer than the last time its catalog entry changed.
+- The listed owner has moved teams, and nobody transferred the field.
+- A tag still reads `active` for an endpoint that already returns a deprecation notice or redirects to a newer version.
+- Two entries describe the same resource under different names, the kind of overlap covered in [Use AI to find duplicate and underused APIs in your codebase](https://redocly.com/learn/ai-for-docs/ai-find-duplicate-underused-apis).
+- Nothing has queried an entry in months, but nothing marks it as a candidate for retirement either.
+
+Any single tell is a small fix. Several at once mean the catalog has stopped reflecting the services it claims to describe, so the fix needs a process, not a one-time edit.
+
+## Automate ingestion before you automate review
+
+AI can help with a currency review, but it cannot substitute for fresh inputs. If the source list of services is already stale, a model will confidently review the wrong world. [Scout](https://redocly.com/docs/realm/scout) collects API definitions directly from repositories, so a review starts from files that changed last week rather than an export someone pulled at the start of the quarter. [What is Scout?](https://redocly.com/docs/realm/scout/what-is-scout) covers how that collection runs on a schedule instead of by request.
+
+Manual updates cannot keep pace with how fast most teams deploy, so the delay between a code change and a catalog reflecting it has to stay close to zero. Once ingestion is automated, AI has something worth reviewing: real deploy and traffic signals, not a spreadsheet someone half remembers.
+
+## Use AI to flag staleness, not to decide it
+
+Give a model the Scout inventory plus whatever deploy, traffic, or ownership signals your systems track, and ask it to flag candidates rather than make the call. A model is good at spotting patterns across hundreds of rows at once, but it should not decide on its own that a service is safe to deprecate, because that decision needs context only an owner has.
+
+### Prompt skeleton for a currency review
+
+```markdown {% process=false %}
+You are reviewing an API catalog for currency, not correctness.
+
+Rules:
+- Do not mark anything as deprecated. Flag it for a human decision.
+- Cite the specific signal for every flag (deploy date, traffic count, owner status).
+- If a signal is missing, say so instead of guessing.
+
+For each catalog row below, return: entry_id, flag_reason, confidence.
+
+[paste table of entry_id, last_catalog_update, last_deploy_date, owner, recent_traffic]
+```
+
+Review the output the way you would review any generated content: in a pull request, next to the catalog row it touches, so the flag and the fix travel together.
+
+## Before and after: a catalog entry nobody had touched in a year
+
+Before:
+
+```yaml {% process=false %}
+title: legacy-payments-svc
+owner: jsmith (left team in 2025)
+status: active
+last_reviewed: null
+```
+
+After:
+
+```yaml {% process=false %}
+title: Legacy payments API (v1)
+owner: payments-platform-team
+status: deprecated
+successor: payments-api-v2
+last_reviewed: 2026-07-14
+```
+
+The after version still needs a human to confirm the successor mapping before anyone points a new integration at it. AI can draft the flag and the fields, but it cannot verify that the replacement covers every behavior the old service handled.
+
+## Build a recurring currency check, not a one-time cleanup
+
+A cleanup project fixes the catalog once. A recurring check keeps it that way, so run the AI-assisted review on a schedule tied to your Scout ingestion instead of waiting until search returns a dead endpoint. Assign a rotating owner who clears flags weekly, the same way a team rotates on-call.
+
+### Checklist before you trust the catalog again
+
+- Every flagged entry names a specific signal, not a vague sense that it looks old.
+- Deprecated services point to a documented successor.
+- Owner fields resolve to a current team, not an individual who may have moved on.
+- Entries with zero recent consumers are marked for review rather than silently removed.
+
+Deterministic checks can carry part of this load once you have a cadence in place. [Use AI to detect drift between your docs and your live API](https://redocly.com/learn/ai-for-docs/ai-detect-drift-docs-live-api) covers Respect's scheduled Arazzo workflows, which catch behavioral drift on individual endpoints, and [Catch API drift with the new proxy and drift commands](https://redocly.com/blog/catch-api-drift) covers a newer way Redocly CLI compares recorded traffic against a spec. Both complement a catalog-level review instead of replacing it.
+
+## Best practices
+
+Log every AI flag with its signal in the pull request that fixes it, so an audit can reproduce the decision later.
+
+Configure how deprecated entries surface through [API catalog configuration](https://redocly.com/docs/realm/config/catalog-classic), so search stops recommending a retired service on its own.
+
+Treat every AI flag as evidence, not a verdict. Owners still confirm before any status changes.
+
+## What AI cannot verify alone
+
+AI cannot see a service's live traffic unless you paste it into the prompt, and it cannot confirm that a successor API truly replaces the one it is retiring. It may also misjudge a slow-moving but still-critical internal tool as stale. Scout ingestion and a human owner remain the source of truth; AI only narrows the list of rows worth a second look.
+
+## How Redocly can help
+
+A catalog that nobody trusts stops getting used, no matter how complete it once was. [Reef](https://redocly.com/reef) hosts the searchable catalog where enriched metadata, ownership, and deprecation status live in one place, so an AI-assisted currency review has somewhere real to publish its results instead of a spreadsheet that goes stale again next quarter. Pair a Scout ingestion schedule with a recurring review, and Reef becomes the centralized single source of truth your team, and your agents, can actually rely on.

learn/ai-for-docs/sidebars.yaml

@@ -28,6 +28,8 @@
   label: Use AI to find duplicate and underused APIs in your codebase
 - page: ai-build-searchable-api-catalog.md
   label: Use AI to build a searchable API catalog for your team
+- page: ai-keep-api-service-catalog-current.md
+  label: Use AI to keep your API service catalog current
 - page: ai-help-developers-find-understand-apis.md
   label: Use AI to help developers find and understand your APIs faster
 - page: ai-check-terminology-consistency-across-docs.md