{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-build-a-searchable-api-catalog-for-your-team","__idx":0},"children":["Use AI to build a searchable API catalog for your team"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A spreadsheet of service names is not a catalog. Developers need descriptions, owners, tags, and stable links they can search. You can use AI to enrich metadata across many OpenAPI files, then publish the result in Reef so the catalog stays current as specs change. That workflow extends the AI plus validation pattern in ",{"$$mdtype":"Tag","name":"Link","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":"lists-versus-catalogs","__idx":1},"children":["Lists versus catalogs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A list answers what is deployed. A catalog answers what it does, who owns it, and how to call it safely. Search fails when titles are opaque (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal-svc-7"]},") or when the same product has three names across repos. Metadata is the difference between findability and guesswork."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Think of search as matching intent to records. Intent might be I need to refund a subscription or Which API owns webhooks. Without summaries and tags, search falls back to filename guessing. A catalog row should read like a helpful librarian card, not like an infrastructure ticket title."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"metadata-ai-can-enrich-safely","__idx":2},"children":["Metadata AI can enrich safely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models are strong at drafting short descriptions from paths and schemas, proposing tags from domain language, and normalizing display names when you supply a style note. They are weak at inventing owners or SLAs. Paste real ownership from your service registry when you have it, and ask the model only to format or shorten."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fields worth enriching in bulk:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Human-readable summary (one to two sentences)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Domain tags (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payments"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lifecycle stage (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["experimental"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stable"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Links to primary OpenAPI file and runbooks"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a contact or team channel when your service catalog already stores it. Search results that end in a dead end teach developers to ignore the catalog."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prompt-skeleton-for-bulk-enrichment","__idx":3},"children":["Prompt skeleton for bulk enrichment"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are enriching API catalog metadata for internal developers.\n\nRules:\n- Do not invent owners or on-call handles; leave blank if missing.\n- Use sentence case for titles.\n- Keep summaries under 40 words.\n\nFor each API row below, return JSON with: title, summary, tags, lifecycle.\n\n[paste table of api_id, path_prefix, openapi_excerpt, owner_if_known]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review JSON in a pull request like any other generated content."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-and-after-on-catalog-fields","__idx":4},"children":["Before and after on catalog fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"title: orders-svc\ndescription: \"\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"title: Orders API\ndescription: Create and track customer orders for the retail storefront.\ntags: [orders, commerce]\nlifecycle: stable\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The after block still needs a human to confirm accuracy against the live service."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ingest-enrich-and-publish","__idx":5},"children":["Ingest, enrich, and publish"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Collect specs with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/realm/scout"},"children":["Scout documentation"]}," and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/realm/scout/what-is-scout"},"children":["What is Scout?"]}," so enrichment starts from files in git, not from stale exports. Configure how APIs appear in the portal using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/realm/config/catalog-classic"},"children":["API catalog configuration"]},". Tune findability with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/realm/config/search"},"children":["Search configuration"]}," once metadata lands."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n A[OpenAPI in repos] --> B[Scout collect]\n B --> C[AI metadata pass]\n C --> D[Human review]\n D --> E[Reef catalog publish]\n","diagramHtml":"","diagramHtmlDark":""},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Re-run enrichment when major paths change, not on every typo fix."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"search-and-natural-language-questions","__idx":6},"children":["Search and natural-language questions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Structured search uses tags and titles. Natural-language questions work better when summaries mention tasks (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refund a subscription"]},") not only resource names. The ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/blog/api-catalogs-agentic-software"},"children":["API catalogs for agentic software"]}," post describes why rich metadata helps both people and agents choose the right API on the first try."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You do not need a custom chatbot on day one. Start with faceted search by tag and owner, then add assistant features when metadata quality is stable. If answers cite the wrong API, fix the catalog row before tuning the model. Garbage in still produces confident wrong answers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"questions-to-test-after-publish","__idx":7},"children":["Questions to test after publish"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ask five colleagues to find an API without Slack help:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How do I create a webhook for billing events?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Which API owns user invitations?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Where is the sandbox base URL documented?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What is deprecated in payments this quarter?"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Who owns the identity service on call?"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Misses become metadata tickets, not one-off doc edits buried in a random repo."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"checklist-before-you-turn-on-broad-search","__idx":8},"children":["Checklist before you turn on broad search"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Every catalog entry links to a canonical OpenAPI file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deprecated APIs are labeled and point to replacements"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Owners or team channels are present for stable APIs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sensitive internal-only APIs are flagged in metadata"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":9},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Batch enrich by domain so reviewers stay in context."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep a banned-phrase list (internal codenames) in the prompt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Diff enriched YAML in CI so drift is visible."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pair catalog updates with Scout collection schedules."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Assign a metadata owner per domain who approves AI suggestions weekly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store enrichment prompts in git next to the glossary so changes are reviewable."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an API ships, block merge unless catalog metadata updates in the same pull request as the OpenAPI change."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limits-of-generated-metadata","__idx":10},"children":["Limits of generated metadata"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generated text can misstate behavior if the spec is thin. Models may over-tag APIs when prompts are vague. Search quality still depends on engineers maintaining specs after enrichment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your organization also runs API design reviews, feed catalog gaps back into those reviews. A missing description in the catalog often means the OpenAPI ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]}," was empty when the service shipped. Fixing upstream specs keeps AI enrichment from repeating the same blank template every quarter."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":11},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat catalog metadata as a product: collect specs, enrich with grounded AI, review in git, and publish in Reef with search tuned for how your developers ask questions. Revisit catalog quality when teams complain they cannot find an API, not only when Scout adds new repositories."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":12},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/reef"},"children":["Reef"]}," hosts the searchable catalog and Scout collection so enriched metadata stays tied to the repositories your teams already maintain."]}]},"frontmatter":{"seo":{"title":"Use AI to build a searchable API catalog for your team","description":"Enrich API metadata with AI at scale and publish a searchable Reef catalog your developers can browse or query in natural language."}},"tagList":[],"title":"Use AI to build a searchable API catalog for your team","lastModified":"2026-05-22T12:10:40.000Z"}