The Definitive Guide to API Governance

I spend most of my week in customer meetings. Platform leads, enterprise architects, heads of developer experience, people running risk or compliance for organizations with hundreds of teams and thousands of APIs. The agenda varies. Once we get past the slide deck, it's the same conversation almost every time.

It usually goes like this. Governance was supposed to make the portfolio defensible, and it hasn't. A wiki exists. A review board exists. Standards are documented somewhere. APIs in production don't pass the standards. Nobody can produce the inventory without a project. An AI initiative is now waiting on work that should have already been done. The person across from me has lived through a version of this once or twice already, and they're about to be asked to fund the next attempt.

The picture I draw on the whiteboard in that meeting is the picture this document is built around. The API has a lifecycle that runs from design through retirement, and the platform should cover all of it. Governance is the framework inside that platform that makes sure what gets shipped at each stage is what the organization actually intended. The catalog is where the readiness signal lives: conformance, quality, ownership, lifecycle stage, all in one place. Consumers (internal teams, partners, agents) pick up what the catalog has certified. The artifact partners and agents pick up is the artifact governance produced.

An API starts as a design decision. Someone writes a spec or a piece of code. It moves into development, picks up tests, gets reviewed, ships to production, finds consumers, gets versioned as those consumers ask for changes, and eventually retires when something newer takes its place. That pattern holds whether the API was authored by a developer twenty years into their career or generated by an agent five minutes ago.

Postman is the platform the team uses at every stage. Specs live in Postman. Collections live in Postman. Tests run from Postman. Monitors observe what production is doing. The catalog shows what exists. The same surface that supports the developer at design time supports the platform team at distribution time.

Governance is what happens inside that platform to make sure the API arriving at each stage is the API the organization intended. It's the framework that sits alongside the API at every step. It's the work that turns a draft spec into something fit for consumers to pick up.

Three scenarios from the last few months illustrate what this looks like when the platform underneath the work isn't the platform the team is actually using.

These aren't isolated cases. They're the predictable output of a structural problem. The API is being built, shipped, consumed, and called by agents on a platform that has no shared source of truth, no inventory consumers can trust, and no enforcement at the point of authoring. Every stage runs on a different tool with a different opinion about what the API is.

Four forces are pushing this from a multi-quarter improvement program into a board-level liability.

The rest of this document walks the picture in order. The catalog first, as the foundation everything else stands on. Then governance setting the bar as the spec is being written, with the catalog accumulating the readiness signal. Then the consumer half of the platform drawing from the certified catalog. Then the feedback loop that closes the cycle. Then four concrete steps to take this month.

The first thing every organization discovers when they start a governance program is that they don't know what they have. The wiki is stale. The spreadsheet has been forked seven times. The architect who knew the most has moved teams. Production has APIs in it that nobody can name an owner for. The audit can't finish because the audit can't enumerate the surface. The recurring shorthand for it across the architects I sit with is treasure hunt and tribal knowledge, and that's exactly the state the catalog is meant to end.

This is the moment the program scope usually turns out to be wrong. At one Fortune 500 retailer I worked with, a portfolio review surfaced hundreds of ungoverned collections that hadn't previously been listed. The platform team had been planning against an estimate that was off by an order of magnitude. Leadership had to recalibrate the budget before the program could actually start.

Cataloging is the work of building a current inventory of every API in production, with its owner, spec status, test coverage, consumer surface, and posture against the standards the organization has agreed on. The catalog is the foundation everything else stands on. A standard you can't map to a real API is a standard you can't enforce. A program you can't scope is a program you can't fund.

This is also where the shape of the answer changes from what most organizations have built. The reflex is to keep two things separate: an inventory document for the platform team, and a discovery surface for developers and consumers. In every case I've seen those two things diverge inside one quarter, and the divergence is permanent. The fix is to consolidate them onto one source so the inventory the platform team is auditing is the same inventory leadership is reviewing and the same inventory developers are searching against.

In Postman, this is Spec Hub doing the design and the API Catalog holding the result. Spec Hub supports OpenAPI (2.0, 3.0, and 3.1), AsyncAPI 2.0, protobuf (2 and 3), and GraphQL specifications. The Postman CLI runs the same governance rules in CI as the merge gate, so the catalog refreshes continuously instead of only at audit time. API Catalog accumulates ownership metadata, lifecycle stage, conformance summaries from Spec Linting, endpoint health from runtime observation, and CI/CD pipeline status (GitHub Actions, GitLab CI, Jenkins).

The other thing the inventory work does is set up the producer/consumer split that the rest of the document keeps returning to. The catalog has two jobs. The first is to be the live inventory which this section covers. The second is to fill that inventory with the readiness signal that turns it into a verdict consumers can trust.

Once the portfolio is visible, the question moves to quality. The standards the organization has written down (naming conventions, error formats, versioning policy, authentication patterns, ownership metadata) need to mean something at the point the spec is being authored. This is the work that turns the inventory into a readiness signal.

Governance does this work in two layers, and the rewrite of every program I've helped run is about getting both layers working together.

The first layer is rules. Governance rules on the Spectral foundation fire against the spec as the developer authors it, and the same rules run in CI as the merge gate. The built-in rule library ships with Postman's API governance guidelines, Zalando's RESTful API and event guidelines, and Postman's OWASP API guidelines. Custom rules extend the library with the conventions specific to the organization, written following Spectral guidelines. Both run at the same enforcement points: inline in Spec Hub as the developer authors, and again in the Postman CLI as the merge gate. The rule a developer sees in the editor is the rule that blocks the build. Rules version with the workspace, so when the standard changes the change propagates automatically; nothing depends on a Confluence page being updated.

This is the moment the doom loop usually breaks. The teams that have closed this gap publicly describe the same shift, moving governance out of a parallel review queue and into the same continuous integration system the application code already runs through.

The second layer is broader. Pass or fail on a rule is a useful signal but a limited one. A spec can pass every rule and still be a bad API. It might lack documentation. It might have inconsistent schemas across endpoints. It might mix authentication patterns. It might paginate one resource one way and a similar resource another way. None of these things break the lint check, but all of them break the consumer.

This is where the catalog's conformance summary becomes load-bearing. API Catalog's Spec Linting produces a conformance summary for every API: the spec quality score, and rule violations grouped by severity. That's the actual product surface. Paired with endpoint health (latency, error rates, request volumes), test coverage, and CI/CD pipeline status, that summary is what I use with customers to talk about whether an API is fit for any consumer (human or agent). The shorthand I use in customer meetings is agent readiness: documentation completeness, schema consistency, authentication standardization, pagination predictability. An API that scores well on those is by definition usable by a human developer, a partner integration, an internal team, and an agent. The agent is the hardest consumer, and the bar is calibrated to that.

Postman's 2025 State of the API Report, drawing on responses from over 5,700 developers, architects, and executives, found that only 24 percent of developers actively design APIs with AI agents in mind. Sixty percent still design primarily for human consumption, and 16 percent haven't considered AI agents as API consumers at all. The mismatch is in the data: 89 percent of developers use generative AI in daily work, 51 percent of organizations have deployed AI agents (with another 35 percent planning to within two years), and 50.8 percent of developers cite unauthorized agent calls as their top security concern. APIs are being consumed by agents that the APIs weren't designed for.

Test coverage and performance data sit alongside the conformance summary. Tests authored in the workspace run in CI through the CLI alongside contract tests, integration tests, and AI-generated test suites. Postman Monitors run the same Collections in production from multiple regions. Postman Insights observes how real consumers (human or agent) actually call the API. None of these signals lives in isolation. Each one is a partial view of how ready a given API is for the consumers who'll eventually pick it up.

The catalog is where all those signals come together. For each API in the portfolio, the catalog carries the conformance summary, spec quality score, test coverage, endpoint health, CI/CD pipeline results, lifecycle stage, owner, and consumer surface. When a platform lead asks whether an API is ready to publish, the answer comes from the catalog. When an AI team asks whether an API is safe to expose to an agent, the answer comes from the catalog. When an auditor asks whether the controls were operating at the time of an incident, the answer comes from the catalog.

This is also where the agent question gets answered without a second framework. An agent producing a spec sees the same rules a developer sees. Agent Mode applies the governance rules to AI-generated specs the same way they apply to human-authored ones. The agent that produces the spec sees the same violation feedback the developer would, in line, before the spec is committed. The standard holds regardless of who is authoring, because the catalog measures conformance in the same way for both.

Governance Groups handle the case where one bar doesn't fit the whole organization. The docs call them governance groups: groupings of workspaces with their own configured rule set. A regulated business unit may need to run at a stricter severity than an internal experimentation team. The same governance runtime applies; the rules get different teeth depending on which governance group the workspace belongs to.

Some standards aren't lint rules. They're secret-handling rules. Postman Vault lets developers store sensitive values as vault secrets locally (Postman Local Vault) or link to external vaults like 1Password, AWS Secrets Manager, Azure Key Vault, and HashiCorp Vault through Vault integrations, so credentials don't need to live in collections or environments at all. The Postman Secret Scanner monitors public workspaces and published documentation for exposed secrets across all plans, with broader workspace coverage on the Advanced Security Administration add-on. BYOK encryption lets organizations on the Advanced Security Administration add-on manage their own encryption keys through AWS KMS. These aren't themselves governance rules, but they're what makes governance defensible for regulated industries that can't tolerate a credential ending up in the wrong place.

Distribution is what happens when consumers pick up the APIs the catalog has certified.

There's a clean line between the two halves of the platform, and the way I draw it on a whiteboard is the most useful picture in the conversation. Producer side: design in Spec Hub, governance rules firing, tests running, monitors observing, conformance summaries accumulating in the catalog. Consumer side: Internal workspaces (the catalog surface for internal teams, feeding the Private API Network), Partner workspaces (curated B2B surfaces with workspace-level access controls and multi-partner mode), the Postman API Network (fed by Public workspaces the organization chooses to publish), and the Postman MCP server (giving coding agents context to work with the platform).

The structural idea this section keeps returning to is simple. The artifact stays the same as it moves outward; only the access scope changes. An API in an Internal workspace, a Partner workspace, or the Postman API Network is the same API, with the same governed spec, the same conformance summary, and the same lifecycle stage. The workspace type is the access decision rather than a second specification of the API.

Internal teams find APIs through Internal workspaces that draw from the API Catalog and surface through the Private API Network. The search-and-fork experience that should have been there from the beginning. The Slack-thread discovery process goes away. The duplicate-API problem from the inventory work goes away with it. Every duplicate I've ever seen forensically untangled was the product of a developer who couldn't find the canonical version and decided to rebuild faster than they could search. The catalog fixes the search problem at its root.

The metric here is discoverability time: the median time from "I need an API for X" to first successful call. Single-digit minutes is the bar to aim for. Most enterprises measure this in days or weeks. Every minute above the bar is a minute a developer spends searching, and search time is the leading indicator of duplicate APIs.

B2B partners arrive through Partner workspaces. Curated slices of the catalog scoped to specific partners, with workspace-level access controls. Postman supports multi-partner mode, where one workspace can be shared with multiple partners. A partner browsing a Partner workspace is browsing a subset of the catalog the organization has chosen to expose to them. The governed spec they see is the governed spec the catalog certified. Per-partner activity metrics let the platform team see what partners are actually calling.

Partner-facing distribution also needs an SDK experience that meets developers in the language stacks they actually write in. SDK Generator produces typed client libraries from a single OpenAPI spec in six languages: TypeScript, Python, Java, PHP, Go, and C#. When the spec changes, the SDKs regenerate. The artifact partners pick up is the artifact governance produced. The spec doesn't fork into a separate documentation artifact. The documentation, the SDKs, and the portal all read from the spec the catalog certified.

The Postman API Network surfaces the catalog to the external developer ecosystem, fed by Public workspaces the organization chooses to publish. Same governance, same catalog, broader audience. The Run in Postman button extends each entry into any developer's existing Postman session, which lowers the barrier to a first call from "set up an environment" to "click a button."

Agents are the newest consumer category, and they're the one organizations most often haven't designed for. The Postman MCP server gives coding agents (Claude Code, Cursor, Codex, Gemini CLI, VS Code, Windsurf, Kiro, and others) the context they need to work with the Postman platform: run collections, generate client code from API definitions, manage workspaces and environments. For programmatic exposure of an API inventory to agents, two surfaces matter. The MCP Generator builds MCP servers from public API requests in the Postman API Network. Agent Mode can generate MCP servers for internal APIs. The MCP Catalog is the discovery surface for available MCP servers. This is where the conformance work pays off. Agents calling against APIs with high spec quality scores and consistent schemas work. Agents calling against ungoverned APIs produce silent data corruption, retry loops, and rate-limit exhaustion. The bar the catalog sets at design time is the bar that determines whether an API is safe for agent consumption.

One spec, every surface. The same governed artifact flows through every consumer surface, with only the access scope changing. That's the line to draw on the architecture diagram.

Organizations that haven't built this picture pay the cost in three predictable ways.

A governance program done once is a governance program that decays. Standards evolve. New failure modes appear. Old APIs get retired. The portfolio changes shape. The agents calling the API today aren't the same agents calling it next year, and the consumers picking it up from the Postman API Network six months from now will be calling it in patterns nobody has anticipated.

The value of running governance inside the platform that covers the lifecycle is that each pass through the loop refines the next one. Production observability flows back to the catalog. The catalog flows back to the assessment work. New rules get added. Old rules get retired. The system gets stronger with use.

Postman Insights observes what real consumers, human and agent, actually call. When traffic patterns diverge from what the spec describes (consumers calling deprecated endpoints, agents retrying on idempotent failures, rate-limit pressure no static analysis would predict), Insights surfaces the gap. The platform team has a closed loop between governance design and governance reality. The catalog's conformance summary and endpoint health metrics get validated against runtime behavior, so the picture reflects what consumers experience.

For the regulated reader, this is where the audit story changes shape. The most expensive line item for most compliance programs isn't the program itself. It's the prep cost when an audit window opens. Programs that hand-stitch evidence from logs, tickets, and Slack threads spend engineer-weeks per cycle. Programs that emit structured evidence as a side effect of every governance run, every CLI execution, every Monitor pass, and every workspace change spend hours. Postman Audit Logs record team events (sign-ins, API key creation, role changes, workspace and team management actions) with timestamps and actor identity for the past 180 days, and the API can feed those events into a SIEM. The API Catalog's tags and governance groups let the platform team scope APIs by audience or business unit, so the auditor's question ("show me the APIs in our regulated-payments governance group and their current conformance posture") becomes a filter on the catalog rather than a forensic project.

The stage metrics from earlier sections roll up into the executive outcomes the budget committee actually reads. Inventory completeness, governance pass rate at first commit, discoverability time, and the catalog's spec quality score and conformance summary all feed the composite, and the composite picture lands on outcomes the board is already tracking.

Adoption rate is the leading indicator the budget committee should be watching. Adoption predicts everything else, because a program with twelve rules and 80 percent adoption is the foundation of everything that comes next, and a program with forty rules and 10 percent adoption is failing regardless of how the rules are written.

The organizations I work with who treat the governance system as part of the platform, not as a project, are the ones who compound. Each pass through makes the next pass cheaper. The catalog improves with use. The ruleset is a living artifact. Each cycle makes the next cycle easier to defend and easier to scale.

If the document so far has landed, the question is what to do this month. Four steps. Each one references the section above. None of them require a budget cycle or executive approval. The point is to start small and prove it.

The output is a five-column table. API name, owner, spec status (does an OpenAPI spec exist), governance pass status (does it pass any standard the team has agreed on), agent-readiness status (is documentation complete, is the schema consistent, is authentication standardized).

The exercise itself is the value. Most platform teams discover that 30 to 60 percent of their portfolio is missing one or more of the columns. That gap is the size of the first phase of the program. Run the inventory in a week. Don't aim for completeness. Aim for the picture.

Which motion you run determines which work to do first.

This is the executive-defense work from the compounding cycle. Pick one stage metric. The most defensible first choice is governance pass rate at first commit, because it produces an immediate signal about whether the rules are working. Pair it with one executive outcome the budget committee is already tracking: lead time for changes, change failure rate, or audit evidence completeness.

Instrument both. Report weekly. Watch the trend for one quarter. The point is to make the program legible to the people who write the budget. A program that can't produce a number is a program that gets cut in the next budget cycle.

The operating-model work from the distribution section, scoped to the smallest possible test. Pick one workspace, one team, one week. Move the team's spec authoring into Spec Hub. Run the Postman CLI in their CI as the merge gate. Watch what happens.

The reason this step is the closer is that the conversion happens in the data, not in the deck. The team that runs the test almost always becomes the internal champion, because they've lived the difference. The test is small enough that it doesn't require executive approval. It's concrete enough that it converts skeptics. It's repeatable enough that it scales when the budget conversation finally happens.

The argument of this document is the picture on the whiteboard. The API has a lifecycle that runs from design through retirement, and the platform should cover all of it. Governance is the framework inside the platform that sets the standard at every stage. The catalog is the readiness signal that says when an API is fit for consumption. Consumers pick up what the catalog has certified. The artifact stays the same as it moves outward; only the access scope changes.

The ones who don't look like that are the ones whose programs decay. Standards on a wiki. Rules in CI that fire too late. A review board that's become a queue. A portfolio nobody can audit. An AI initiative waiting on work that should have already been done. The compounding cost is the cost of running every consumer surface on a different opinion about what the API is.

I write this because I have the same conversation every week, and the numbers I share in it have the same effect on most people in the room. Starting now costs one quarter of platform engineering time; starting after the incident costs the incident itself. The window to be early is narrow. Only 10 percent of organizations have a posture governance strategy today (Salt Labs State of API Security, Q1 2025). The other 90 percent are compounding debt that turns ungoverned APIs into liabilities the moment AI consumers reach for them.

For a working session that walks the seven stages against your actual portfolio, runs the five diagnostic questions on a real API in your environment, and produces a concrete picture of where the gaps are and which stage to start with, ask your Postman account team for a Field CTO engagement. The session opens the repositories, Spec Hub, the Catalog, and the CI pipeline, and looks at what is actually running.

A consolidated view of how Postman platform capabilities map across the five-stage governance journey.