Create a workflow

Create a new workflow owned by the authenticated user.

Authentication: Required.

Common Use Cases:

• Save a newly built workflow
• Programmatically provision workflows

Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.

POST /workflows

Create a workflow

cURL

curl --request POST \
  --url https://api.fal.ai/v1/workflows \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "my-image-workflow",
  "title": "My Image Generation Workflow",
  "contents": {
    "name": "my-image-workflow",
    "version": "1.0.0",
    "nodes": {
      "node_a1b2c3": {
        "id": "node_a1b2c3",
        "type": "run",
        "app": "fal-ai/flux/dev",
        "depends": [],
        "input": {
          "prompt": "$input.prompt"
        },
        "metadata": {
          "position": {
            "x": 300,
            "y": 100
          }
        }
      }
    },
    "output": {
      "image": "$node_a1b2c3.images.0.url"
    },
    "schema": {
      "input": {
        "prompt": {
          "type": "string"
        }
      },
      "output": {
        "image": {
          "type": "string"
        }
      }
    }
  }
}
'

201

{
  "workflow": {
    "name": "my-image-workflow",
    "title": "My Image Generation Workflow",
    "user_nickname": "johndoe",
    "created_at": "2025-01-15T12:00:00Z",
    "is_public": false,
    "contents": {
      "name": "my-image-workflow",
      "version": "1.0.0",
      "nodes": {
        "node_a1b2c3": {
          "id": "node_a1b2c3",
          "type": "run",
          "app": "fal-ai/flux/dev",
          "depends": [],
          "input": {
            "prompt": "$input.prompt"
          },
          "metadata": {
            "position": {
              "x": 300,
              "y": 100
            }
          }
        }
      },
      "output": {
        "image": "$node_a1b2c3.images.0.url"
      },
      "schema": {
        "input": {
          "prompt": {
            "type": "string"
          }
        },
        "output": {
          "image": {
            "type": "string"
          }
        }
      }
    }
  }
}

Authorizations

Authorization · string · header · required

API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_API_KEY

Body

application/json

Request body for creating a new workflow

name · string · required

Unique workflow name/slug within the user's namespace

Maximum string length: 128

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"my-image-workflow"

title · string · required

Human-readable workflow title

Required string length: 1 - 256

Example:

"My Image Generation Workflow"

contents · object · required

The workflow definition/configuration object

Show child attributes

Example:

{
  "name": "my-image-workflow",
  "version": "1.0.0",
  "nodes": {
    "node_a1b2c3": {
      "id": "node_a1b2c3",
      "type": "run",
      "app": "fal-ai/flux/dev",
      "depends": [],
      "input": { "prompt": "$input.prompt" },
      "metadata": { "position": { "x": 300, "y": 100 } }
    }
  },
  "output": { "image": "$node_a1b2c3.images.0.url" },
  "schema": {
    "input": { "prompt": { "type": "string" } },
    "output": { "image": { "type": "string" } }
  }
}

is_public · boolean · default: false

Whether the workflow is publicly visible

Example:

false

Response

201

application/json

Successfully created workflow

Response containing a single workflow's details

workflow · object · required

The workflow details

Show child attributes

Example:

{
  "name": "my-image-workflow",
  "title": "My Image Generation Workflow",
  "user_nickname": "johndoe",
  "created_at": "2024-01-15T10:30:00Z",
  "is_public": true,
  "contents": {
    "nodes": {
      "node_a1b2c3": {
        "id": "node_a1b2c3",
        "type": "model",
        "app": "fal-ai/flux/dev",
        "depends": [],
        "input": { "prompt": "$input.prompt" },
        "metadata": { "position": { "x": 300, "y": 100 } }
      },
      "output": {
        "id": "output",
        "type": "output",
        "depends": ["node_a1b2c3"],
        "fields": { "image": "$node_a1b2c3.images.0.url" },
        "metadata": { "position": { "x": 600, "y": 100 } }
      }
    }
  }
}