Arazzo 1.0: Multi-Step API Workflows Spec 2026

TL;DR

Arazzo 1.0 is the OpenAPI Initiative's answer to a problem every API developer faces: OpenAPI describes what each endpoint does, but not how to sequence them into a workflow. Arazzo adds a machine-readable layer on top of OpenAPI that describes multi-step flows — like "create account → verify email → create subscription" — with inputs, outputs, success criteria, and step dependencies. In 2026, it's becoming critical for making APIs consumable by AI agents.

Key Takeaways

• Arazzo 1.0.1 is the current stable version, fully backward-compatible with 1.0.0
• It doesn't replace OpenAPI — it layers on top, referencing your existing OpenAPI documents
• Machine-readable workflows enable AI agents to understand how to use your API, not just what endpoints exist
• Tooling is growing: Redocly, Speakeasy, APIDog, Specmatic, and Bruno all have Arazzo support in 2026
• Key components: sourceDescriptions (which APIs), workflows (named flows), steps (individual API calls), successCriteria, and outputs
• Practical use cases: onboarding flows, payment sequences, OAuth handshakes, multi-step data transformations

---

The Problem Arazzo Solves

OpenAPI is excellent at documenting individual endpoints. You can describe every parameter, response code, and schema. But a developer integrating your payment API doesn't just need to know what /payments accepts — they need to know the sequence:

1. Call POST /customers → get customerId
2. Call POST /payment-methods with customerId → get paymentMethodId
3. Call POST /payments with both IDs → get paymentId
4. Poll GET /payments/{paymentId} until status is succeeded or failed

None of that sequencing lives in OpenAPI. Developers read docs, build mental models, and translate them into code. AI agents can't do that easily — they need the workflow described explicitly.

That's exactly what Arazzo 1.0 provides.

---

Arazzo Document Structure

An Arazzo document is a YAML (or JSON) file with this top-level structure:

arazzo: "1.0.1"
info:
  title: Stripe Payment Workflow
  version: "1.0.0"
sourceDescriptions:
  - name: stripe
    url: ./stripe-openapi.yaml
    type: openapi
workflows:
  - workflowId: create-and-charge-customer
    summary: Create a customer and process a payment
    inputs:
      type: object
      properties:
        email: { type: string }
        amount: { type: integer }
        currency: { type: string }
    steps:
      - stepId: create-customer
        operationId: stripe.createCustomer
        requestBody:
          payload:
            email: $inputs.email
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          customerId: $response.body.id
      - stepId: create-payment-intent
        operationId: stripe.createPaymentIntent
        requestBody:
          payload:
            customer: $steps.create-customer.outputs.customerId
            amount: $inputs.amount
            currency: $inputs.currency
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          paymentIntentId: $response.body.id
          clientSecret: $response.body.client_secret

The Four Core Concepts

1. sourceDescriptions Points to one or more OpenAPI documents. You reference operations from these documents using dot notation: stripe.createCustomer means "the createCustomer operation in the stripe source."

2. workflows Named, reusable flows. Each has a workflowId, optional inputs schema (JSON Schema), an ordered list of steps, and outputs that downstream consumers can reference.

3. steps Individual API calls within a workflow. Each step can:

• Reference an operationId from a source description
• Extract values from responses using JSONPath expressions ($response.body.id)
• Pass those values to subsequent steps ($steps.step-id.outputs.value)
• Define successCriteria (HTTP status codes, JSONPath assertions)

4. successCriteria Conditions that must be true for a step to be considered successful. Beyond status codes, you can assert on response body values:

successCriteria:
  - condition: $statusCode == 200
  - condition: $response.body.status == "active"
    type: jsonpath

---

Real-World Example: OAuth 2.0 PKCE Flow

OAuth 2.0 PKCE is exactly the kind of multi-step flow that's hard to document in plain OpenAPI but natural in Arazzo:

arazzo: "1.0.1"
info:
  title: OAuth 2.0 PKCE Authorization Flow
  version: "1.0.0"
sourceDescriptions:
  - name: auth-api
    url: ./auth-openapi.yaml
    type: openapi
workflows:
  - workflowId: pkce-authorization
    summary: Complete OAuth 2.0 PKCE flow
    inputs:
      type: object
      properties:
        clientId: { type: string }
        redirectUri: { type: string }
        codeVerifier: { type: string }
        scope: { type: string }
    steps:
      - stepId: generate-auth-url
        operationId: auth-api.generateAuthorizationUrl
        parameters:
          - name: client_id
            in: query
            value: $inputs.clientId
          - name: code_challenge_method
            in: query
            value: "S256"
          - name: redirect_uri
            in: query
            value: $inputs.redirectUri
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          authUrl: $response.body.url
          state: $response.body.state
      - stepId: exchange-code-for-token
        operationId: auth-api.exchangeAuthCode
        requestBody:
          payload:
            code: $inputs.authCode
            code_verifier: $inputs.codeVerifier
            client_id: $inputs.clientId
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          accessToken: $response.body.access_token
          refreshToken: $response.body.refresh_token
          expiresIn: $response.body.expires_in

This document is unambiguous. Any tool — or AI agent — that reads it knows exactly what calls to make, in what order, and what to do with the responses.

---

Why Arazzo Matters for AI Agents in 2026

The API ecosystem is being reshaped by AI agents. In 2026, a significant percentage of API calls come from AI agents — orchestration frameworks like LangChain, CrewAI, Claude, and custom agent loops that need to understand how to use APIs without human guidance.

OpenAPI alone isn't sufficient for agents. An agent reading your OpenAPI spec knows what endpoints exist but has to infer how to sequence them. This leads to:

• Guessing the correct order of API calls
• Missing required setup steps (authentication, resource creation)
• Failing silently when intermediate steps fail

Arazzo solves this directly. Anthropic's MCP specification already references Arazzo as the way to describe multi-step workflows that MCP servers expose. Tools like Kong are building AI gateway features that use Arazzo documents to guide agent behavior.

"OpenAPI won't make your APIs AI-ready. But Arazzo can." — Bump.sh engineering blog, 2025

The pattern is clear: OpenAPI describes your API surface. Arazzo describes how to use it.

---

Tooling Ecosystem (March 2026)

Tool	Arazzo Support
Redocly	Linting, validation, rendering workflows in docs
Speakeasy	SDK generation from Arazzo workflows
APIDog	Visual workflow builder + Arazzo export
Specmatic	Contract testing from Arazzo documents
Bruno	Native MCP client support with Arazzo flows
Swagger Editor	Basic validation (v4+)
Stoplight	Planned support Q2 2026

Speakeasy's SDK generation is particularly compelling: you write an Arazzo document describing your API workflows, and Speakeasy generates typed SDK methods that encapsulate the full workflow — not just individual API calls. Instead of your users manually chaining three API calls, they call sdk.createAndChargeCustomer({ email, amount, currency }).

Redocly's rendering embeds workflow steps directly into your API documentation, showing users the recommended sequence with code samples auto-generated for each step.

---

Getting Started: Your First Arazzo Document

1. Install Redocly CLI for validation

npm install -g @redocly/cli

2. Create your Arazzo document

Start with a simple two-step workflow. Reference your existing OpenAPI spec:

arazzo: "1.0.1"
info:
  title: User Onboarding
  version: "1.0.0"
sourceDescriptions:
  - name: my-api
    url: ./openapi.yaml
    type: openapi
workflows:
  - workflowId: user-onboarding
    summary: Register and activate a new user account
    inputs:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password: { type: string, minLength: 8 }
    steps:
      - stepId: register
        operationId: my-api.registerUser
        requestBody:
          payload:
            email: $inputs.email
            password: $inputs.password
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          userId: $response.body.id
          verificationToken: $response.body.verificationToken
      - stepId: verify-email
        operationId: my-api.verifyEmail
        parameters:
          - name: token
            in: path
            value: $steps.register.outputs.verificationToken
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          accessToken: $response.body.accessToken

3. Validate your document

redocly lint arazzo.yaml

Redocly will catch reference errors, invalid JSONPath expressions, and missing required fields.

---

Arazzo vs Other Workflow Description Approaches

Approach	What It Does	Arazzo Advantage
OpenAPI only	Describes endpoints, no sequences	Arazzo adds the sequence layer
API Blueprint	Markdown-based docs	Arazzo is machine-readable YAML
Postman Collections	Step-based API execution	Arazzo is a portable open standard
Manual SDK code	Hard-codes workflows in client code	Arazzo keeps workflow as data
AsyncAPI	Event-driven/async APIs	Arazzo is for synchronous REST/HTTP

Arazzo is explicitly designed to complement OpenAPI — not replace it. If you have an OpenAPI spec, adding an Arazzo document is additive, not a migration.

---

Practical Checklist

Before publishing an Arazzo document:

• arazzo version field set to "1.0.1"
• All operationId references match IDs in the referenced OpenAPI specs
• Every $response.body.X expression references an actual field from the response schema
• successCriteria defined for every step
• inputs schema is complete with required fields and types
• Outputs from one step that feed into the next are explicitly declared
• Validated with redocly lint

---

Recommendations

Start with Arazzo if:

• Your API has any multi-step flows that users commonly implement (onboarding, auth, checkout)
• You're exposing your API to AI agents or MCP tools
• You use Speakeasy, Redocly, or APIDog — tooling support is ready today

You can wait if:

• Your API is single-endpoint (analytics writes, simple CRUD)
• Your primary consumers are internal teams with direct code access

Methodology

• Sources: Arazzo Specification v1.0.1 (spec.openapis.org), Bump.sh engineering blog, Speakeasy documentation, Redocly learn center, Swagger.io deep dive, APIDog specification guide
• Date: March 2026

---

Related: API documentation tools compared 2026 — see how Redocly and Stoplight fit into the broader doc toolchain.

Also on APIScout: OpenAPI vs AsyncAPI 2026 — understanding when each spec applies.

Building AI-ready APIs? See How MCP is changing API discovery 2026 for the full picture.