X Openapi Flow MCP

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
• Export a dense, non-prose flow contract for coding agents (export-llm-flows) — or call it directly as an MCP tool — so an agent like Claude Code knows the exact call order, decision rules, and field refs to implement an integration, without re-deriving them from human docs

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/ /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/ /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 or Python 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

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

Example usage (TypeScript):

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

await payment.authorize(); await payment.capture();

Example usage (Python — zero-dependency, stdlib urllib-backed client, generated under ./sdk/src):

from src import FlowApiClient

from src.http_client import UrllibHttpClient

client = FlowApiClient(UrllibHttpClient("https://api.example.com")) payment = client.payment.create({"body": {"amount": 1000}}) payment = payment.authorize() payment = 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 + Hono)

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.

• Works with Express and Fastify
• Resolves operations by operationId (when available) or by method + route
• Reads current resource state using your own persistence callback
• Blocks invalid transitions with explicit 409 error payloads

Install and use directly in your API server:

const {

createExpressFlowGuard, createFastifyFlowGuard, createHonoFlowGuard, } = require("x-openapi-flow/lib/runtime-guard");

Express example:

const express = require("express");

const { createExpressFlowGuard } = require("x-openapi-flow/lib/runtime-guard"); const openapi = require("./openapi.flow.json");

const app = express();

app.use( createExpressFlowGuard({ openapi, async getCurrentState({ resourceId }) { if (!resourceId) return null; return paymentStore.getState(resourceId); // your DB/service lookup }, resolveResourceId: ({ params }) => params.id || null, }) );

Fastify example:

const fastify = require("fastify")();

const { createFastifyFlowGuard } = require("x-openapi-flow/lib/runtime-guard"); const openapi = require("./openapi.flow.json");

fastify.addHook( "preHandler", createFastifyFlowGuard({ openapi, async getCurrentState({ r