Quick Start

n8n-client is easiest to understand if you think in three steps:

1. Create N8nClient with your n8n base URL and one authentication method.
2. Pick a typed handle such as workflow(), execution(), or project().
3. Call methods that map directly to the public API without hand-writing HTTP requests.

Installation

npm

npm install @egose/n8n-client --save

Yarn

yarn add @egose/n8n-client

pnpm

pnpm add @egose/n8n-client

Bun

bun add @egose/n8n-client

Authentication

The n8n Public API supports two authentication methods: API key and Bearer token.

Use exactly one of them. The client rejects configurations that provide both or neither.

API Key (recommended)

import N8nClient from '@egose/n8n-client';

const client = new N8nClient({
  baseUrl: 'http://localhost:5678',
  apiKey: 'your-n8n-api-key', // pragma: allowlist secret
});

Bearer Token (JWT)

const client = new N8nClient({
  baseUrl: 'http://localhost:5678',
  bearerToken: 'your-jwt-token',
});

First Script

This is the smallest useful script for checking that your instance URL, credentials, and client setup are correct:

import N8nClient from '@egose/n8n-client';

const client = new N8nClient({
  baseUrl: 'http://localhost:5678',
  apiKey: process.env.N8N_API_KEY!,
});

const { data: workflows } = await client.workflow().list({ limit: 5 });

for (const workflow of workflows) {
  console.log(`${workflow.id} ${workflow.name}`);
}

Basic Usage

List Workflows

const { data: workflows, nextCursor } = await client.workflow().list({
  limit: 10,
  active: true,
});

Get a Workflow

const workflow = await client.workflow().get('workflow-id');
console.log(workflow.name, workflow.active);

Create a Credential

const credential = await client.credential().create({
  name: 'My API Key',
  type: 'httpHeaderAuth',
  data: {
    headerName: 'Authorization',
    headerValue: 'Bearer secret-token',
  },
});

Manage Executions

// List error executions
const { data: errors } = await client.execution().list({
  status: 'error',
  workflowId: 'workflow-id',
});

// Stop a running execution
await client.execution().stop(executionId);

How The API Surface Is Organized

• Use client.workflow() for workflow lifecycle and tagging.
• Use client.execution() for monitoring, retrying, and stopping runs.
• Use client.project() and client.folder(projectId) for structure and access control.
• Use client.get(), client.post(), and the other low-level helpers only when you intentionally need to drop below a typed handle.

Organize with Projects

await client.project().create({ name: 'Production' });

await client.project().addMembers('project-id', [
  { userId: 'user-id', role: 'project:admin' },
]);

Resource Handles

Every n8n API resource has a typed handle:

Handle	Access	Description
WorkflowHandle	client.workflow()	Create, list, activate, archive workflows
ExecutionHandle	client.execution()	List, get, stop, retry executions
CredentialHandle	client.credential()	CRUD, test, transfer credentials
TagHandle	client.tag()	Manage workflow/execution tags
UserHandle	client.user()	List, create, delete users
VariableHandle	client.variable()	Manage environment variables
ProjectHandle	client.project()	CRUD projects and members
DataTableHandle	client.dataTable()	Tables, columns, and rows
FolderHandle	client.folder(projectId)	Project-scoped folder management
CommunityPackageHandle	client.communityPackage()	Install, update, uninstall packages
AuditHandle	client.audit()	Generate audit reports
InsightsHandle	client.insights()	Execution insights summary
SourceControlHandle	client.sourceControl()	Git-based source control
DiscoverHandle	client.discover()	Discover available resources
N8nPackageHandle	client.n8nPackage()	Import/export workflow packages

Next Steps

• Browse the API Reference for the full method surface.
• Read Philosophy if you want the design rationale behind handles, retries, and low-level request helpers.
• Check out Examples for end-to-end walkthroughs.