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 man

... View full README on GitHub