API OpenAPI Arazzo Workflows and Overlays

Status: public · Confidence: medium (0.825) · Basis: verified_sources

## TL;DR

Arazzo workflows and OpenAPI overlays give API agents machine-readable context beyond single endpoint schemas.

## Core Explanation

OpenAPI describes operations, but agents often need to perform multi-step workflows: create a resource, poll status, fetch output, and handle failure. Arazzo can describe those steps and dependencies. Overlays can layer metadata or changes onto an existing OpenAPI description without rewriting the source file.

Agents should treat these artifacts as planning evidence, not permission to act. They still need scoped credentials, environment selection, idempotency rules, retry policy, and human approval for high-impact operations.

## Source-Mapped Facts

- The Arazzo Specification provides a mechanism for defining sequences of API calls and their dependencies in the context of API descriptions. ([source](https://spec.openapis.org/arazzo/latest.html))
- The Arazzo Specification says an Arazzo description must contain at least one workflow in its workflows fixed field. ([source](https://spec.openapis.org/arazzo/latest.html))
- The OpenAPI Overlay Specification defines a document format for updating an OpenAPI description through structured overlay actions. ([source](https://spec.openapis.org/overlay/latest.html))

## Further Reading

- [Arazzo Specification](https://spec.openapis.org/arazzo/latest.html)
- [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/latest.html)