Arazzo often gets filed away as yet another API format, some kind of alternative to OpenAPI. That filing misses the point. Arazzo describes no single API. It describes the order in which several API calls come together into one business flow.
An OpenAPI specification answers which endpoints an API offers and what a single call looks like. Arazzo sits one level above that. It pins down the sequence in which those endpoints have to be called for a complete transaction to emerge, a partner onboarding, say, or an order that spans several systems. The OpenAPI Initiative, the same body behind OpenAPI itself, published Arazzo in May 2024. The name is the Italian word for tapestry, a nod to the way individual calls get woven into one flow.
Arazzo is an open specification by the OpenAPI Initiative for describing multi-step API workflows. While OpenAPI documents a single API and its endpoints, the Arazzo specification defines the order in which calls run across one or more APIs and how the result of one step feeds into the next. The current version is Arazzo 1.1.0.
What Arazzo describes and what OpenAPI leaves open
In most backend landscapes, OpenAPI is a given. Every API ships with its spec, the endpoints are documented, the schemas are well kept. The one thing missing is how the calls relate to each other. An OpenAPI spec lists an endpoint for creating an order and another for checking delivery status. It says nothing about the second call needing the order ID from the first.
That gap is exactly what Arazzo fills. An Arazzo document lays out a sequence of steps where each step makes an API call and hands its results to later steps. The login step returns a token, the order step uses that token and returns an order ID, the status step takes that ID. OpenAPI alone cannot express this chain, because OpenAPI deliberately stays at the level of the individual operation. Anyone familiar with the underlying OpenAPI specification will feel at home in Arazzo quickly, since both share the same design language.
Put briefly, OpenAPI describes what an API offers, and Arazzo describes how you use it, in which order. That distinction explains why Arazzo presupposes OpenAPI rather than replacing it. As a declarative approach, Arazzo also belongs to the broader field of API orchestration.
How an Arazzo document is structured
An Arazzo document consists of a handful of clearly named building blocks. At the top sits the sourceDescriptions field, which references the underlying descriptions, typically one or more OpenAPI files. Below that come the actual workflows. Each workflow carries a workflowId and consists of an ordered list of steps.
Each step calls an operation, identified by its operationId or its path in one of the source descriptions. A step can set parameters, send a request body, and check via successCriteria whether the call succeeded. The crucial part is the outputs. They extract values from the response and publish them under a name that later steps can reference. Through expressions like $steps.authenticate.outputs.token, the result of one step becomes the input of the next.
info:
title: Partner onboarding
version: 1.0.0
sourceDescriptions:
- name: partnerApi
url: ./openapi.yaml
type: openapi
workflows:
- workflowId: onboardPartner
steps:
- stepId: authenticate
operationId: createSession
requestBody:
payload:
apiKey: $inputs.apiKey
outputs:
token: $response.body#/accessToken
- stepId: createAccount
operationId: createPartner
parameters:
- name: Authorization
in: header
value: $steps.authenticate.outputs.token
outputs:
partnerId: $response.body#/id
The example shows the basic pattern. The first step authenticates and stores the token under outputs. The second step reads that token and sets it as the authorization header. This step-to-step data flow is the core of every Arazzo description.
Beyond the individual steps, Arazzo brings two further mechanisms that matter quickly in real flows. With successCriteria, a step checks against status code, response content, or regular expressions whether it counts as successful. Through onSuccess and onFailure, the workflow defines what happens next, a retry, a jump to another step, or a controlled exit. At the level of the whole workflow, inputs describe the expected input and outputs the final result the workflow hands back. How these building blocks add up to a complete, runnable file is what the step-by-step guide Arazzo in practice walks through.
What Arazzo deliberately leaves out
A common misunderstanding concerns execution. Arazzo describes a flow. It does not run one. The specification pins down which steps are intended, in which order, and with which data handoffs. Which tool then works through that description, a test runner, an SDK generator, or an agent, stays open and sits outside the specification.
This separation is intentional. Arazzo stays out of topics that belong to a runtime, such as long-running retry strategies, executing many workflows in parallel, or persisting intermediate state across hours. Arazzo remains a description, and that is precisely what keeps it portable across tools.
Arazzo is a description language for API workflows, and deliberately not an execution environment. The specification defines steps, order, and data handoffs, while the actual execution is left to whichever tool consumes it, a test runner or an AI agent, for example.
What Arazzo is used for in practice
The most common entry point into Arazzo is documentation. Plenty of teams describe their key business processes in prose today, with a few sample requests in a wiki on the side. Descriptions like that age fast, and there is no way to verify them. An Arazzo spec makes the same flow machine-readable and therefore testable.
Several practical uses follow from that, and they tend to build on each other.
- Multi-step flows, such as a partner onboarding across three or four endpoints, get captured precisely instead of paraphrased in running text.
- From the same spec, you can generate end-to-end tests that check exactly the order and the data handoffs the workflow defines.
- Tutorials and SDK examples stay consistent with the actual call sequence because they come from one shared source.
- AI agents get a reliable template for flows that have to stay deterministic and leave no room for interpretation.
We supported a project at a mid-sized insurer where the claims process lived in a fourteen-page wiki article spanning several APIs. Nobody could say with confidence whether it was still accurate. Once the flow was written down as an Arazzo workflow, the same process could run as an automated test. Three mismatches between documentation and actual behavior surfaced within a single afternoon.
What strikes many teams at this point is an uncomfortable property of their own documentation. As long as a flow only exists in prose, there is hardly any way to tell whether it still matches reality. Only an executable spec makes the difference visible between documented and actually correct.
Arazzo and AI agents
In 2026, Arazzo comes up most often in connection with AI agents. The reason hides in the word deterministic. An agentic workflow lets a language model decide at runtime which tool makes sense next. That is powerful when the flow is genuinely variable. For many business processes, though, that flexibility is a risk, because the order is supposed to be fixed.
The two approaches complement each other here. Where a flow is firmly defined, Arazzo describes it as a reliable template an agent can execute without having to invent the sequence itself. Where real decision room exists, the agentic approach keeps the upper hand. Work on AI-ready APIs and work on Arazzo workflows pull in the same direction, making APIs dependable for machine consumers. Plenty of multi-step flows need no model that reasons along. They simply need a specification that pins down what is already settled.
What version 1.1 changes
Arazzo has moved at a calm, steady pace since its first release. Version 1.0.0 shipped in May 2024, and a 1.0.1 patch followed in January 2025. The current version 1.1.0 brings three additions that noticeably widen the scope.
| New in 1.1.0 | What it enables |
|---|---|
| AsyncAPI support | sourceDescriptions accepts AsyncAPI documents alongside OpenAPI and Arazzo. Steps can send or receive messages, including correlation identifiers and timeouts, reaching beyond purely synchronous REST calls. |
| Chained workflows | A step can call another workflow and pass inputs through an explicit mapping. Larger flows grow out of smaller, reusable workflows. |
| Selector Object | Fine-grained data extraction from structured responses via jsonpath, xpath, or jsonpointer. Values from deeply nested or XML responses can be pulled out cleanly. |
The AsyncAPI support deserves the most attention, because it extends Arazzo from a pure REST description into a language for mixed architectures. A workflow can now make a synchronous call and wait for an incoming event in the next step.
The article What’s new in Arazzo 1.1 covers the 1.1.0 additions in detail. If you want to keep track of which capabilities arrived in which version, the OpenAPI Initiative’s releases are worth watching, since the specification keeps evolving.
What this means for teams
Once Arazzo enters the picture, an organizational question comes up that looks trivial at first. Who owns the workflow specification? An Arazzo file describes a flow that often crosses several APIs and with them several team boundaries. The underlying OpenAPI specs have clear owners. The workflow above them frequently has none.
In practice, it works best to place the Arazzo file with the team that owns the business process and to keep it in a repository of its own, versioned like an API spec. If the workflow gets maintained in a wiki or an isolated test environment instead, it loses touch with reality the same way the old prose documentation did. Arazzo starts paying off once every change to the flow also lands in the spec and goes through the same review as the code. The dedicated repository is no end in itself. A workflow is an asset in its own right, with its own releases and tags, and that versioning only stays clean as long as it does not get tangled up with the release history of any single API.
The fastest way in
The most direct route to Arazzo runs through your own backlog. Take a multi-step flow that sits in your wiki documentation today, a partner onboarding across three endpoints, say, and describe it as an Arazzo workflow.
Frequently asked questions about Arazzo
No. Arazzo presupposes OpenAPI and references OpenAPI documents in its sourceDescriptions field. OpenAPI describes the individual endpoints of an API, while Arazzo describes the order of calls across one or more APIs. Both specifications come from the OpenAPI Initiative and are designed to be used together.
That depends on whether your consumers have to call several endpoints in a fixed order. For an API that is mostly used call by call, Arazzo adds little. As soon as an onboarding, a booking, or a payment chains several calls with data handoffs, an Arazzo description makes that flow verifiable and easy for consumers to follow.
Arazzo is a description language, and deliberately not an execution environment. It defines what a flow across APIs looks like without prescribing which engine runs it. BPMN models business processes at a higher, organizational level. Arazzo stays close to the concrete API calls and their technical data handoffs.
A growing ecosystem has formed around Arazzo since the first release. There are editors for writing workflows, validators for checking the specification, and test runners that execute an Arazzo workflow against a live API. Because the specification is open and maintained by the OpenAPI Initiative, these tools combine freely.
No. The value for agents is a major driver in 2026, yet Arazzo started out serving documentation, testing, and consistent examples. Teams with no agent ambitions at all still benefit from capturing multi-step flows in a machine-readable, testable form.
Arazzo documents are written in YAML or JSON, exactly like OpenAPI documents. The design language deliberately mirrors OpenAPI, so teams that know OpenAPI find their way around quickly. An Arazzo file is best versioned in a repository of its own, since a workflow is an asset in its own right with its own releases and tags, kept separate from the API repositories, especially once it is shared across API boundaries.