Once, the rallying cry of the mobile revolution was, ‘There’s an app for that.’ Today, the new reality is that
AI-powered agents are substantially changing how we interact with software, coining a new catchphrase: ‘There’s an agent for that!’ From automating tasks to executing complex workflows and acting autonomously on our behalf, AI agents are becoming critical intermediaries in digital interactions. While it may seem like magic, APIs—not new wizardry—still provide the connective fabric enabling these agentic workflows and serving this new class of consumers.
This shift has led to a massive acceleration in API consumption, with AI-driven API usage soaring throughout 2024 as the demand for machine-readable data exchanges skyrockets. The new wave of AI consumers has fuelled a drastic
800% increase in AI-related API production
, further reinforcing the importance of designing structured, interoperable, and AI-ready APIs. As a result, thinking holistically about APIs — and
ensuring they are built for the AI era — has never been more critical in all industry verticals.
The surge in API activity has also driven renewed momentum in standards-based initiatives like the
OpenAPI Initiative (OAI). In 2024, the initiative set a new bar for activity by releasing specifications like
Arazzo 1.0.0 and
Overlay 1.0.0, alongside two important patch versions of the OpenAPI Specification:
3.1.1 and 3.0.4. This momentum has continued into 2025, marked by the recent patch release for
Arazzo 1.0.1.
Why Do Standards and Specifications Matter?
In today’s fast-evolving API landscape, where
AI agents are emerging as first-class API consumers, standards and specifications play a critical role in ensuring interoperability, improving the tooling experience, and fostering a shared understanding of how APIs are designed, implemented, and consumed. Specifications such as OpenAPI, AsyncAPI, and now Arazzo form the foundation for creating consistent, predictable API experiences — vital, especially as we enter the AI era.
This shift in API consumption has real implications. But why does this matter?
Extracting value from
APIs often requires more than a single API call. Instead,
workflows often demand a series of API calls orchestrated programmatically to accomplish a specific task (or jobs). This same premise holds true when delegating responsibilities to an AI agent performing tasks autonomously on our behalf.
However, API documentation quality and accuracy vary significantly, creating challenges for all consumers. Even structured formats like OpenAPI descriptions do not
natively define complex workflows, especially when spanning multiple APIs. Supporting documentation also often omits guidance on orchestrating multiple API calls into a cohesive workflow, especially in a manner that can be verified. Human consumers have compensated for these gaps through trial and error, out-of-band documentation, or direct communication with API providers. However, AI agents lack this flexibility, and we certainly do not want them engaging in trial-and-error executions without deterministic guidance to function reliably.
AI agents and systems to effectively and consistently leverage APIs require structured, deterministic, and reliable workflows — something only robust specifications can guarantee. By standardizing how a series of complex or sensitive API calls should be executed in concert, we can:
- Prevent AI hallucinations or incorrect outputs from AI-driven consumers.
- Ensure interoperability, quality, and efficiency across API ecosystems.
- Build trust between API producers and consumers, both human and machine.
By doing so, we simultaneously elevate the human developer experience (DX) and agent experience (AX).
As
David Roldán Martínez, an
AI Researcher and Industry Advisor, puts it:
“In the age of agentic AI, where autonomous systems increasingly rely on interacting with diverse APIs, a specification like Arazzo emerges as a critical enabler of deterministic and reliable API workflows. By providing a standardized framework for orchestrating complex API interactions, Arazzo empowers
developers to build robust and scalable solutions. This enhances the predictability and efficiency of AI-driven systems and fosters greater trust and control, ensuring that the next wave of API consumption remains flexible and governable.”
What Is the Arazzo Specification?
The Arazzo Specification (now at
version 1.0.1) enables the crafting of deterministic API workflows—a structured series of API calls that, when combined, accomplish a specific business objective or consumer job to be done.
Arazzo supports JSON and YAML formats, allowing workflows to be human- and machine-readable. This makes API capabilities easier to understand and consume, accelerating adoption for traditional human developers and AI-agent consumers. By providing a structured way to express workflows, Arazzo bridges the gap between API producers and consumers, making it easier to integrate APIs efficiently.
Beyond readability, Arazzo’s assertiveness helps
API providers tackle key industry challenges while enabling new possibilities for next-generation, agent-based API consumption. It also supports third-party verification, allowing regulatory bodies to
improve rigor and compliance across jurisdictions.
Arazzo and AI-Agent API Consumption
Arazzo’s deterministic approach makes agentic API consumption more efficient. It allows API providers to deliver interoperable workflows across various LLMs and agent technology stacks. Providers can define and use case-oriented consumption semantics
across multiple API operations, whether within a single API description or multiple independent API descriptions.
Additionally, Arazzo’s extensibility allows for the inclusion of usage-based or SLA-based metadata, which can be enforced at the processing or observability layer to ensure predictable scale, cost management, and intended AI-agent use of APIs which will be ever more important as IT leaders navigate the
total cost of ownership (TCO) of new AI-fused topologies.
APIs Are the ‘Best’ Interfaces for Agents
The rise of AI agents for Computer Use (ACU) and Computer-Using Agents (UCAs) — including recent innovations like OpenAI’s Operator — demonstrates how AI can augment human workflows by interacting with existing user interfaces (UIs). This approach is instrumental in legacy environments, where AI can
unlock value quickly without requiring new API development.
However, while leveraging UI-based automation may provide short-term gains, APIs are inherently the superior interface for AI agents. Unlike UIs, which are designed for human cognition, APIs are built for machine consumption, making them more scalable, reliable, and cost-effective in the long run.
Convenience technology has a habit of biting back, and while there can be short-term gains, executives may misinterpret those gains as cheaper, faster, and more consistent ways to enable AI goals. Just as
Robotic Process Automation (RPA) was often misinterpreted as a “quick automation solution” (only to lead to expensive maintenance costs later), short-term UI-based AI integrations risk becoming a crutch if companies fail to invest in API-first strategies.
By investing in robust API assets, organizations prepare for the inevitable shift where APIs, not UIs, become the primary interface for AI agents. This is where Arazzo comes in — by providing a deterministic API workflow layer, Arazzo ensures that agents interact with APIs in a structured, reliable way, rather than relying on fragile UI-based automation and delivering the agent experience (AX) needs mentioned earlier.
Beyond AI: The Broader Use-Cases for Arazzo
While Arazzo is a key enabler of AI-based API consumption, it also provides broader value across the API lifecycle for API producers and consumers today:
- Provide deterministic API consumption recipes: Standardize workflows to ensure repeatable, structured API interactions.
- Act as living workflow documentation: Keep API workflows current without relying on outdated or external documentation.
- Automate consumer-facing documentation: Reduce reliance on out-of-band documentation by generating developer portal docs dynamically.
- Enable end-to-end test automation: Define API workflows that can be used for automated testing.
- Streamline regulatory compliance validation: Automate checks to verify API interactions against compliance requirements.
- Empower next-generation API SDK generation: Enable workflow-aware SDKs for improved developer experiences.
The Arazzo Specification does not mandate a specific development process, such as
design-first or
code-first. It facilitates either technique by establishing precise workflow interactions with HTTP APIs described using the OpenAPI Specification (which it plans to
expand to event-based protocols and the AsyncAPI specification in the future).
Arazzo — A Concrete Example
Let’s imagine we want to describe how to achieve a “Buy Now Pay Later (BNPL)” checkout workflow for online products. An agent will be responsible for determining if the products and customers are eligible for this type of financial engagement. The steps to perform the BNPL flow are:
- Check that selected products are BNPL-eligible
- Retrieve T&Cs and determine customer eligibility
- Create customer record (if needed)
- Initiate the BNPL Loan Transaction
- Authenticate customer and obtain loan authorization
- Calculate and retrieve payment play for client-side rendering
- Update order status
There are two APIs that offer the endpoints/methods needed to complete the process. They are:
👁 ImageFigure 1 – Buy Now, Pay Later – Eligibility API
👁 ImageFigure 2 – Buy Now, Pay Later – Loan API
Leveraging Arazzo, we can describe the workflow explicitly, giving the agent instructions to execute the workflow first and every time correctly. If you would like to better understand the specification structure before looking at the Arazzo document below, check out this
deep dive on the spec.
arazzo: 1.0.1
info:
title: BNPL Loan Application Workflow
version: 1.0.0
description: >
This workflow walks through the steps to apply for a BNPL loan at checkout, including checking product eligibility,
retrieving terms and conditions, creating a customer record, initiating the loan transaction, customer authentication,
and retrieving the finalized payment plan. It concludes by updating the order status once the transaction is complete.
sourceDescriptions:
- name: BnplEligibilityApi
url: https://raw.githubusercontent.com/frankkilcommins/apidays-describing-api-workflows-with-arazzo/ef35e237576d7af2bc3be66d94ffca94eee5036d/specs/bnpl-eligibility.openapi.yaml
type: openapi
- name: BnplLoanApi
url: https://raw.githubusercontent.com/frankkilcommins/apidays-describing-api-workflows-with-arazzo/ef35e237576d7af2bc3be66d94ffca94eee5036d/specs/bnpl-loan.openapi.yaml
type: openapi
workflows:
- workflowId: ApplyForLoanAtCheckout
summary: Apply for a BNPL loan at checkout using the BNPL platform
description: >
This workflow describes the steps to secure a loan at checkout using a BNPL platform, involving multiple API calls
to check product eligibility, determine customer eligibility, initiate the loan transaction, authenticate the customer,
retrieve the payment plan, and update the order status.
inputs:
type: object
required:
- customer
- products
- totalAmount
- token
properties:
customer:
description: Customer details or link to an existing customer record.
oneOf:
- type: object
required:
- firstName
- lastName
- dateOfBirth
- postalCode
properties:
firstName:
type: string
lastName:
type: string
dateOfBirth:
type: string
format: date-time
postalCode:
type: string
- type: object
required:
- uri
properties:
uri:
description: URI for an existing customer.
type: string
format: uri
products:
type: array
minItems: 1
items:
type: object
required:
- productCode
- purchaseAmount
properties:
productCode:
type: string
purchaseAmount:
type: object
required:
- currency
- amount
properties:
currency:
type: string
pattern: "^[A-Z]{3}$"
amount:
type: number
totalAmount:
type: object
required:
- currency
- amount
properties:
currency:
type: string
pattern: "^[A-Z]{3}$"
amount:
type: number
token:
description: Authorization token for the loan transaction.
type: string
steps:
- stepId: checkProductEligibility
description: Call the BNPL API to check if selected products are eligible for BNPL loans.
operationId: $sourceDescriptions.BnplEligibilityApi.findEligibleProducts
requestBody:
contentType: application/json
payload: |
{
"customer": "{$inputs.customer.uri}",
"products": $inputs.products
}
successCriteria:
- condition: $statusCode == 200
outputs:
eligibilityCheckRequired: $response.body.eligibilityCheckRequired
eligibleProducts: $response.body.productCodes
totalLoanAmount: $response.body.totalAmount
onSuccess:
- name: productsEligible
type: goto
stepId: getCustomerTermsAndConditions
criteria:
- condition: $response.body.productCodes != null
- name: productsNotEligible
type: end
criteria:
- condition: $response.body.productCodes == null
- stepId: getCustomerTermsAndConditions
description: Retrieve terms and conditions for BNPL loans.
operationId: $sourceDescriptions.BnplEligibilityApi.getTermsAndConditions
successCriteria:
- condition: $statusCode == 200
outputs:
termsAndConditions: $response.body
onSuccess:
- name: eligibilityCheckRequired
type: goto
stepId: createCustomer
criteria:
- condition: $steps.checkProductEligibility.outputs.eligibilityCheckRequired == true
- name: eligibilityCheckNotRequired
type: goto
stepId: initiateBnplTransaction
criteria:
- condition: $steps.checkProductEligibility.outputs.eligibilityCheckRequired == false
- stepId: createCustomer
description: >
If the customer is not already enrolled, create a new customer record by verifying their eligibility for a BNPL loan.
operationId: $sourceDescriptions.BnplEligibilityApi.createCustomer
requestBody:
contentType: application/json
payload: |
{
"firstName": "{$inputs.customer.firstName}",
"lastName": "{$inputs.customer.lastName}",
"dateOfBirth": "{$inputs.customer.dateOfBirth}",
"postalCode": "{$inputs.customer.postalCode}",
"termsAndConditionsAccepted": true
}
successCriteria:
- condition: $statusCode == 200 || $statusCode == 201
outputs:
customer: $response.body.links.self
onSuccess:
- name: customerCreated
type: goto
stepId: initiateBnplTransaction
criteria:
- condition: $statusCode == 201
- name: customerNotEligible
type: end
criteria:
- condition: $statusCode == 200
- stepId: initiateBnplTransaction
description: Initiate the BNPL loan transaction.
operationId: $sourceDescriptions.BnplLoanApi.createBnplTransaction
requestBody:
contentType: application/json
payload: |
{
"enrolledCustomer": "https://api.example.com/customers/12345",
"products": $inputs.products,
"totalAmount": $inputs.totalAmount
}
successCriteria:
- condition: $statusCode == 202
outputs:
redirectAuthToken: $response.body.redirectAuthToken
loanTransactionId: $response.body.loanTransactionId
onSuccess:
- name: authorizationRequired
type: goto
stepId: authenticateCustomerAndAuthorizeLoan
criteria:
- condition: $response.body.redirectAuthToken != null
- name: authorizationNotRequired
type: goto
stepId: retrievePaymentPlan
criteria:
- condition: $response.body.redirectAuthToken == null
- stepId: authenticateCustomerAndAuthorizeLoan
description: Authenticate the customer and obtain authorization for the loan.
operationId: $sourceDescriptions.BnplEligibilityApi.getAuthorization
parameters:
- name: authorizationToken
in: query
value: $inputs.token
successCriteria:
- condition: $statusCode == 200
outputs:
redirectUrl: $response.headers.Location
- stepId: retrievePaymentPlan
description: Retrieve the finalized payment plan after loan authorization.
operationId: $sourceDescriptions.BnplLoanApi.retrieveBnplLoanTransaction
parameters:
- name: loanTransactionId
in: path
value: $steps.initiateBnplTransaction.outputs.loanTransactionId
successCriteria:
- condition: $statusCode == 200
outputs:
finalizedPaymentPlan: $response.body
- stepId: updateOrderStatus
description: Update the order status to "Completed" once the loan transaction is finalized.
operationId: $sourceDescriptions.BnplLoanApi.updateBnplLoanTransactionStatus
parameters:
- name: loanTransactionId
in: path
value: $steps.initiateBnplTransaction.outputs.loanTransactionId
requestBody:
contentType: application/json
payload: |
{
"status": "Completed"
}
successCriteria:
- condition: $statusCode == 204
outputs:
finalizedPaymentPlan: $steps.retrievePaymentPlan.outputs.finalizedPaymentPlan
Wow — all that YAML. Yes, machines love it but the beauty of such formats is that we can also leverage tools to render Arazzo in human-centric forms. The Arazzo Document can be parsed to a sequence diagram like:
👁 Image
Enabling Agentic API Consumption
The shift towards AI-driven API consumption is accelerating, and deterministic API workflows are critical to ensuring that AI agents can interact reliably with APIs. Arazzo bridges the gap between traditional API consumers and AI agents, providing a structured, assertable framework that removes ambiguity and enhances interoperability, reducing vendor lock-in.
Whether you’re automating workflows, enabling AI consumption, or enhancing API governance, Arazzo is the key to unlocking the next generation of API-driven innovation.
Explore the
Arazzo Specification today to learn more.
