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 resource client such as workflows(), executions(), or projects().
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.workflows().list({ limit: 5 });

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

Basic Usage

List Workflows

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

Get a Workflow

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

Create a Credential

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

Manage Executions

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

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

How The API Surface Is Organized

• Use client.workflows() for workflow lifecycle and tagging.
• Use client.executions() for monitoring, retrying, and stopping runs.
• Use client.projects() and client.folders(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 resource client.

Organize with Projects

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

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

Resource Clients

Every n8n API resource has a typed client:

Client	Access	Description
WorkflowClient	client.workflows()	Create, list, activate, archive workflows
ExecutionClient	client.executions()	List, get, stop, retry executions
CredentialClient	client.credentials()	CRUD, test, transfer credentials
TagClient	client.tags()	Manage workflow/execution tags
UserClient	client.users()	List, create, delete users
VariableClient	client.variables()	Manage environment variables
ProjectClient	client.projects()	CRUD projects and members
DataTableClient	client.dataTables()	Tables, columns, and rows
FolderClient	client.folders(projectId)	Project-scoped folder management
CommunityPackageClient	client.communityPackages()	Install, update, uninstall packages
AuditClient	client.audit()	Generate audit reports
InsightsClient	client.insights()	Execution insights summary
SourceControlClient	client.sourceControl()	Git-based source control
SecurityPolicyClient	client.securityPolicy()	Instance security policy settings
DiscoverClient	client.discover()	Discover available resources
N8nPackageClient	client.n8nPackage()	Import/export workflow packages

When you want bound instance methods instead of plain API objects, use getResource() or listResources(). The full model is documented on the N8nClient API page.

Next Steps

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