Create, update, and delete workflows via API

The workflow CRUD endpoints let you manage workflow definitions through the API. You can list, fetch, create, update, reorganize, and delete workflows without using the Knouds editor. Read operations (GET) require capability workflow:read. Write operations (POST, PUT, DELETE) require workflow:write AND ownership — you can only modify workflows you created. Both capabilities are available to Pro+ tiers. Free tier has no external API access; Free users use the canvas via session.

Workflows are user-owned content. The capability layer admits the request; the ownership check inside the handler (existing.createdBy === req.user.id) enforces that you can only edit your own workflows. There is no admin override on the standard endpoints.

List workflows

GET /api/workflows

Returns an array of workflow summaries for your account. Templates (workflows with isTemplate: true) created by other users that are visible platform-wide are also included. Auth: capability workflow:read. Response: an array of workflow summary objects.

string

The workflow’s URL slug and unique identifier.

string

The display name of the workflow.

string

The workflow’s description, if set.

string[]

Tag labels assigned to the workflow.

boolean

Whether this is a template (visible to all users).

boolean

Whether the workflow is hidden from your dashboard list.

boolean

Whether the workflow is archived.

object

Optional cover thumbnail { image, video? }.

string

Legacy thumbnail (data URL or S3 URL).

string

User id of the workflow’s owner.

number

Estimated credit cost per run, calculated from generator nodes and your tier. null if no generators.

string

ID of the folder this workflow lives in. null if at root level.

string

ISO 8601 timestamp of the last update.

Example:

curl https://knouds.ai/api/workflows \
  -H "x-api-key: $KNOUDS_KEY"

Get a single workflow

GET /api/workflows/:slug

Returns the full workflow JSON for a single workflow. The response shape is identical to the body accepted by POST /api/workflows — it is round-trip safe and suitable for backup, forking, or templating. Auth: capability workflow:read.

curl https://knouds.ai/api/workflows/my-thumbnail-pipeline \
  -H "x-api-key: $KNOUDS_KEY"

Create a workflow

POST /api/workflows

Creates a new workflow. The server slugifies the name field to generate the workflow’s slug, appending -2, -3, etc. if the slug is already taken. Auth: capability workflow:write. The created workflow is owned by your user (createdBy = your user id).

Free tier is capped at 1 saved workflow (maxWorkflows: 1). Creating a second workflow returns 403 WORKFLOW_CAP_REACHED. Pro+ tiers are uncapped.

Request body (any subset of these — name is required):

string

required

Display name. The server converts this to a URL slug (lowercase, hyphens) and uses it as the permanent identifier. The slug cannot be changed after creation.

string

Short description of what the workflow does.

string[]

Tag labels.

array

Node definitions. Each includes id, type, position, data.

array

Connections between nodes. Each includes id, source, target, sourceHandle, targetHandle.

object

Saved canvas viewport { x, y, zoom }. Editor restores this position on open.

boolean

When true, schema is accessible without auth via GET /api/workflows/:slug/public-schema.

boolean

When true, the workflow appears in every user’s Templates section. Templates skip the maxWorkflows cap.

object

Cover thumbnail { image, video? } (S3 URLs).

string

Folder ID to place the workflow in. Omit or pass null for root level.

Response: the created workflow JSON, including the assigned slug and timestamps.

curl -X POST https://knouds.ai/api/workflows \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Image Pipeline",
    "description": "Generates product images from a prompt",
    "tags": ["image"],
    "nodes": [],
    "edges": [],
    "viewport": { "x": 0, "y": 0, "zoom": 1 }
  }'

Update a workflow

PUT /api/workflows/:slug

Updates an existing workflow. You can pass a full or partial workflow JSON — any fields you include overwrite the stored values; fields you omit are preserved. Auth: capability workflow:write AND ownership. Editing another user’s workflow returns 404. Request body: any subset of the workflow JSON fields. The slug field is always read from the URL and cannot be changed via the request body.

A workflow’s slug is immutable. The URL slug is the disk filename, the API identifier, and the key used in usage logs. There is no rename operation. If you need a workflow with a different slug, create a new one and delete the old one.

Response: the full updated workflow JSON.

curl -X PUT https://knouds.ai/api/workflows/my-image-pipeline \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

Move a workflow

PUT /api/workflows/:slug/move

Moves a workflow into a folder or back to the root level. Separate from the general update because folder organization is independent from workflow content. Auth: capability workflow:write AND ownership.

string

The ID of the destination folder. Pass null to move the workflow back to the root level.

# Move to a folder
curl -X PUT https://knouds.ai/api/workflows/my-image-pipeline/move \
  -H "x-api-key: $KNOUDS_KEY" -H "Content-Type: application/json" \
  -d '{"folderId": "folder-abc123"}'

# Move back to root
curl -X PUT https://knouds.ai/api/workflows/my-image-pipeline/move \
  -H "x-api-key: $KNOUDS_KEY" -H "Content-Type: application/json" \
  -d '{"folderId": null}'

Delete a workflow

DELETE /api/workflows/:slug

Permanently deletes a workflow. This action cannot be undone. Auth: capability workflow:write AND ownership.

curl -X DELETE https://knouds.ai/api/workflows/my-image-pipeline \
  -H "x-api-key: $KNOUDS_KEY"

Workflow JSON schema

The full workflow object accepted and returned by these endpoints follows this shape:

{
  "slug": "my-workflow",
  "name": "My Workflow",
  "description": "What this workflow does",
  "tags": ["image", "automation"],
  "isTemplate": false,
  "hidden": false,
  "archived": false,
  "publicPlayground": false,
  "folderId": null,
  "thumbnail": null,
  "cover": { "image": "https://knouds-media.s3.../cover.png", "video": null },
  "createdBy": "user_abc...",
  "nodes": [],
  "edges": [],
  "viewport": { "x": 0, "y": 0, "zoom": 1 },
  "createdAt": "2026-04-30T00:00:00.000Z",
  "updatedAt": "2026-04-30T00:00:00.000Z"
}

The GET /api/workflows/:slug response is round-trip safe: you can GET a workflow, modify the JSON, and PUT it back without losing any fields.

Overview

Identity & Usage

Endpoints

Async & Webhooks

Create, update, and delete workflows via API

List workflows

Get a single workflow

Create a workflow

Update a workflow

Move a workflow

Delete a workflow

Workflow JSON schema

​List workflows

​Get a single workflow

​Create a workflow

​Update a workflow

​Move a workflow

​Delete a workflow

​Workflow JSON schema

List workflows

Get a single workflow

Create a workflow

Update a workflow

Move a workflow

Delete a workflow

Workflow JSON schema