Workflow API

WorkflowClient manages n8n workflows — create, list, activate, deactivate, archive, transfer, and manage tags and versions.

Use this handle when you are working with workflow lifecycle operations. It is the largest handle in the client because the n8n API exposes both CRUD operations and workflow-specific actions here.

Access

const workflow = client.workflows();

Methods

Common Tasks

• list workflows for a project or environment
• fetch a workflow before editing or transferring it
• activate, deactivate, archive, and unarchive workflows
• manage workflow tags and inspect historical versions

list(params?)

List workflows with optional filters.

const { data, nextCursor } = await client.workflows().list({
  limit: 10,
  active: true,
  tags: 'production',
  name: 'deploy',
  projectId: 'proj-1',
  excludePinnedData: true,
});

get(id, params?)

Get a workflow by ID.

const workflow = await client.workflows().get('wf-123', {
  excludePinnedData: false,
});

create(data)

Create a new workflow.

const workflow = await client.workflows().create({
  name: 'My Workflow',
  nodes: [{ name: 'Start', type: 'n8n-nodes-base.start', position: [0, 0], parameters: {} }],
  connections: {},
  settings: { executionOrder: 'v1' },
});

update(id, data)

Update a workflow. The public API expects the full workflow body, not a partial patch.

const current = await client.workflows().get('wf-123');

const updated = await client.workflows().update('wf-123', {
  name: 'Updated Name',
  description: current.description,
  nodes: current.nodes,
  connections: current.connections,
  settings: current.settings ?? {},
  staticData: current.staticData,
  pinData: current.pinData,
});

delete(id)

Delete a workflow.

const deleted = await client.workflows().delete('wf-123');

activate(id, data?)

Activate a workflow. You can optionally send version metadata when activating a specific revision.

const activated = await client.workflows().activate('wf-123', {
  versionId: 'v-2',
  name: 'Production version',
});

deactivate(id)

Deactivate a workflow.

const deactivated = await client.workflows().deactivate('wf-123');

archive(id) / unarchive(id)

Archive or unarchive a workflow.

await client.workflows().archive('wf-123');
await client.workflows().unarchive('wf-123');

transfer(id, destinationProjectId)

Move a workflow to another project.

await client.workflows().transfer('wf-123', 'proj-456');

getTags(id) / updateTags(id, tags)

Get or update tags on a workflow.

const tags = await client.workflows().getTags('wf-123');
const updatedTags = await client.workflows().updateTags('wf-123', [
  { id: 'tag-1' },
  { id: 'tag-2' },
]);

getVersion(id, versionId)

Get a specific workflow version.

const version = await client.workflows().getVersion('wf-123', 'v-1');

WorkflowResource

Use getResource() or createResource() to get a bound WorkflowResource instance that wraps the workflow data and exposes convenience methods.

const resource = await client.workflows().getResource('wf-123');
const created = await client.workflows().createResource({
  name: 'New Workflow',
  nodes: [],
  connections: {},
  settings: {},
});

Properties

Property	Type	Description
id	string	Workflow ID
name	string	Workflow name
active	boolean	Whether the workflow is active
isArchived	boolean	Whether the workflow is archived
versionId	string	Current version ID

Methods

Method	Returns	Description
update(data)	this	Full update — replaces snapshot with the API response
patch(data)	this	Convenience update — merges partial fields into the current workflow snapshot, then sends a full update body
delete()	Workflow	Delete the workflow
activate(data?)	this	Activate the workflow
deactivate()	this	Deactivate the workflow
archive()	this	Archive the workflow
unarchive()	this	Unarchive the workflow
transfer(destinationProjectId)	void	Move to another project
getTags()	Tag[]	List tags on the workflow
updateTags(tags)	Tag[]	Replace tags on the workflow
getVersion(versionId)	WorkflowVersion	Fetch a specific version
executions()	WorkflowExecutionResourceCollection	Scope queries to this workflow

Snapshot management

Mutating methods (update, patch, activate, deactivate, archive, unarchive) call replaceSnapshot() under the hood, so resource.data stays current after each call. updateTags() calls mergeSnapshot() to patch the tags field without re-fetching the full workflow.

Nested executions

resource.executions() returns a collection scoped to the workflow:

const runs = await workflow.executions().list({ status: 'error', limit: 10 });
const runResource = await workflow.executions().getResource(123);

Both get and getResource verify the execution belongs to this workflow via paginated list before fetching.

Typical Flow

const workflow = client.workflows();

const { data } = await workflow.list({ projectId: 'proj-1', active: false, limit: 10 });

if (data[0]) {
  await workflow.activate(data[0].id);
}

Typical Flow with Resource

const resource = await client.workflows().getResource('wf-123');

await resource.update({
  name: 'Updated Name',
  description: resource.data.description,
  nodes: resource.data.nodes,
  connections: resource.data.connections,
  settings: resource.data.settings ?? {},
});

await resource.activate();

const runs = await resource.executions().list({ status: 'error', limit: 5 });