An API catalog is a structured inventory of every API your organization runs, with enough metadata (owner, version, schema, status) that people and software can find an interface, understand it and decide whether to use it. A good one is generated from the same files that define your APIs, so it never drifts. A catalog kept by hand goes stale within a quarter.
This guide covers what belongs in a catalog entry, how a catalog differs from a developer portal and from API management, how to validate and retire entries, and how to use a catalog to expose tools to AI agents and MCP clients.
TL;DR
-
An API catalog is the inventory: what exists, who owns it, what version, what schema. A developer portal is the curated storefront built on top of it.
-
Every entry needs machine-readable fields (name, version, owner, schema, visibility, lifecycle status), not just a prose description.
-
Catalogs rot when entries are typed by hand. Generate them from the specs or manifests that already define your APIs, and fail the build when an entry is invalid.
-
RFC 9727 gives you a standard place to publish a machine-readable catalog:
/.well-known/api-catalog. -
AI agents and MCP clients need the same thing humans do: a precise schema for each tool, served consistently.
Table of Contents
-
Catalog, developer portal and API management: three different jobs
-
Using a catalog to find tools, including AI agent and MCP tools
What an API catalog is, and the problem it solves
Think of a catalog as the table of contents for your API estate. It lists each API, links to its specification, names the team responsible, and records where it sits in its lifecycle: draft, active, deprecated, retired.
The problem it solves is sprawl. As companies grow, teams ship endpoints, internal services, webhooks and scripts nobody else knows about. A catalog makes a large API estate visible, which helps reduce sprawl and surface undocumented or forgotten interfaces that may be less protected. That is a security argument as much as a convenience one: you cannot review, patch or retire what you cannot see.
For developers, the day-to-day payoff is simpler:
-
Discovery. Before writing a new endpoint, you check whether one already does the job.
-
Ownership. When something breaks, you know which team to ask.
-
Safe change. You see who depends on a version before you change it.
-
Onboarding. A new engineer gets a map instead of a scavenger hunt.
Catalog, developer portal and API management: three different jobs
These three terms get used interchangeably, and that is where many projects go wrong. They overlap in the metadata they use, but they serve different audiences.
| API catalog | API developer portal | API management / gateway | |
|---|---|---|---|
| Main job | Inventory and governance | Discovery and onboarding for consumers | Runtime control of traffic |
| Main audience | Platform teams, architects, security | Internal developers, partners, customers | Operations, security, platform |
| Typical contents | Every API, including drafts and internal ones | Curated, approved APIs, tutorials, SDKs, access requests | Policies, rate limits, keys, analytics |
| Source of truth | Specs, manifests, ownership data | Selected catalog entries plus documentation | Gateway configuration |
One way to put it: a catalog may hold draft, internal or restricted APIs that should never be public, while a portal combines selected catalog metadata with tutorials, SDKs, support and an access workflow. The gateway is a runtime enforcement point, and is not automatically your catalog or your portal.
If you searched for an API developer portal, the practical advice is the same: build the catalog first, then publish a filtered view of it as the portal. A portal with its own hand-maintained list becomes a second source of truth, and two sources of truth disagree.
What belongs in a catalog entry
A catalog entry that is only a name and a paragraph of prose helps nobody and cannot be consumed by software. Aim for a small, strict set of fields.
Identity and ownership
One published example of a catalog implementation defines an API metadata structure with fields such as name, version, owner, team, tags and visibility. That is a sensible baseline. Add a stable identifier that never changes when the display name does.
Contract
Link to, or embed, the machine-readable contract: an OpenAPI document for HTTP APIs, a JSON Schema for the inputs and outputs of a function or tool. The contract is what lets a consumer, a code generator or an AI agent use the API without reading a wiki page.
Lifecycle and audience
Record status (draft, active, deprecated, retired), the date of the last change, and who may see the entry. Visibility matters because the same catalog often feeds both an internal view and a public portal.
A sample entry
Here is the shape we would use for a tool-style entry:
{
"id": "uuid-generator",
"name": "UUID Generator",
"version": "1.0.0",
"owner": "platform",
"status": "active",
"visibility": "public",
"tags": ["utility", "generation"],
"inputSchema": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"description": "How many UUIDs to generate",
"minimum": 1,
"maximum": 100
}
},
"required": ["count"]
},
"outputSchema": {
"type": "object",
"properties": {
"uuids": {
"type": "array",
"items": { "type": "string" }
}
}
},
"surfaces": ["web", "cli", "api", "mcp", "embed", "vscode"]
}
Notice what is not in that entry: the code. A catalog entry is metadata, not implementation — it describes the contract, not the function that fulfils it. That is true of every catalog.
What is different here is where the metadata comes from. In a conventional setup, this entry would be a separate record someone maintains next to the actual implementation: a row in a database, a file in a registry, a page in a wiki. In NexusBloom, this entry is the top half of the tool file. The bottom half is a single pure function, coreLogic(input), which takes the object described by inputSchema and returns the object described by outputSchema. The manifest and the function ship together, are versioned together, and are signed together.
That is why the entry cannot drift. There is no second document to update, because the catalog record and the behaviour are the same artifact. The listing is the code.
Publishing a catalog machines can find: RFC 9727
Catalogs are not only for people. RFC 9727, published in 2025, describes the API catalog document as primarily machine-readable, meant to make automated discovery and use of APIs possible. It defines an api-catalog link relation and a well-known location. The target resource may be /.well-known/api-catalog or any other URI the publisher chooses, and the catalog is served as a Linkset with, at minimum, hyperlinks to API endpoints.
In practice that means a client, a crawler or an agent can fetch one predictable URL on your domain and learn what you offer. If your organization spreads APIs across several domains, the same RFC covers pointing from one catalog to others, so decide which domain hosts the canonical list.
How to build a catalog from one source of truth
Most catalog projects fail the same way. Someone creates a spreadsheet or a wiki page, fills it in during a burst of enthusiasm, and six months later half the entries are wrong. The fix is structural: the catalog should be a build output, not a document people edit.
A common architecture has three layers: API sources feed a catalog core that processes and indexes specifications, and a developer portal consumes that data for discovery and interaction. Here is how to apply it.
-
Pick the authoritative artifact. For each API, decide which file defines it: an OpenAPI document, a JSON Schema, a manifest in the repo. That file, and nothing else, is the truth.
-
Ingest on every change. A pipeline step reads those files on merge and updates the catalog. No manual copy.
-
Normalize. Parse each source into one internal shape, so an OpenAPI file and a tool manifest end up as comparable entries.
-
Index for search. Names, tags, owners and descriptions should be searchable, because discovery is the whole point.
-
Render views. The portal, the machine-readable
/.well-known/api-catalogdocument and any internal dashboard are all views of the same data.
The same logic, many surfaces
There is a deeper version of this problem that catalogs expose. Often the same piece of logic is exposed as a web form, a CLI command, an HTTP endpoint and an AI agent tool, each written separately. The catalog then lists four entries that are supposed to behave identically and, over time, do not. A validation rule gets fixed in the API and not in the CLI. The agent tool accepts an input the web page rejects.
The cleaner design is to define the logic once and generate the surfaces from it. Then the catalog entry is derived from the same definition as the behavior, so the listing and the reality cannot disagree.
Validate, version and retire entries
A catalog is only trusted if its entries are correct. Treat entries like code.
Validate before you store
The published guidance is consistent here: validate specifications before storing them, parse them into a normalized form, index them for search, and implement versioning, access control and documentation generation. A rejected entry should fail the pipeline with a clear message, the same way a failing test does.
Useful checks, all automatable:
-
The schema is valid JSON Schema or a valid OpenAPI document.
-
Required fields (owner, version, status, visibility) are present.
-
The owner resolves to a real team.
-
The version is higher than the last published one when the contract changes.
-
Examples in the documentation validate against the schema.
Governance as gates, plus a thin human layer
One practitioner recommendation is to make governance mostly automated gates, with a thin human layer, using machine-checkable standards such as OpenAPI contract requirements and pipeline linting. That matches experience: a review board that reads every spec does not scale, while a linter that blocks a bad spec in seconds does. Keep humans for the judgment calls: naming, breaking changes, new public APIs.
Version and retire with a published rule
Versioning without a retirement policy produces a graveyard of old endpoints. The same source suggests a published retirement rule: deprecated versions keep running for a fixed window, deprecation is announced in responses and in the catalog, and shutdown happens once consumer traffic falls near zero. Whatever window you pick, write it down and show deprecation status in the catalog entry itself, so consumers see it where they look first.
Using a catalog to find tools, including AI agent and MCP tools
Human developers browse a catalog. AI agents query one. The requirements overlap more than you might expect.
An agent that calls a tool needs to know its name, what it does in a sentence, which inputs it takes and their types, and what comes back. That is exactly the content of a good catalog entry with a JSON Schema contract. Weak or missing schemas are why agent tools behave unpredictably: the model guesses at inputs, and the implementation behind the tool may differ from the one the web page uses.
When you add agent-facing tools to your catalog:
-
Write tight input schemas. Required fields, enums for fixed choices, clear descriptions on every property.
-
Keep the description honest and specific. It is what the model reads to decide whether to call the tool.
-
Make the tool deterministic where you can. A pure function with the same input giving the same output is easy to test and to trust.
-
List the tool once. The same entry should describe the web, CLI, API and agent forms of the logic.
For developers who discover tools through MCP directories and community forums, a clean catalog entry is also your listing: it is what makes a tool understandable in thirty seconds.
Where NexusBloom fits
NexusBloom is built for the case where one piece of logic has to live in several places. You write one file: a JSON Schema manifest plus one pure function. We serve that file as a web page, a CLI command, an API endpoint and an AI agent tool, with the same schema and the same execution everywhere. The point is that your tool no longer behaves differently depending on where it runs.
That matters for a catalog because the manifest is already the machine-readable entry: name, input schema, behavior. You are not maintaining a listing next to the code. The listing and the code are the same file.
There are three plans on the pricing page: Free, Creator at €9 per month, and Pro at €29 per month. If you want to see what a single-source tool looks like before committing, the free online developer tools are a good place to start, and the JSON Formatter is handy for cleaning up the schemas you write along the way.
When you are ready to define your first tool once and serve it everywhere, start from the NexusBloom home page and pick the plan that fits your project.
Perspective
Most teams treat the catalog as a documentation problem. We think it is a duplication problem. Every time a team describes a tool in a wiki, then implements it for the web, then again for the CLI, then again as an agent tool, they create four things that must agree and one more document claiming they do.
The catalog that stays accurate is the one that is a by-product of the code. When the schema is the manifest, and the manifest is what runs, the entry cannot be out of date, because there is nothing separate to update.
That is the idea behind NexusBloom: one JSON Schema manifest, one pure function, every surface generated from it. For anyone building AI agent integrations, this is the difference between a tool that behaves the same in a chat client, a terminal and an API call, and one that surprises you in production. We built it so that reliability is the default, not a review step.
Benjamin
A practical rollout plan
You do not need a platform team of ten to start. A sensible sequence for a company of 20 to 200 engineers looks like this.
Week one: inventory
List every API, service and tool you can find. Use gateway logs, repository searches for OpenAPI files and a short survey of team leads. Record owner and status only. Do not try to document everything yet. The goal is to learn how big the estate is and how many entries have no owner.
Weeks two to four: automate the top ten
Pick the ten most-used APIs. Make sure each has a machine-readable contract in its repository, then wire the pipeline step that ingests it. Add the validation checks from the section above. This proves the flow end to end on real data.
Month two: publish views
Expose the machine-readable catalog at a predictable URL, following RFC 9727 if you want standard discovery. Then publish a filtered portal view for the audiences who need it, with only approved entries.
Ongoing: governance and retirement
Add lint rules as you learn what goes wrong. Publish the deprecation window. Review entries with no traffic and no owner every quarter.
For solo developers and small teams the same steps shrink: a single directory of manifests, one validation script and one generated index page is a catalog. The principle does not change with size.
Common mistakes
-
Starting with a tool purchase instead of a data model. Decide the required fields first. Any catalog is only as good as its metadata.
-
Listing only public APIs. Internal and forgotten interfaces are where the visibility gain is largest.
-
No owner field enforcement. An entry nobody owns is an entry nobody updates.
-
Treating the portal as the catalog. The portal is a view. Keep the inventory separate and complete.
-
Prose-only descriptions. If software cannot read it, agents and automation cannot use it.
-
No retirement policy. Without one, deprecated versions live forever.
FAQ
What is the difference between an API catalog and an API developer portal?
A catalog is the complete inventory of your APIs, used mainly by platform, architecture and security teams for governance. A developer portal is a curated, consumer-facing view that adds tutorials, SDKs and access workflows. Build the catalog first and generate the portal from it.
What should an API catalog entry contain?
At minimum: a stable ID, name, version, owner or team, tags, visibility, lifecycle status and a link to the machine-readable contract such as OpenAPI or JSON Schema. Fields like these let both people and software find and evaluate an API without asking anyone.
Is there a standard for publishing an API catalog?
Yes. RFC 9727 defines the api-catalog link relation and the well-known path /.well-known/api-catalog, with a Linkset format that lists API endpoints. Publishing there lets automated clients discover your APIs from your domain.
How do you keep a catalog from going stale?
Generate it from the specs or manifests in your repositories, validate every entry in the pipeline, and require an owner. When the catalog is a build output rather than a hand-edited document, updates happen as a side effect of shipping code.
Can AI agents use an API catalog?
Yes, if entries carry precise machine-readable schemas. An agent needs a tool’s name, a clear description and typed inputs. A consistent definition across web, CLI, API and agent surfaces keeps behavior predictable wherever the tool runs.