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	Stored as-is. Inbound trigger URLs are not available yet, see Webhooks
mediaId	string	No	Project/media ID to scope the workflow to

mediaId must name a media you own, belong to the team of, or hold edit access to. Anything else, including an id that does not exist, is refused with 403 forbidden and nothing is saved.

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. Run history is not included: use GET /api/v1/workflows/{id}/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,
  "linkPermission": "PRIVATE",
  "isPublished": false,
  "publishedSlug": null,
  "publishedAt": null,
  "publishSettings": null,
  "tags": ["image"],
  "createdAt": "2025-03-20T12:00:00.000Z",
  "updatedAt": "2025-03-20T12:00:00.000Z",
  "isOwner": true,
  "canEdit": true,
  "canDuplicate": true,
  "userRole": "OWNER"
}

Readers who are not the owner or an editor. A VIEW link (every published template) lets an anonymous visitor read the workflow, nodes included. What they do not get is the creator's integration and billing settings: webhookId, webhookUrl and lastEditorHeartbeatAt are omitted, secrets is null, and publishSettings is reduced. Every key that names a secret, token, key or password is removed at any depth, along with webhookUrl, dailyCreditBudget and executionEngine. Owners and editors get the full response above.

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.

The GET body can be sent back whole. linkPermission, isPublished, publishedSlug, publishedAt and publishSettings are not writable here, but a value equal to the stored one is accepted and ignored. Changing one returns 400 field_not_writable, naming every changed field and the endpoint that owns it: POST /api/v1/workflows/{id}/visibility for linkPermission, POST /api/v1/workflows/{id}/publish for the rest. If they differ because the workflow changed after your GET (the body's updatedAt or baseUpdatedAt is older than the stored one), you get 409 stale_write instead: reload and reapply.

Two more fields need care on a whole-body round trip:

• secrets is shown only to the workflow's creator. Everyone else gets null, and a null sent back by anyone but the creator is ignored, so it never clears the creator's secrets. A creator's null does clear them, so do the round trip with a key that has workflows:read: without it GET serves you as an anonymous visitor and secrets comes back null.
• poster sent back pins the stored thumbnail. Omit it if you want the graph's newest image to refresh it.

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	Stored as-is, see Webhooks
webhookUrl	string	Stored as-is. Nothing is sent to it: for a completion callback, pass webhook to POST /run
folderId	string | null	Move to a folder

folderId moves the workflow into a folder, or out of its folder with null. Only the workflow owner can move it, and the folder must be yours or belong to a team you are in (403 otherwise, 404 if it does not exist). Folders belong to one workspace, so a folder in another workspace moves the workflow there: its team becomes the folder's team (personal for your personal folders), as long as you are a current member of that team (400 folder_workspace_mismatch otherwise). Anyone who could reach the workflow only through its old team loses access. Direct shares and the link permission are unchanged, you stay the owner, runs bill the new team's pool, and each of the workflow's automations is re-pointed to the account its runs will charge (a teammate's automation never moves to a team they are not in). GET /api/v1/folders lists the folders of your active workspace only. POST /api/v1/workflows with an id that changes folderId follows the same rule, except it never changes the workflow's workspace: a folder in another workspace is a 400 folder_workspace_mismatch there, so use this PUT. Like the guarded fields above, a folderId that differs from the stored one because the workflow changed after your GET (the body's updatedAt or baseUpdatedAt is older) gets 409 stale_write, so a stale body never undoes someone else's move: reload and reapply.

A workflow created through this API is personal, while GET and POST /api/v1/folders use your active workspace. So when your active workspace is a team, every folder the API can list or create is in that team, and moving an API-created workflow into one with PUT /api/v1/workflows/:id { folderId } moves the workflow into the team. To keep API-created workflows personal while a team is active, create the folder in your personal workspace instead: POST /api/v1/folders takes an optional teamId, which must be a team you are currently a member of (your personal team counts; any other team is a 404, whether or not it exists). Without teamId the folder goes in your active workspace, as before.

The rest of a GET body is accepted and ignored: updatedAt, the per-reader fields (isOwner, canEdit, canDuplicate, userRole, media, meta), and any other stored field sent back with the value GET returned (or in a body older than the workflow, since counters like views move on their own). Any other key, including a read-only field you changed (teamId, say), is ignored and named in meta.warnings, never dropped silently. The warning lists every accepted key. Those keys will become a 400 unknown_parameter.

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.

Layout ships with the edit

position has no effect on execution, but a board is a picture a human opens, so a graph left as a pile of stacked cards discredits the work that produced it. Do not guess coordinates: card height is browser state and no caller outside the tab can get it right.

• Read real geometry. GET /api/v1/workflows/{id} returns every node with a read-only dims: { width, height, source }. Branch on source, never on the numbers: measured is a real rendered box, declared is a size the user set by dragging a resize handle, estimated is our per-type model.
• layoutPending is the routine outcome — branch on it first. After a structural edit meta.warnings normally carries a layoutPending: line, and it means NOTHING WAS MOVED: the graph is exactly as you wrote it. Two independent reasons produce it, and both are common. One, an editor tab may be holding the board — repositioning a board an open tab holds makes the editor's conflict self-heal read a harmless 409 as a foreign edit and wedges that user behind a banner they cannot clear, and the server cannot reliably rule the tab out, so it assumes the worst. Two, server-side arrangement is flag-gated and OFF by default until a durable editor-presence signal exists. Plan for this path.
• When arrangement is enabled and the board is provably quiet, a write that adds, removes or rewires nodes is instead ARRANGED by the write itself — topological columns, producers left of consumers, group frames fitted to their members with one uniform gap — and the response echoes the new positions with its own meta.warnings line. A write that changes only VALUES (a prompt, a result, a rename) is not a topology change and is never rearranged. Pass autoLayout: false to keep your own coordinates.
• Your grouping is never changed, on either path. It is a semantic choice only you can make, and a grouping the wiring disagrees with comes back as an advisory, never a silent regroup.
• Adds are guarded for you either way. A node this PUT ADDS that arrives with no position, stacked on another, or burying one is repositioned before it is persisted, and every move is named in the response's meta.warnings with the node id and its new coordinates. Only nodes the write added are ever moved, because an existing position belongs to the user.
• Removals are still yours on the pending path. A delete leaves a hole and a rewire crosses edges, and neither shows up anywhere else in the response body.
• Arrange on demand, any time. POST /api/v1/workflows/{id}/layout is the same engine as the in-app Auto Layout button and stays available whether or not the write arranged for you — it is what you call after a layoutPending. It is group-aware, and it refuses any board over 250 nodes or 750 edges with a 422. Pass a scope array of node ids to lay out just the part you changed.
• What "geometry only" actually covers. The layout authors node positions, a group box's size, and a group box's derived childNodeIds, and it DELETES the legacy ReactFlow parentId/parentNode/extent keys from any node it lays out (it applies absolute positions, which ReactFlow would otherwise read as parent-relative; only weavy-imported boards carry them). Your config, prompt, type, result and the edge list are never touched, so you do not need to re-verify the graph afterwards.

An edit is not done until the board is tidy.

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 1500 edges and a 4 MB request body per workflow (over 100 nodes is a lint warning, not a refusal). Over the edge cap, continue the next section on a second board. 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.