Workflows are the core resource in Wireflow. Each workflow contains a graph of AI model nodes connected by edges.

List Workflows

GET /api/v1/workflows

Returns all workflows owned by the authenticated user, ordered by most recently updated.

Query Parameters

Parameter	Type	Description
isActive	string	Filter by active status: "true" or "false"
mediaId	string	Filter by project/media ID
teamId	string	Filter by team ID

Request

curl https://www.wireflow.ai/api/v1/workflows \
  -H "Authorization: Bearer sk-your-api-key"

Response 200 OK

[
  {
    "id": "cm1abc123",
    "name": "Product Image Generator",
    "description": "Generates product photos from text descriptions",
    "webhookId": "whk_xyz789",
    "webhookUrl": null,
    "isActive": true,
    "isPublished": false,
    "executionCount": 42,
    "lastExecutedAt": "2025-03-15T10:30:00.000Z",
    "tags": ["image", "product"],
    "createdAt": "2025-01-10T08:00:00.000Z",
    "updatedAt": "2025-03-15T10:30:00.000Z"
  }
]

Create a Workflow

POST /api/v1/workflows

Creates a new workflow. The nodes and edges arrays define the workflow graph.

Build nodes from the node catalog (GET /api/v1/nodes). It declares every node's ports, config keys, enum options, defaults, and pricing. The write path lints the graph against it: unknown node types are rejected, unknown config keys and bad enum values come back as warnings in the response meta.

Request Body

Field	Type	Required	Description
name	string	Yes	Workflow name
description	string	No	Workflow description
nodes	Node[]	Yes	Array of workflow nodes
edges	Edge[]	Yes	Array of connections between nodes
tags	string[]	No	Tags for organizing workflows
isActive	boolean	No	Whether the workflow is active (default: true)
webhookId	string	No	Webhook identifier for triggering via HTTP
mediaId	string	No	Project/media ID to scope the workflow to

Request

curl -X POST https://www.wireflow.ai/api/v1/workflows \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Workflow",
    "description": "Generates images from prompts",
    "nodes": [
      {
        "id": "node-1",
        "type": "basedNode",
        "position": { "x": 0, "y": 0 },
        "data": {
          "label": "Text to Image",
          "nodeType": "model:fal:text-to-image",
          "category": "model",
          "prompt": "A sunset over mountains"
        }
      }
    ],
    "edges": [],
    "tags": ["image"]
  }'

Response 201 Created

{
  "id": "cm1abc123",
  "name": "My Workflow",
  "description": "Generates images from prompts",
  "nodes": [...],
  "edges": [],
  "webhookId": null,
  "isActive": true,
  "tags": ["image"],
  "userId": 1,
  "createdAt": "2025-03-20T12:00:00.000Z",
  "updatedAt": "2025-03-20T12:00:00.000Z"
}

Get a Workflow

GET /api/v1/workflows/{id}

Retrieves a single workflow by ID, including its last 10 executions.

Request

curl https://www.wireflow.ai/api/v1/workflows/cm1abc123 \
  -H "Authorization: Bearer sk-your-api-key"

Response 200 OK

{
  "id": "cm1abc123",
  "name": "My Workflow",
  "description": "Generates images from prompts",
  "nodes": [...],
  "edges": [...],
  "webhookId": null,
  "isActive": true,
  "isPublished": false,
  "tags": ["image"],
  "createdAt": "2025-03-20T12:00:00.000Z",
  "updatedAt": "2025-03-20T12:00:00.000Z",
  "executions": [
    {
      "id": "exec_456",
      "status": "COMPLETED",
      "triggeredBy": "manual",
      "startedAt": "2025-03-20T12:01:00.000Z",
      "completedAt": "2025-03-20T12:01:15.000Z",
      "executionTime": 15000,
      "error": null
    }
  ],
  "isOwner": true,
  "canEdit": true,
  "canDuplicate": true,
  "userRole": "OWNER"
}

Update a Workflow

PUT /api/v1/workflows/{id}

Updates an existing workflow. All fields are optional; only include the fields you want to change.

When sending nodes/edges, build them against the node catalog. Responses from GET /api/v1/workflows/{id} round-trip cleanly: canvas runtime fields (width, height, positionAbsolute, selected, dragging) are stripped on read and on write, so you never persist stale view state.

Request Body

Field	Type	Description
name	string	Workflow name
description	string | null	Workflow description
nodes	Node[]	Updated nodes array
edges	Edge[]	Updated edges array
tags	string[]	Tags
isActive	boolean	Active status
webhookId	string	Webhook identifier
webhookUrl	string	Webhook callback URL

Request

curl -X PUT https://www.wireflow.ai/api/v1/workflows/cm1abc123 \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workflow Name",
    "isActive": false
  }'

Response 200 OK

Returns the full updated workflow object.

Delete a Workflow

DELETE /api/v1/workflows/{id}

Soft-deletes a workflow. The workflow is deactivated and marked as deleted but can be recovered by support.

Request

curl -X DELETE https://www.wireflow.ai/api/v1/workflows/cm1abc123 \
  -H "Authorization: Bearer sk-your-api-key"

Response 200 OK

{
  "success": true
}

Data Types

Node Object

Nodes represent AI models, inputs, and utilities on the workflow canvas. Every node uses the React Flow Node structure.

Field	Type	Required	Description
id	string	Yes	Unique node identifier (e.g. "node-1")
type	string	Yes	Always "basedNode" for standard nodes
position	object	Yes	Canvas layout coordinates: { "x": 0, "y": 0 }
data	object	Yes	Node configuration (see below)

data fields:

Field	Type	Required	Description
label	string	Yes	Display name shown on the node
category	string	Yes	Node category: "model", "input", "utility", "output", "logic"
nodeType	string	Yes	Identifies the model or utility (see common values below)
config	object	No	Node settings (prompt, seed, guidance_scale, etc.). This is the canonical bag.
params	object	No	Legacy read location. Avoid — see the warning below.
inputs	Port[]	No	Input port definitions: [{ "id": "image", "label": "Image", "type": "IMAGE" }]
outputs	Port[]	No	Output port definitions: [{ "id": "image", "label": "Image", "type": "IMAGE" }]

Write settings to config, not params. At run time the resolver merges {...config, ...params, ...inputs}, so params WINS over config — but normalization and rehydration only ever touch config. A value written to params therefore overrides the normalized one and is never itself normalized, which is how a node ends up running something the canvas does not show. params is a legacy read location kept for old graphs.

The position field controls where the node appears on the visual canvas. It has no effect on execution — the API uses it to persist layout when saving workflows.

Common nodeType values:

nodeType	Description
generate:flux_2	Flux 2 text-to-image
generate:flux_2_pro	Flux 2 Pro text-to-image
generate:nano_banana_pro	Nano Banana Pro image gen
generate:imagen3	Google Imagen 3
generate:imagen4	Google Imagen 4
generate:bytedance_seedream_v4_text_to_image	Seedream v4 text-to-image
edit:flux_2_edit	Flux 2 image editing
edit:nano_banana_pro_edit	Nano Banana Pro editing
edit:bytedance_seedream_v4_edit	Seedream v4 editing
video:kling_video_2_5_i2v	Kling 2.5 image-to-video
talking:veed_fabric	VEED Fabric talking head
input:text	Text input
input:image	Image/media upload
output:preview	Preview output
utility:prompt_concat	Prompt concatenator

Edge Object

Edges define connections between node ports.

Field	Type	Required	Description
id	string	Yes	Unique edge identifier (e.g. "edge-1")
source	string	Yes	Source node ID
target	string	Yes	Target node ID
sourceHandle	string	No	Output port ID on the source node (e.g. "out-image")
targetHandle	string	No	Input port ID on the target node (e.g. "in-image")

Validation limits: Max 100 nodes and 500 edges per workflow. Node data nesting is limited to 10 levels deep.

Permissions

Workflow access is determined by:

1. Workflow creator — full access
2. Media/project owner — full access if the workflow belongs to their project
3. Team member — access if the workflow belongs to a team project
4. Explicit permission — granted via sharing (EDIT or OWNER)

Delete requires ownership — team members need the OWNER role on the team to delete workflows.