OpenAPI describes APIs. x-openapi-flow turns them into executable workflows — for developers and AI agents.

Define your API workflows in openapi.x.json and execute them without writing custom clients or orchestration logic

🚀 2,100+ downloads in the first 3 weeks!

⚡ Get started in seconds

npx x-openapi-flow init --suggest-transitions

This generates an openapi.x.json file where you can declaratively define how your API should be executed — not just described.

See your API lifecycle come alive from your OpenAPI spec, with one simple command

Validate, document, and generate flow-aware SDKs automatically.

What is this?

x-openapi-flow extends your OpenAPI specification with a workflow layer.

openapi.json → describes your API
openapi.x.json → describes how to use it (flows)

Instead of writing imperative code to orchestrate API calls, you define workflows declaratively and run them anywhere.

x-openapi-flow adds a declarative state machine to your OpenAPI spec.

Model resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.

🚀 Example

Define stateful workflows and lifecycle transitions directly inside your OpenAPI operations:

{
  "operationId": "createOrder",
  "x-openapi-flow": {
    "version": "1.0",
    "id": "create-order",
    "current_state": "created",
    "description": "Creates an order and starts the lifecycle",
    "transitions": [
      {
        "transition_id": "order-created-to-paid",
        "trigger_type": "synchronous",
        "condition": "Payment is confirmed",
        "decision_rule": "payOrder:response.200.body.payment_status == 'approved'",
        "target_state": "paid",
        "next_operation_id": "payOrder",
        "operation_role": "mutate",
        "prerequisite_operation_ids": ["createOrder"],
        "evidence_refs": [
          "payOrder:response.200.body.payment_status"
        ],
        "propagated_field_refs": [
          "createOrder:response.201.body.order_id"
        ],
        "failure_paths": [
          {
            "reason": "Payment denied",
            "target_state": "payment_failed",
            "next_operation_id": "getOrder"
          }
        ]
      }
    ]
  }
}

This flow defines an order lifecycle directly inside your OpenAPI:

• Starts in the created state
• Transitions to paid when payment is confirmed
• Supports both synchronous and polling-based transitions
• Propagates data between operations automatically
• Can include explicit decision/evidence and failure-path metadata for AI-guided orchestration

Instead of manually orchestrating API calls, the workflow is fully described alongside your API specification.

Why This Exists

Building APIs is cheap. Building complex, multi-step APIs that teams actually use correctly is hard.

Teams face recurring problems:

• 📄 Manual documentation is brittle – OpenAPI specs are static, often out of sync with real workflows
• 🤖 AI agents can hallucinate – LLMs and code-generating agents may produce invalid calls if workflows are unclear or undocumented
• 🤯 Workflows are confusing – multi-step operations are hard to track for humans and AI agents
• ⚠️ Invalid calls slip through – developers make mistakes because lifecycle rules aren’t enforced
• ⏱️ Integration slows down – SDKs, Postman collections, and docs need constant manual updates
• 🛡️ Hard to prevent errors in production – without explicit lifecycle rules, invalid operations can reach live systems, causing outages or inconsistencies

x-openapi-flow exists to solve these pains: it makes lifecycles explicit, validates transitions automatically, and generates flow-aware docs and SDKs — so teams move faster, make fewer mistakes, and ship confident integrations.

What This Enables

Turn your OpenAPI spec into a single source of truth for API behavior:

• Visualize API lifecycles directly in Swagger UI and Redoc
• Validate flows and state transitions in CI pipelines
• Generate lifecycle diagrams automatically from your OpenAPI spec
• Build SDKs that understand and respect API workflows
• Export Postman and Insomnia collections organized by lifecycle
• Create AI-ready API contracts for agentic integrations

Quick Start (without OpenAPI file)

Start in 2 Minutes (Online Playground)

Prefer no local setup? Open the minimal runtime-guard demo directly in your browser:

• StackBlitz: https://stackblitz.com/github/tiago-marques/x-openapi-flow/tree/main/example/runtime-guard/minimal-order
• Codespaces (repo): https://github.com/tiago-marques/x-openapi-flow

Once open, run:

npm install
npm run start

Then in another terminal:

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

Expected: 409 INVALID_STATE_TRANSITION.

Fastest way to see value (guided scaffold):

npx x-openapi-flow quickstart
cd x-openapi-flow-quickstart
npm install
npm start

Optional runtime:

npx x-openapi-flow quickstart --runtime fastify

Then run:

curl -s -X POST http://localhost:3110/orders
curl -i -X POST http://localhost:3110/orders/<id>/ship

Expected: 409 INVALID_STATE_TRANSITION.

If you already have an OpenAPI file, use the sidecar workflow:

Initialize flow support in your project:

npx x-openapi-flow init
# optional: infer suggested transitions using naming heuristics
npx x-openapi-flow init --suggest-transitions

After regenerating your OpenAPI file, apply and validate the flow (optional):

npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml

npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality

This will:

• enrich your OpenAPI spec with flow metadata
• validate lifecycle consistency
• catch invalid transitions early

💡 Tip: run this in CI to enforce API workflow correctness

Less Verbose DSL for Large Flows

For larger APIs, you can define flow rules by resource (with shared transitions/defaults) and reduce duplication in sidecar files.

See: Sidecar Contract

GitHub Action (One-Step CI Validation)

Use the official reusable action to validate lifecycle rules in CI with a single step:

- name: Validate OpenAPI flow rules
  uses: tiago-marques/x-openapi-flow@v1
  with:
    openapi-file: openapi.flow.yaml
    profile: strict
    strict-quality: "true"

Integration guide: GitHub-Actions-Integration.md

Real Lifecycle Example

Here’s a real-world payment lifecycle represented in x-openapi-flow:

CREATED -> AUTHORIZED -> CAPTURED -> REFUNDED

Generate a visual graph of the lifecycle:

npx x-openapi-flow graph openapi.flow.yaml --format mermaid

Resulting diagram:

graph TD
CREATED --> AUTHORIZED
AUTHORIZED --> CAPTURED
CAPTURED --> REFUNDED

This visualization makes your API workflow explicit, easy to communicate, and ready for documentation or demos.

Generate Flow-Aware SDKs

Create a TypeScript SDK that respects your API’s lifecycle and transition rules, following best practices seen in leading companies like Stripe and Adyen:

• Orchestrator by model: each resource exposes methods that enforce valid transitions
• Chainable API calls: perform sequences naturally and safely

npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk

Example usage:

const payment = await sdk.payments.create({ amount: 1000 });
await payment.authorize();
await payment.capture();

This SDK guides developers through valid transition paths, following patterns used by market leaders to ensure safe and intuitive integrations.

Runtime Enforcement (Express + Fastify)

CI validation is important, but production safety needs request-time enforcement.

x-openapi-flow now includes an official runtime guard for Node.js that can block invalid state transitions during request handling.