What is an API catalog?

Last updated: September 2026

An API catalog is a searchable inventory of an organization's APIs, where each entry records what the API does, who owns it, which version is current, and where its machine-readable description (usually an OpenAPI or AsyncAPI document) and its documentation live. It answers the question every growing engineering team eventually asks: "Do we already have an API for this, and where is it?"

An API registry is closely related. The catalog is the index people browse; the registry is the versioned store that holds the actual API descriptions and serves them to tools. In practice most teams want both, and many products combine them. This guide explains the difference, what belongs in a catalog entry, the IETF standard for publishing a machine-readable catalog, and how to build one that stays accurate.

On this page

• The short answer
• Why API catalogs exist
• API catalog vs API registry vs developer portal vs gateway
• What goes into a catalog entry
• The machine-readable catalog: /.well-known/api-catalog
• Catalogs inside developer platforms
• How to build an API catalog that stays accurate
• Governance: rules, ownership and lifecycle
• Building a catalog with the Scalar Registry
• Common mistakes
• Frequently asked questions

The short answer

• An API catalog is a list of APIs with enough metadata to find, evaluate and start using each one.
• An API registry is the system of record that stores each API's description document, with versions and access control, so other tools (docs, SDK generators, linters, mock servers, AI agents) can fetch it.
• A catalog is only trustworthy if its entries are generated from the registry, and the registry is only trustworthy if documents flow into it automatically from where APIs are built.

Everything else in this guide is about making those three sentences true in a real organization.

Why API catalogs exist

Nobody sets out to have 400 APIs. It happens one service at a time, and the costs show up later.

Duplication. Two teams build two customer-lookup services because neither could find the other's. Both need maintaining forever.

Slow onboarding. A new engineer spends a week asking in chat channels which service owns invoices and where its documentation lives.

Unknown attack surface. Security teams cannot protect APIs they do not know exist. An inventory of every API, with its authentication and owner, is a prerequisite for any serious review.

Broken change management. When a team wants to deprecate an endpoint, they need to know who calls it. A catalog that links APIs to owners and consumers makes that a query instead of an investigation.

Machine consumers. SDK generators, mock servers, contract tests and now AI agents all need a reliable URL for "the current description of this API". An MCP server generated from a stale document gives an agent a stale API.

API catalog vs API registry vs developer portal vs gateway

These four overlap in marketing copy. They do different jobs.

A gateway sees live traffic, which makes it good at discovering undocumented APIs, but it does not know what an API is for. A developer portal is beautifully written but usually covers only the APIs someone decided to publish. The catalog and registry are what tie them together: the gateway config, the portal and the SDKs should all be derived from the same registered description.

What goes into a catalog entry

A useful entry is short. It needs enough to decide "is this the API I want?" and a link to go deeper.

• Name and one-sentence purpose. Plain language, not the service's internal code name.
• Owner. A team, not a person, plus a way to contact them.
• Description document. A stable URL to the OpenAPI or AsyncAPI document, ideally with a "latest" alias and pinned versions.
• Version and lifecycle. Experimental, production, deprecated, retired, with dates for deprecation.
• Audience. Internal, partner or public, which drives who can see the entry at all.
• Authentication. Which security schemes the API uses, taken straight from components.securitySchemes. See OpenAPI security schemes.
• Environments. Base URLs for production, staging and sandboxes, from the document's servers.
• Documentation. A link to the human-readable API reference and guides.
• Derived artifacts. SDK packages, the MCP server, the mock server, the Postman or API client collection.
• Quality signals. Last updated date, lint score against your ruleset, whether contract tests pass.

Notice how much of this is already in the OpenAPI document: title, description, version, servers, security, contact, tags. That is the strongest argument for generating catalog entries from registered documents rather than typing them into a wiki.

The machine-readable catalog: /.well-known/api-catalog

In June 2025 the IETF published RFC 9727, which standardizes a machine-readable API catalog. A publisher serves a document at /.well-known/api-catalog on its domain, and clients (including automated agents) can fetch it to discover the publisher's APIs.

The RFC requires the catalog to be available in the Linkset format, application/linkset+json from RFC 9264. Each entry uses link relations to point at the pieces of an API:

• service-desc for the machine-readable description, such as an OpenAPI document
• service-doc for human-readable documentation
• service-meta for other metadata, such as usage policies
• status for a health or status endpoint

A minimal catalog for two APIs looks like this:

GET /.well-known/api-catalog HTTP/1.1
Host: example.com
Accept: application/linkset+json

{
  "linkset": [
    {
      "anchor": "https://api.example.com/orders",
      "service-desc": [
        {
          "href": "https://api.example.com/orders/openapi.yaml",
          "type": "application/yaml"
        }
      ],
      "service-doc": [
        {
          "href": "https://docs.example.com/orders",
          "type": "text/html"
        }
      ]
    },
    {
      "anchor": "https://api.example.com/billing",
      "service-desc": [
        {
          "href": "https://api.example.com/billing/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        {
          "href": "https://docs.example.com/billing",
          "type": "text/html"
        }
      ]
    }
  ]
}

The response's content type should carry the RFC's profile: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727". The RFC also defines an api-catalog link relation, so a homepage can point at the catalog with a Link header, and it allows catalogs to link to other catalogs when APIs span several domains.

The design choice worth copying is that the catalog does not repeat the API description; it links to it. If you already publish OpenAPI documents at stable URLs, generating an RFC 9727 file is a small build step. It pairs well with the other agent-facing files covered in llms.txt for API docs.

Catalogs inside developer platforms

Internal developer portals often include an API catalog as one section of a wider software catalog. Backstage, the open source developer portal framework, models an API as an entity of kind API with a type, lifecycle, owner and definition:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: orders-api
  description: Create and track customer orders
spec:
  type: openapi
  lifecycle: production
  owner: commerce-team
  system: storefront
  definition: |
    openapi: 3.1.0
    info:
      title: Orders API
      version: 1.4.0
    paths: {}

The definition field can hold the document inline, as above, but inline copies are the fastest way to a stale catalog. Point it at the registered document instead so there is one copy of the truth. The same principle applies to any platform: the catalog should reference the registry, never duplicate it.

How to build an API catalog that stays accurate

Every team that has tried a spreadsheet catalog knows how this goes: it is accurate the week it is created. Accuracy comes from automation, not diligence.

Governance: rules, ownership and lifecycle

A catalog becomes a governance tool when it can answer questions reliably. Three practices make that possible.

Shared rules, versioned. Encode your API style guide as a ruleset and version it like code. Teams extend it rather than copying it, so an update applies everywhere. A rule such as "every document must have info.contact" is how you guarantee every catalog entry has an owner.

Ownership as data. Put the owning team in the document (info.contact, or an extension like x-owner) and require it through linting. Ownership that lives only in a wiki is ownership nobody updates after a reorg.

Lifecycle states with dates. Mark operations or whole APIs as deprecated in the document (OpenAPI has a deprecated flag on operations and, in 3.2, on security schemes), publish the retirement date, and let the catalog show it. Consumers learn about deprecations from the same place they discovered the API.

Building a catalog with the Scalar Registry

The Scalar Registry is a registry first: it stores, versions and serves OpenAPI and AsyncAPI documents, standalone JSON Schemas and Spectral rulesets, with public or private access per resource. Docs, SDKs and MCP servers are built on top of what is registered.

A typical setup has three parts.

Publish from the pipeline. The Scalar CLI validates and publishes a document with a namespace, a slug and an optional version:

npx @scalar/cli document validate api/openapi.yaml
npx @scalar/cli registry publish api/openapi.yaml \
  --namespace acme \
  --slug orders-api \
  --version 1.4.0

In GitHub Actions the same commands run on every push to main, after logging in with an API key stored as a secret. The GitHub Actions guide has a ready-made workflow, including publishing to different namespaces per branch, and there is a GitLab CI guide too.

Share schemas across APIs. When several APIs use the same Address or Money model, publish it once as a Registry schema and reference it from each document, so a change to the shared model is versioned and visible. Why this works so cleanly with OpenAPI 3.1 is covered in JSON Schema vs OpenAPI.

Enforce one ruleset. Store your style guide as a Registry rule and lint every document against it, from the CLI or as a publish gate in Scalar Docs.

From there, the same registered document powers an API reference, generated SDKs and a hosted MCP server, so the catalog entry, the docs and the client libraries all describe the same version of the API. The Free plan includes up to three APIs, and larger limits are on the pricing page.

If you are consolidating from another registry, the SwaggerHub/API Hub migration guide walks through moving documents over.

Common mistakes

Building the catalog by hand. A catalog someone has to remember to update will be wrong within a quarter. Generate entries from registered documents.

Cataloging only public APIs. Internal APIs are where most duplication and most unknown attack surface live. Catalog them, and control visibility with access rules rather than leaving them out.

Storing descriptions inline in the catalog. An inline copy of an OpenAPI document is a fork. Link to the registry.

No owner field. An entry without an owner cannot be deprecated, secured or improved. Make ownership required through linting.

Treating the catalog as a documentation project. Documentation is one output. The catalog's real value is that pipelines, SDK generators and agents can rely on it, which means stable URLs, versioning and access control matter more than page design.

Ignoring AsyncAPI. Event-driven APIs (Kafka topics, webhooks, WebSocket channels) are APIs too. A catalog that only lists HTTP endpoints hides half of how your services talk.

Frequently asked questions

Related

• Learn: Spectral rules · JSON Schema vs OpenAPI · llms.txt for API docs
• Docs: Registry getting started
• Product: Scalar Registry — one versioned home for your OpenAPI documents, schemas and rulesets, feeding docs, SDKs and MCP servers.