0
# API Client
1

2
HTTP client methods for communication with the n8n backend API, handling workflows, credentials, executions, users, and other backend services.
3

4
## Capabilities
5

6
### Workflows API
7

8
Core workflow management operations.
9

10
```typescript { .api }
11
/**
12
 * Get new workflow template
13
 * @param context - Request context
14
 * @param data - Optional template data
15
 * @returns New workflow template
16
 */
17
function getNewWorkflow(context: IRestApiContext, data?: IDataObject): Promise<NewWorkflowResponse>;
18

19
/**
20
 * Fetch workflow by ID
21
 * @param context - Request context
22
 * @param id - Workflow ID
23
 * @returns Workflow data
24
 */
25
function getWorkflow(context: IRestApiContext, id: string): Promise<IWorkflowDb>;
26

27
/**
28
 * List workflows with filtering
29
 * @param context - Request context
30
 * @param filter - Filter criteria
31
 * @param options - Pagination and sorting options
32
 * @returns Paginated workflows list
33
 */
34
function getWorkflows(
35
  context: IRestApiContext,
36
  filter?: WorkflowsListRequestFilter,
37
  options?: ListRequestOptions
38
): Promise<WorkflowsListResponse>;
39

40
/**
41
 * Create new workflow
42
 * @param context - Request context
43
 * @param data - Workflow creation data
44
 * @returns Created workflow
45
 */
46
function createWorkflow(context: IRestApiContext, data: WorkflowDataCreate): Promise<IWorkflowDb>;
47

48
/**
49
 * Update existing workflow
50
 * @param context - Request context
51
 * @param id - Workflow ID
52
 * @param data - Updated workflow data
53
 * @returns Updated workflow
54
 */
55
function updateWorkflow(
56
  context: IRestApiContext, 
57
  id: string, 
58
  data: WorkflowDataUpdate
59
): Promise<IWorkflowDb>;
60

61
/**
62
 * Delete workflow
63
 * @param context - Request context
64
 * @param id - Workflow ID
65
 */
66
function deleteWorkflow(context: IRestApiContext, id: string): Promise<void>;
67

68
/**
69
 * Get active workflow IDs
70
 * @param context - Request context
71
 * @returns Array of active workflow IDs
72
 */
73
function getActiveWorkflows(context: IRestApiContext): Promise<string[]>;
74
```
75

76
### Execution Management
77

78
Workflow execution operations.
79

80
```typescript { .api }
81
/**
82
 * Execute workflow
83
 * @param context - Request context
84
 * @param data - Execution configuration
85
 * @returns Execution response
86
 */
87
function executeWorkflow(
88
  context: IRestApiContext, 
89
  data: IStartRunData
90
): Promise<IExecutionPushResponse>;
91

92
/**
93
 * Get workflow executions
94
 * @param context - Request context
95
 * @param filter - Execution filter criteria
96
 * @param options - Pagination options
97
 * @returns Paginated executions list
98
 */
99
function getExecutions(
100
  context: IRestApiContext,
101
  filter?: ExecutionsQueryFilter,
102
  options?: ListRequestOptions
103
): Promise<IExecutionsListResponse>;
104

105
/**
106
 * Get execution details
107
 * @param context - Request context
108
 * @param executionId - Execution ID
109
 * @returns Execution data
110
 */
111
function getExecutionData(
112
  context: IRestApiContext, 
113
  executionId: string
114
): Promise<IExecutionResponse>;
115

116
/**
117
 * Stop execution
118
 * @param context - Request context
119
 * @param executionId - Execution ID
120
 * @returns Stop response
121
 */
122
function stopExecution(
123
  context: IRestApiContext, 
124
  executionId: string
125
): Promise<IExecutionsStopData>;
126

127
/**
128
 * Delete executions
129
 * @param context - Request context
130
 * @param filter - Deletion filter
131
 * @returns Deletion summary
132
 */
133
function deleteExecutions(
134
  context: IRestApiContext, 
135
  filter: IExecutionDeleteFilter
136
): Promise<void>;
137

138
/**
139
 * Get running executions
140
 * @param context - Request context
141
 * @param filter - Filter criteria
142
 * @returns Running executions
143
 */
144
function getActiveExecutions(
145
  context: IRestApiContext,
146
  filter?: ExecutionsQueryFilter
147
): Promise<ExecutionSummary[]>;
148
```
149

150
### Credentials API
151

152
Credential management operations.
153

154
```typescript { .api }
155
/**
156
 * Get all credentials
157
 * @param context - Request context
158
 * @param filter - Filter criteria
159
 * @param includeScopes - Include permission scopes
160
 * @param onlySharedWithMe - Only shared credentials
161
 * @returns Credentials list
162
 */
163
function getAllCredentials(
164
  context: IRestApiContext,
165
  filter?: CredentialsListRequestFilter,
166
  includeScopes?: boolean,
167
  onlySharedWithMe?: boolean
168
): Promise<ICredentialsResponse[]>;
169

170
/**
171
 * Create new credential
172
 * @param context - Request context
173
 * @param data - Credential data
174
 * @returns Created credential
175
 */
176
function createNewCredential(
177
  context: IRestApiContext, 
178
  data: ICredentialsDecrypted
179
): Promise<ICredentialsResponse>;
180

181
/**
182
 * Update credential
183
 * @param context - Request context
184
 * @param id - Credential ID
185
 * @param data - Updated credential data
186
 * @returns Updated credential
187
 */
188
function updateCredential(
189
  context: IRestApiContext,
190
  id: string,
191
  data: ICredentialsDecrypted
192
): Promise<ICredentialsResponse>;
193

194
/**
195
 * Delete credential
196
 * @param context - Request context
197
 * @param id - Credential ID
198
 */
199
function deleteCredential(context: IRestApiContext, id: string): Promise<void>;
200

201
/**
202
 * Get credential data
203
 * @param context - Request context
204
 * @param id - Credential ID
205
 * @returns Credential details
206
 */
207
function getCredentialData(
208
  context: IRestApiContext, 
209
  id: string
210
): Promise<ICredentialsDecryptedResponse>;
211

212
/**
213
 * Test credential connection
214
 * @param context - Request context
215
 * @param data - Credential test data
216
 * @returns Test result
217
 */
218
function testCredential(
219
  context: IRestApiContext, 
220
  data: ICredentialsDecrypted
221
): Promise<INodeCredentialTestResult>;
222
```
223

224
### OAuth Integration
225

226
OAuth authentication flow helpers.
227

228
```typescript { .api }
229
/**
230
 * Get OAuth1 authorization URL
231
 * @param context - Request context
232
 * @param data - OAuth1 configuration
233
 * @returns Authorization URL
234
 */
235
function oAuth1CredentialAuthorize(
236
  context: IRestApiContext, 
237
  data: IOAuth1Options
238
): Promise<string>;
239

240
/**
241
 * Get OAuth2 authorization URL
242
 * @param context - Request context
243
 * @param data - OAuth2 configuration
244
 * @returns Authorization URL
245
 */
246
function oAuth2CredentialAuthorize(
247
  context: IRestApiContext, 
248
  data: IOAuth2Options
249
): Promise<string>;
250

251
interface IOAuth1Options {
252
  credentialId: string;
253
}
254

255
interface IOAuth2Options {
256
  credentialId: string;
257
  state?: string;
258
}
259
```
260

261
### Folder Management
262

263
Workflow folder organization.
264

265
```typescript { .api }
266
/**
267
 * Create workflow folder
268
 * @param context - Request context
269
 * @param projectId - Project ID
270
 * @param name - Folder name
271
 * @param parentFolderId - Parent folder ID
272
 * @returns Created folder
273
 */
274
function createFolder(
275
  context: IRestApiContext,
276
  projectId: string,
277
  name: string,
278
  parentFolderId?: string
279
): Promise<FolderCreateResponse>;
280

281
/**
282
 * Delete folder
283
 * @param context - Request context
284
 * @param projectId - Project ID
285
 * @param folderId - Folder ID
286
 * @param transferToFolderId - Target folder for content
287
 */
288
function deleteFolder(
289
  context: IRestApiContext,
290
  projectId: string,
291
  folderId: string,
292
  transferToFolderId?: string
293
): Promise<void>;
294

295
/**
296
 * Rename folder
297
 * @param context - Request context
298
 * @param projectId - Project ID
299
 * @param folderId - Folder ID
300
 * @param name - New folder name
301
 * @returns Updated folder
302
 */
303
function renameFolder(
304
  context: IRestApiContext,
305
  projectId: string,
306
  folderId: string,
307
  name: string
308
): Promise<FolderCreateResponse>;
309

310
/**
311
 * Move folder
312
 * @param context - Request context
313
 * @param projectId - Project ID
314
 * @param folderId - Folder ID
315
 * @param parentFolderId - New parent folder ID
316
 * @returns Updated folder
317
 */
318
function moveFolder(
319
  context: IRestApiContext,
320
  projectId: string,
321
  folderId: string,
322
  parentFolderId?: string
323
): Promise<FolderCreateResponse>;
324
```
325

326
### Tags API
327

328
Tag management for workflows and credentials.
329

330
```typescript { .api }
331
/**
332
 * Get all tags
333
 * @param context - Request context
334
 * @param withUsageCount - Include usage statistics
335
 * @returns Tags list
336
 */
337
function getTags(context: IRestApiContext, withUsageCount?: boolean): Promise<ITag[]>;
338

339
/**
340
 * Create new tag
341
 * @param context - Request context
342
 * @param data - Tag data
343
 * @returns Created tag
344
 */
345
function createTag(context: IRestApiContext, data: ITagCreatePayload): Promise<ITag>;
346

347
/**
348
 * Update tag
349
 * @param context - Request context
350
 * @param id - Tag ID
351
 * @param data - Updated tag data
352
 * @returns Updated tag
353
 */
354
function updateTag(context: IRestApiContext, id: string, data: ITagUpdatePayload): Promise<ITag>;
355

356
/**
357
 * Delete tag
358
 * @param context - Request context
359
 * @param id - Tag ID
360
 * @returns Deletion result
361
 */
362
function deleteTag(context: IRestApiContext, id: string): Promise<{ success: boolean }>;
363

364
interface ITagCreatePayload {
365
  name: string;
366
}
367

368
interface ITagUpdatePayload {
369
  name: string;
370
}
371
```
372

373
### AI API
374

375
AI-powered workflow assistance.
376

377
```typescript { .api }
378
/**
379
 * Generate workflow from natural language description
380
 * @param context - Request context
381
 * @param prompt - Natural language prompt
382
 * @returns Generated workflow data
383
 */
384
function generateWorkflow(context: IRestApiContext, prompt: string): Promise<WorkflowData>;
385

386
/**
387
 * Get AI chat response
388
 * @param context - Request context
389
 * @param message - User message
390
 * @param sessionId - Chat session ID
391
 * @returns AI response
392
 */
393
function aiChat(
394
  context: IRestApiContext, 
395
  message: string, 
396
  sessionId?: string
397
): Promise<AiChatResponse>;
398

399
/**
400
 * Generate node configuration suggestions
401
 * @param context - Request context
402
 * @param nodeType - Node type name
403
 * @param context - Node context
404
 * @returns Configuration suggestions
405
 */
406
function getNodeSuggestions(
407
  context: IRestApiContext,
408
  nodeType: string,
409
  nodeContext: IDataObject
410
): Promise<NodeSuggestion[]>;
411

412
interface AiChatResponse {
413
  message: string;
414
  sessionId: string;
415
  suggestions?: string[];
416
}
417

418
interface NodeSuggestion {
419
  parameter: string;
420
  value: NodeParameterValueType;
421
  confidence: number;
422
}
423
```
424

425
### User Management
426

427
User and authentication operations.
428

429
```typescript { .api }
430
/**
431
 * Get current user info
432
 * @param context - Request context
433
 * @returns Current user data
434
 */
435
function getCurrentUser(context: IRestApiContext): Promise<IUserResponse>;
436

437
/**
438
 * Update current user
439
 * @param context - Request context
440
 * @param data - Updated user data
441
 * @returns Updated user data
442
 */
443
function updateCurrentUser(
444
  context: IRestApiContext, 
445
  data: Partial<IUser>
446
): Promise<IUserResponse>;
447

448
/**
449
 * Get all users (admin only)
450
 * @param context - Request context
451
 * @returns Users list
452
 */
453
function getUsers(context: IRestApiContext): Promise<IUserResponse[]>;
454

455
/**
456
 * Invite user (admin only)
457
 * @param context - Request context
458
 * @param data - Invitation data
459
 * @returns Invitation result
460
 */
461
function inviteUsers(
462
  context: IRestApiContext, 
463
  data: Array<{ email: string; role: InvitableRoleName }>
464
): Promise<IInviteResponse[]>;
465

466
/**
467
 * Delete user (admin only)
468
 * @param context - Request context
469
 * @param userId - User ID
470
 * @param transferId - Transfer workflows to user ID
471
 */
472
function deleteUser(
473
  context: IRestApiContext, 
474
  userId: string, 
475
  transferId?: string
476
): Promise<void>;
477
```
478

479
## Usage Examples
480

481
**Workflow Operations:**
482

483
```typescript
484
import { workflowsApi } from '@/api/workflows';
485
import { useRootStore } from '@/stores/n8nRootStore';
486

487
const rootStore = useRootStore();
488

489
// Create new workflow
490
const workflow = await workflowsApi.createWorkflow(rootStore.getRestApiContext, {
491
  name: 'My New Workflow',
492
  nodes: [],
493
  connections: {}
494
});
495

496
// Update workflow
497
const updatedWorkflow = await workflowsApi.updateWorkflow(
498
  rootStore.getRestApiContext,
499
  workflow.id,
500
  {
501
    name: 'Updated Workflow Name',
502
    active: true
503
  }
504
);
505

506
// Execute workflow
507
const execution = await workflowsApi.executeWorkflow(
508
  rootStore.getRestApiContext,
509
  {
510
    workflowData: workflow
511
  }
512
);
513
```
514

515
**Credential Management:**
516

517
```typescript
518
import { credentialsApi } from '@/api/credentials';
519

520
// Get all credentials
521
const credentials = await credentialsApi.getAllCredentials(
522
  rootStore.getRestApiContext,
523
  { filter: { type: 'httpHeaderAuth' } }
524
);
525

526
// Test credential
527
const testResult = await credentialsApi.testCredential(
528
  rootStore.getRestApiContext,
529
  {
530
    type: 'httpHeaderAuth',
531
    data: {
532
      name: 'Authorization',
533
      value: 'Bearer token123'
534
    }
535
  }
536
);
537

538
if (testResult.status === 'OK') {
539
  console.log('Credential test successful');
540
}
541
```
542

543
## Types
544

545
```typescript { .api }
546
interface IRestApiContext {
547
  baseUrl: string;
548
  sessionId?: string;
549
}
550

551
interface WorkflowsListRequestFilter {
552
  active?: boolean;
553
  tags?: string[];
554
  search?: string;
555
  projectId?: string;
556
}
557

558
interface ListRequestOptions {
559
  limit?: number;
560
  offset?: number;
561
  orderBy?: string;
562
  orderDirection?: 'ASC' | 'DESC';
563
}
564

565
interface WorkflowsListResponse {
566
  count: number;
567
  data: WorkflowListItem[];
568
}
569

570
interface NewWorkflowResponse {
571
  name: string;
572
  defaultSettings: IWorkflowSettings;
573
}
574

575
interface INodeCredentialTestResult {
576
  status: 'OK' | 'Error';
577
  message?: string;
578
}
579

580
interface ExecutionsQueryFilter {
581
  status?: ExecutionStatus[];
582
  projectId?: string;
583
  workflowId?: string;
584
  finished?: boolean;
585
  waitTill?: boolean;
586
  metadata?: Array<{ key: string; value: string }>;
587
  startedAfter?: string;
588
  startedBefore?: string;
589
}
590

591
interface IExecutionsListResponse {
592
  count: number;
593
  results: ExecutionSummary[];
594
  estimated: boolean;
595
}
596

597
interface CredentialsListRequestFilter {
598
  type?: string;
599
  search?: string;
600
  projectId?: string;
601
}
602

603
type InvitableRoleName = 'member' | 'admin';
604

605
interface IInviteResponse {
606
  user: {
607
    id: string;
608
    email: string;
609
    emailSent: boolean;
610
    inviteAcceptUrl: string;
611
    role: string;
612
  };
613
  error?: string;
614
}
615
```