An integration engineer at a partner company opens the developer portal, finds the order API in the catalog, and sees twelve cleanly documented endpoints. What she actually wants to know is on none of those pages. She wants to place an order and track it, and for that she needs the sequence in which the endpoints play together, which call hands which result to the next, and what to do when a payment gets declined. After two hours in the endpoint reference, she files a support ticket with the question the catalog left unanswered. "In what order do I call this?"
A few months later, in the same portal, the same research looks different. Next to the order API, the catalog lists three described workflows, among them "Place and track an order" with every step, data handoff, and failure path. The engineer reads the flow in ten minutes, runs it against the test environment, and asks no questions at all. The difference between the two scenes is no new product and no better endpoint documentation. It is one additional kind of content in the catalog.
An API catalog answers which APIs exist and what their endpoints do. The order in which several calls form a business transaction is usually beyond its scope. Arazzo workflows close that gap as machine-readable flow descriptions that publish into the catalog right next to the OpenAPI specs. Consumers then find the building blocks and the assembly instructions in one place.
The gap between endpoints and flows
Catalogs and portals have come a long way in recent years. A well-kept API catalog reliably answers which APIs exist, who owns them, and what the individual operations look like. The question it leaves structurally unanswered is the one about the transaction. A partner onboarding, an order with status tracking, or a claims report across three systems simply do not exist as objects in the catalog, because its content types end at the single API.
The information exists all the same, just elsewhere. It spreads across wiki pages, onboarding slides, old support tickets, and the minds of experienced colleagues. Each of those sources goes stale at its own pace, none gets verified at API release time, and in the end none of them is findable. Whoever needs the flow asks around, and whoever has nobody to ask, like the external partner above, files a ticket.
It is striking how consistently this gap shows in support data. When a team categorizes its recurring consumer questions once, questions about sequence and interplay land in the top group, well ahead of questions about individual endpoints. The endpoint documentation is mostly good enough. What is missing is the layer above it.
The obvious objection is that good portals have tutorials and getting-started pages for this. True, and those pages do valuable work, yet they share the fate of all hand-written flow documentation. They get written once, rarely verified against the API, and age unnoticed, because no test breaks when reality drifts away from them. The difference to a workflow spec lies less in the content than in the verifiability. A tutorial claims a flow. An executed spec proves it.
Workflows as first-class catalog content
With Arazzo, an open format has existed since 2024 that describes exactly this layer, machine-readable and versioned like an OpenAPI spec. What the specification does is explained in What is Arazzo, and how a concrete workflow file comes together is shown in the hands-on tutorial. The interest here is the step after that, publication.
A workflow in the catalog behaves best like an API, as an entry of its own with a name, a description, a version, and an owner. It links to the participating APIs, and they link back to it in turn. Whoever finds the order API sees its workflows, and whoever finds the order workflow sees the participating APIs. That two-way linking is the actual mechanism behind discoverability, because consumers enter sometimes through the API and sometimes through the transaction.
More than a text page can be generated from the Arazzo file. The steps yield a visual flow diagram, the data handoffs render as connections, and the failure paths show where the transaction branches. All of it comes from the same source the test runner executes, which is exactly why it stays current while hand-maintained flow diagrams drift away from reality within months.
Search benefits from the structured source as well. A consumer searching for "track an order" finds the workflow through its title and description, even without knowing the participating APIs yet. That reverses the direction of discovery. It used to take guessing the right API to find the flow. Now the transaction someone is after leads to the matching API. For business-minded users especially, from business analysts to product owners, entering through the transaction is the more natural route.
What changes for consumers
From the consumer’s side, workflows in the catalog shift one thing above all, the starting point of an integration. It used to begin with detective work on the endpoint list. With described workflows, it begins with following a verified flow.
- The call order is settled and no longer reconstructed from field names and guesswork.
- The data handoffs are explicit. Which value from which response goes into which follow-up call is part of the description.
- The failure paths are documented, including which steps remain in which state after an abort.
- The flow is executable. Run it against the test environment and you know it works before writing a single line of your own code.
Taken together, that shortens the time to the first successful transaction considerably and shifts the support load. The question "in what order" disappears from the tickets, because its answer now sits where people search.
The contrast plays out along the typical integration stations.
| Station | Without workflows in the catalog | With workflows in the catalog |
|---|---|---|
| Understand the flow | Endpoint list, wiki search, asking colleagues | Read the workflow entry with steps and data flows |
| Verify the order | Guesswork, trial and error against the test environment | Execute the described workflow against the test environment |
| Clarify failure cases | Support ticket after the first production incident | Read the documented failure paths before integrating |
| Currency | Wiki state of unknown age | Synced from the repository, tested in the pipeline |
Which workflows belong in the catalog
Not every internal flow deserves publication, and a small selection logic keeps the catalog from overgrowing. Three criteria have held up.
The first is consumer relevance. Publish what consumers actually have to rebuild, the transactions behind the most common integration scenarios. Internal operations workflows, for data migrations, say, belong in the repository and mostly stay out of the portal. The second criterion is stability. A workflow that changes weekly produces more version noise than orientation, and its flow may simply still be under design. The third is completeness. A published workflow without failure paths answers half the question, and that second half is precisely what separates it from the wiki.
In practice, that yields rarely more than three to five published workflows per API, and that concentration is the point. The catalog is there to show the main roads, no collection of every conceivable path.
A clear mapping between workflow and business domain helps as well, mirroring the domain structure of the APIs themselves. An order workflow belongs in the same catalog category as the order API, even when it touches the payment API along the way. Consumers search along their business task, and sorting by the leading business object matches that direction far better than a technical grouping by participating systems.
What changes for provider teams
For the team behind the API, publishing in the catalog is first and foremost a commitment, and it is honest to call it that. A published workflow is a promise to consumers, exactly like a published API. It needs an owner, versioning, and a check that catches drift between description and actual API behavior before consumers experience it.
The good news is that the API world already has processes in place for this. An Arazzo file lives under version control, passes through reviews, and runs as a test in the pipeline, all mechanisms long established for OpenAPI specs. Governance extends to one more kind of artifact without inventing new processes. How a catalog stays current at enterprise scale, through federated ownership and automated sync from Git and CI, is covered in API catalogs in large organizations, and the same logic applies to workflows. They sync from the repository into the catalog, with no hand-maintenance involved. The workflow files have their place in a repository of their own, separate from the API repositories, because they follow their own releases and tags. The catalog manages an Arazzo file like an API spec, with owner, versions, and a complete audit trail. In regulated industries especially, that record of who changed which flow and when is frequently the precondition for being allowed to share workflows with partners at all.
There is an inward effect on top, one that surprises in projects. Whoever describes their key flows for publication discovers inconsistencies in their own APIs along the way, from mismatched status values to gaps in the error responses. The workflow description acts like a review of the API from the consumer’s seat, and some teams now describe their flows before the first consumer arrives, for exactly that effect.
One consideration of its own goes to versioning. A workflow changes for two reasons, either because a participating API changes or because the business flow itself gets restructured. The two cases hit consumers differently, and a catalog should keep them distinguishable. A corrected data handoff is a patch. An additional mandatory step in the flow is, for consumers, a new major version with migration work attached. Teams that already run their API versioning cleanly carry that logic over to the workflow entries with little effort and spare consumers the surprise of a flow that changed unannounced.
Workflows, agents, and the next generation of consumers
The integration engineer from the opening is about to get company from a second group of consumers. AI agents that execute transactions over APIs face the same question about sequence, except they read no wiki pages and file no tickets. A catalog that carries flows as machine-readable workflows answers the question for both groups from one source.
For deterministic transactions, the Arazzo description is the more dependable foundation than an agent’s free runtime decisions, because order and failure paths are settled, while dynamic agentic workflows keep their strength wherever genuine decision room exists. The bigger picture, in which the two approaches complement each other, is drawn in the overview of API orchestration. For the catalog, the takeaway is plain. The investment in described workflows pays twice, for today’s humans and for tomorrow’s agents.
How to start with your first workflow
As with most catalog topics, the start decides the adoption, and the start should be small. A single workflow for the most used API, cleanly described, tested, and published, demonstrates the value faster than any concept paper. Finding the candidate is easy, since the support tickets and the wiki show which flow needs explaining most often.
The best pilot workflow for the catalog is the flow consumers ask about most. The support history of the past months usually reveals it at a glance, and the effect of publishing can be read straight off the ticket numbers afterward.
api-portal.io supports this path with an API catalog that carries workflows next to the API specs, syncs them from the repository, and makes them searchable for consumers. The flow description becomes part of the same platform where consumers already discover endpoints, read documentation, and request access.
As a first step, publish the one flow that shows up most often in your support tickets as a described workflow in the catalog. Compare the ticket numbers after a quarter with the baseline, and you have a solid basis for deciding on every workflow after it.