[go: up one dir, main page]

Open source · Apache 2.0

OpenAPI Describes Each Call. Arazzo Describes the API Workflow.

You've probably scripted your API workflow by hand, and it breaks quietly when the API changes. Write it as an Arazzo document instead. UseArazzo validates it, runs it against live APIs, and shows you exactly what happened at each step.

Founded by two industry veterans with over 15 years of combined experience building and maintaining core Swagger/OpenAPI tooling. Meet the team →

$ node
> const { ArazzoRunner } = await import('@usearazzo/runner')
> const runner = await ArazzoRunner.load('find-a-pet.arazzo.yaml')
> const inputs = { status: 'available' }
> const result = await runner.execute('findAPet', { inputs })
> result.steps.map((step) => [step.stepId, step.successful])
[ [ 'findPets', true ], [ 'getPet', true ] ]
> result.outputs
{ petId: 11, name: 'doggie' }

Works with

Arazzo Arazzo Specification
OpenAPI OpenAPI Specification (source descriptions)

Why API workflows still get improvised

A single API call is a solved problem. OpenAPI describes it, generators wrap it, and every HTTP client can make it. The order you call the endpoints in, what you carry from one response into the next request, and how you know you are done have no such home. That part lives in scripts, in tribal knowledge, and in agents that work out the call order at runtime. If you maintain an API, test one, or build agents on top of one, you have written that glue yourself. It is rarely reviewed, rarely versioned alongside the API it drives, and it breaks quietly when the API changes. Improvisation is exactly what you don't want in production.

Read why it still happens →

What it does

Plenty of tools will tell you whether an Arazzo document is well formed. Far fewer will run it. UseArazzo does both, and tells you what happened.

The UseArazzo pipeline: an Arazzo document is described once, validated with every violation located, run step by step against live APIs, and read back as a trace of each step with the outputs and final status. arazzo: 1.0.1workflows:- workflowId: findAPetsteps:- stepId: findPets- stepId: getPet 01 Describe an Arazzo document in your repository - name: petIdin: pathsvalue: $steps.findPets…✖ error at 39:17 02 Validate every violation, with its location findPetsgetPetAPI 03 Run each step, against live APIs findPetsgetPetcompletedpetId: 11, name: 'doggie' 04 Read the trace steps, outputs, final status
Get started

Why UseArazzo

Deterministic execution

A workflow that ran yesterday runs the same today. Agents can choose which workflow to run, not improvise the steps inside it.

The standard is the product

UseArazzo implements Arazzo exactly as the specification defines it. When something needs fixing, the fix goes upstream into the specification, not into private extensions that only one tool can read.

See the upstream contributions →

Portable artifacts

Plain Arazzo documents in your repository, driven from your own code, your CI pipeline, or an agent. If you stop using the toolkit, your API workflows keep working.

Compatibility

What the toolkit can validate and run today.

Document Versions Validate Run
Workflow Document: Arazzo 1.0.0, 1.0.1, 1.1.0 ✓ Yes ✓ Yes
Source Description: OpenAPI 2.0, 3.0.x, 3.1.x ✓ Yes ✓ Yes
Source Description: OpenAPI 3.2.x ✗ No ✗ No
Source Description: Arazzo 1.0.0, 1.0.1, 1.1.0 ✓ Yes ✓ Yes
Source Description: AsyncAPI any ✗ No ✗ No

On the roadmap

None of this is built yet. It's where the toolkit is headed, published here so you can tell what exists today from what doesn't.

Language Service

An LSP-compatible library bringing Arazzo intelligence to any editor or tool: validation, completion, hover, go-to-definition, and find references.

Editor

A browser-based editor for authoring and validating Arazzo workflows with real-time feedback.

VS Code Extension

Arazzo authoring inside VS Code: real-time validation, semantic linting, autocompletion, and live preview.

GitHub Actions

Validation and run results reported where the work happens: violations annotated on the diff, the step-by-step run trace rendered into the job summary, and the check status driven by step outcomes rather than a single pass or fail.

Agent Skills

A set of task-shaped skills teaching agents to work the toolchain: authoring workflows from an API description, validating and fixing them, and reading a run trace when a step fails.

MCP Server

A generic Model Context Protocol server exposing validation and execution over any Arazzo document, so agents can check and run workflows with no build step.

MCP Compiler

Compiles a specific workflow into a dedicated MCP server: one typed tool per workflow, with real input schemas, for production agent deployments.

Arazzo Transformers

Explicit, versioned transformations for reshaping data between steps, declared as ordinary API calls the toolchain can validate rather than arbitrary code that needs a sandbox to run.

Community

Built in the open

Every part of UseArazzo is open source under Apache 2.0, and it runs on your machine. Contributions, issues, and questions are welcome.

Get help from the maintainers

UseArazzo is free to use. If you have a question, an idea, or a bug to report, Discussions is a good place to start, and you are welcome to email the maintainers directly about anything else.

Talk to the maintainers

Frequently asked questions

Short answers to what people ask first about UseArazzo.

Something else? Ask in Discussions.

UseArazzo is a free, open-source JavaScript and TypeScript toolkit for Arazzo, the OpenAPI Initiative’s specification for multi-step API workflows. It validates Arazzo documents, runs workflows against live APIs, and returns a trace of every step. It ships as a CLI, a Validator, and a Runner.

Arazzo is the OpenAPI Initiative’s specification for multi-step API workflows. OpenAPI describes each operation on its own, which is not enough once a task takes more than one call. Arazzo describes how to use the operations together: which calls to make in which order, how the output of one call feeds the next, and what counts as success.

Run npx @usearazzo/cli validate workflow.arazzo.yaml. It prints every problem with its location and exits with 1 on an error, so it works in CI as is. In code, validateURI from @usearazzo/validator returns the same problems as data. An operationId that is missing from the OpenAPI description is not reported.

Install @usearazzo/runner, then call ArazzoRunner.load(uri) and runner.execute(workflowId, { inputs }). The result carries the final status, the outputs, and a trace of every step. The Runner is a library: the CLI has no run command. See the Runner API reference.

Write a short Node.js script and run it as a CI step. Load the document with ArazzoRunner.load, call execute, and set the exit code from the result: process.exitCode = result.status === 'completed' ? 0 : 1. The getting started guide builds a complete script that validates first and then runs.

Yes. Five packages are on npm: @usearazzo/cli, @usearazzo/validator, @usearazzo/runner, @usearazzo/parser, and @usearazzo/resolver. They are for JavaScript and TypeScript and need Node.js 20.10 or newer.

Yes. The packages are alphas because the API may still change before the stable release, not because of quality. Tests run on every pull request and every night, and each pull request also runs workflows end to end against a real API server. Pin an exact version.

Arazzo 1.0.0, 1.0.1, and 1.1.0 workflow documents validate and run, in JSON and YAML. Source descriptions can be OpenAPI 2.0, 3.0.x, or 3.1.x documents, or other Arazzo documents. OpenAPI 3.2.x and AsyncAPI source descriptions are not supported. The compatibility table has every row.

With credentials you supply per API in executeOptions: { petstoreAPI: { securities: { authorized: { api_key: 'KEY' } } } }. API keys, bearer tokens, basic auth, and OAuth tokens are covered, and a requestInterceptor handles computed ones. The Runner runs no OAuth flow. See Authentication in the Runner API reference.

Only to the APIs your workflow calls. UseArazzo runs on your own machine, with no account and no hosted service in between. A credential is sent only to the API it belongs to, never to another API in the same workflow or to a host that only serves a document.

Yes. Every package is free, open source, and licensed under Apache 2.0. All of the source is in the arazzo-toolkit repository on GitHub.

Vladimír Gorej and Francesco Tumanischvili, former core contributors to the Swagger open-source tools and contributors to the Arazzo specification. The toolkit is built on SpecLynx, their own API tooling foundation. The About page has the track record.

Yes. npx @usearazzo/cli validate --json prints problems as JSON and sets an exit code, so an agent can check and fix a workflow it wrote. The Runner executes a workflow exactly as written, so an agent chooses which workflow to run instead of improvising the calls. There is no MCP server today.

UseArazzo is built from small parts that also work alone. The Runner runs a whole workflow, a single step, or a single OpenAPI operation, and its HTTP stack can be replaced. Problems and step traces come back as data. It follows the Arazzo specification as closely as it can, with no private extensions. The Arazzo Ecosystem page lists the other tools.