0
# Runtime Operations
1

2
Programmatic access to Node-RED's runtime system for administrative applications. The runtime API provides comprehensive control over flows, nodes, settings, and other runtime components without requiring the editor interface.
3

4
## Capabilities
5

6
### Flow Management
7

8
Manage flow configurations programmatically including reading, writing, and deploying flows.
9

10
```javascript { .api }
11
/**
12
 * Flow management API
13
 */
14
interface FlowsAPI {
15
    getFlows(opts: RequestOptions): Promise<FlowConfig[]>;
16
    setFlows(opts: RequestOptions & { flows: FlowConfig[]; deploymentType?: string }): Promise<DeploymentResult>;
17
    addFlow(opts: RequestOptions & { flow: FlowConfig }): Promise<string>;
18
    getFlow(opts: RequestOptions & { id: string }): Promise<FlowConfig>;
19
    updateFlow(opts: RequestOptions & { id: string; flow: FlowConfig }): Promise<string>;
20
    deleteFlow(opts: RequestOptions & { id: string }): Promise<void>;
21
    getNodeCredentials(opts: RequestOptions & { type: string; id: string }): Promise<object>;
22
    getState(opts: RequestOptions): Promise<FlowState>;
23
    setState(opts: RequestOptions & { state: "start" | "stop" }): Promise<FlowState>;
24
}
25

26
/**
27
 * Get current flow configuration
28
 * @param opts - Request options
29
 * @returns Promise resolving to array of flow configurations
30
 */
31
RED.runtime.flows.getFlows(opts: RequestOptions): Promise<FlowConfig[]>;
32

33
/**
34
 * Set complete flow configuration (full deployment)
35
 * @param opts - Request options with flow data
36
 * @returns Promise resolving to deployment result
37
 */
38
RED.runtime.flows.setFlows(opts: RequestOptions & { flows: FlowConfig[] }): Promise<DeploymentResult>;
39

40
/**
41
 * Add a new flow
42
 * @param opts - Request options with flow configuration
43
 * @returns Promise resolving to the new flow ID
44
 */
45
RED.runtime.flows.addFlow(opts: RequestOptions & { flow: FlowConfig }): Promise<string>;
46

47
/**
48
 * Get individual flow configuration
49
 * @param opts - Request options with flow ID
50
 * @returns Promise resolving to flow configuration
51
 */
52
RED.runtime.flows.getFlow(opts: RequestOptions & { id: string }): Promise<FlowConfig>;
53

54
/**
55
 * Update existing flow configuration
56
 * @param opts - Request options with flow ID and updated configuration
57
 * @returns Promise resolving to the updated flow ID
58
 */
59
RED.runtime.flows.updateFlow(opts: RequestOptions & { id: string; flow: FlowConfig }): Promise<string>;
60

61
/**
62
 * Delete a flow
63
 * @param opts - Request options with flow ID
64
 * @returns Promise resolving when flow is deleted
65
 */
66
RED.runtime.flows.deleteFlow(opts: RequestOptions & { id: string }): Promise<void>;
67

68
/**
69
 * Get node credentials (safe/filtered version)
70
 * @param opts - Request options with node type and ID
71
 * @returns Promise resolving to safe credentials object
72
 */
73
RED.runtime.flows.getNodeCredentials(opts: RequestOptions & { type: string; id: string }): Promise<object>;
74

75
/**
76
 * Get current flow runtime state
77
 * @param opts - Request options
78
 * @returns Promise resolving to flow state information
79
 */
80
RED.runtime.flows.getState(opts: RequestOptions): Promise<FlowState>;
81

82
/**
83
 * Set flow runtime state (start/stop flows)
84
 * @param opts - Request options with target state
85
 * @returns Promise resolving to updated flow state
86
 */
87
RED.runtime.flows.setState(opts: RequestOptions & { state: "start" | "stop" }): Promise<FlowState>;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
const RED = require("node-red");
94

95
// Get all flows
96
const flows = await RED.runtime.flows.getFlows({});
97
console.log(`Found ${flows.length} flows`);
98

99
// Add a new flow
100
const newFlow = {
101
    type: "tab",
102
    label: "My New Flow",
103
    disabled: false,
104
    info: ""
105
};
106
const flowId = await RED.runtime.flows.addFlow({ flow: newFlow });
107

108
// Get specific flow
109
const specificFlow = await RED.runtime.flows.getFlow({ id: flowId });
110
console.log(`Flow label: ${specificFlow.label}`);
111

112
// Update flow
113
const updatedFlow = { ...specificFlow, label: "Updated Flow Name" };
114
await RED.runtime.flows.updateFlow({ id: flowId, flow: updatedFlow });
115

116
// Deploy flows with validation
117
const deployResult = await RED.runtime.flows.setFlows({
118
    flows: updatedFlows,
119
    deploymentType: "full"
120
});
121

122
// Flow state management
123
const currentState = await RED.runtime.flows.getState({});
124
console.log(`Current flow state: ${currentState.state}`);
125

126
// Stop flows
127
const stoppedState = await RED.runtime.flows.setState({ state: "stop" });
128
console.log(`Flows stopped: ${stoppedState.state}`);
129

130
// Start flows
131
const startedState = await RED.runtime.flows.setState({ state: "start" });
132
console.log(`Flows started: ${startedState.state}`);
133

134
// Get node credentials (returns safe/filtered credentials)
135
const credentials = await RED.runtime.flows.getNodeCredentials({ 
136
    type: "mqtt-broker", 
137
    id: "broker-node-id" 
138
});
139
console.log("Has username:", credentials.has_username);
140
```
141

142
### Node Management
143

144
Manage installed node types and modules, including enabling/disabling nodes and installing new node packages.
145

146
```javascript { .api }
147
/**
148
 * Node management API
149
 */
150
interface NodesAPI {
151
    getNodeList(opts: RequestOptions): Promise<NodeInfo[]>;
152
    getNodeInfo(opts: RequestOptions & { id: string }): Promise<NodeInfo>;
153
    getNodeConfig(opts: RequestOptions & { id: string; lang?: string }): Promise<string>;
154
    getNodeConfigs(opts: RequestOptions & { lang?: string }): Promise<string>;
155
    getModuleInfo(opts: RequestOptions & { module: string }): Promise<ModuleInfo>;
156
    addModule(opts: RequestOptions & { module?: string; version?: string; tarball?: TarballInfo; url?: string }): Promise<ModuleInfo>;
157
    removeModule(opts: RequestOptions & { module: string }): Promise<void>;
158
    setModuleState(opts: RequestOptions & { module: string; enabled: boolean }): Promise<ModuleInfo>;
159
    setNodeSetState(opts: RequestOptions & { id: string; enabled: boolean }): Promise<NodeInfo>;
160
    getModuleCatalogs(opts: RequestOptions & { lang?: string }): Promise<object>;
161
    getModuleCatalog(opts: RequestOptions & { module: string; lang?: string }): Promise<object>;
162
    getIconList(opts: RequestOptions): Promise<IconList>;
163
    getIcon(opts: RequestOptions & { module: string; icon: string }): Promise<Buffer | null>;
164
    getModuleResource(opts: RequestOptions & { module: string; path: string }): Promise<Buffer | null>;
165
}
166

167
/**
168
 * Get list of all installed node types
169
 * @param opts - Request options
170
 * @returns Promise resolving to array of node information
171
 */
172
RED.runtime.nodes.getNodeList(opts: RequestOptions): Promise<NodeInfo[]>;
173

174
/**
175
 * Get all node HTML configurations
176
 * @param opts - Request options with optional language
177
 * @returns Promise resolving to combined HTML configuration for all nodes
178
 */
179
RED.runtime.nodes.getNodeConfigs(opts: RequestOptions & { lang?: string }): Promise<string>;
180

181
/**
182
 * Get information about a specific module
183
 * @param opts - Request options with module name
184
 * @returns Promise resolving to module information
185
 */
186
RED.runtime.nodes.getModuleInfo(opts: RequestOptions & { module: string }): Promise<ModuleInfo>;
187

188
/**
189
 * Install a node module from npm, tarball, or URL
190
 * @param opts - Request options with module details
191
 * @returns Promise resolving to installation result
192
 */
193
RED.runtime.nodes.addModule(opts: RequestOptions & { 
194
    module?: string; 
195
    version?: string; 
196
    tarball?: TarballInfo; 
197
    url?: string 
198
}): Promise<ModuleInfo>;
199

200
/**
201
 * Remove/uninstall a node module
202
 * @param opts - Request options with module name
203
 * @returns Promise resolving when module is uninstalled
204
 */
205
RED.runtime.nodes.removeModule(opts: RequestOptions & { module: string }): Promise<void>;
206

207
/**
208
 * Enable or disable an entire module
209
 * @param opts - Request options with module name and enabled state
210
 * @returns Promise resolving to updated module information
211
 */
212
RED.runtime.nodes.setModuleState(opts: RequestOptions & { module: string; enabled: boolean }): Promise<ModuleInfo>;
213

214
/**
215
 * Enable or disable a specific node set
216
 * @param opts - Request options with node set ID and enabled state
217
 * @returns Promise resolving to updated node information
218
 */
219
RED.runtime.nodes.setNodeSetState(opts: RequestOptions & { id: string; enabled: boolean }): Promise<NodeInfo>;
220

221
/**
222
 * Get message catalogs for all modules
223
 * @param opts - Request options with optional language
224
 * @returns Promise resolving to message catalogs object
225
 */
226
RED.runtime.nodes.getModuleCatalogs(opts: RequestOptions & { lang?: string }): Promise<object>;
227

228
/**
229
 * Get message catalog for a specific module
230
 * @param opts - Request options with module name and optional language
231
 * @returns Promise resolving to module's message catalog
232
 */
233
RED.runtime.nodes.getModuleCatalog(opts: RequestOptions & { module: string; lang?: string }): Promise<object>;
234

235
/**
236
 * Get list of all available icons from installed modules
237
 * @param opts - Request options
238
 * @returns Promise resolving to icon list
239
 */
240
RED.runtime.nodes.getIconList(opts: RequestOptions): Promise<IconList>;
241

242
/**
243
 * Get icon file as buffer
244
 * @param opts - Request options with module and icon name
245
 * @returns Promise resolving to icon buffer or null if not found
246
 */
247
RED.runtime.nodes.getIcon(opts: RequestOptions & { module: string; icon: string }): Promise<Buffer | null>;
248

249
/**
250
 * Get module resource file
251
 * @param opts - Request options with module name and resource path
252
 * @returns Promise resolving to resource buffer or null if not found
253
 */
254
RED.runtime.nodes.getModuleResource(opts: RequestOptions & { module: string; path: string }): Promise<Buffer | null>;
255
```
256

257
**Usage Examples:**
258

259
```javascript
260
// List all installed nodes
261
const nodes = await RED.runtime.nodes.getNodeList({});
262
nodes.forEach(node => {
263
    console.log(`${node.name}: ${node.enabled ? 'enabled' : 'disabled'}`);
264
});
265

266
// Install a new node module
267
try {
268
    const result = await RED.runtime.nodes.addModule({ 
269
        module: "node-red-contrib-influxdb" 
270
    });
271
    console.log(`Installed module: ${result.name}`);
272
} catch (err) {
273
    console.error("Installation failed:", err.message);
274
}
275

276
// Enable/disable a specific node set
277
await RED.runtime.nodes.setNodeSetState({ id: "inject", enabled: false });
278
await RED.runtime.nodes.setNodeSetState({ id: "inject", enabled: true });
279

280
// Enable/disable an entire module
281
await RED.runtime.nodes.setModuleState({ 
282
    module: "node-red-contrib-influxdb", 
283
    enabled: false 
284
});
285

286
// Get module information
287
const moduleInfo = await RED.runtime.nodes.getModuleInfo({ 
288
    module: "node-red-contrib-influxdb" 
289
});
290
console.log(`Module version: ${moduleInfo.version}`);
291

292
// Get available icons
293
const iconList = await RED.runtime.nodes.getIconList({});
294
console.log(`Available icons:`, iconList);
295

296
// Get specific icon
297
const iconBuffer = await RED.runtime.nodes.getIcon({ 
298
    module: "node-red", 
299
    icon: "inject.svg" 
300
});
301
if (iconBuffer) {
302
    console.log(`Icon size: ${iconBuffer.length} bytes`);
303
}
304
```
305

306
### Settings Management
307

308
Access and modify runtime settings programmatically.
309

310
```javascript { .api }
311
/**
312
 * Settings management API
313
 */
314
interface SettingsAPI {
315
    getRuntimeSettings(opts: RequestOptions): Promise<RuntimeSettings>;
316
    getUserSettings(opts: RequestOptions): Promise<UserSettings>;
317
    updateUserSettings(opts: RequestOptions & { settings: Partial<UserSettings> }): Promise<void>;
318
}
319

320
/**
321
 * Get runtime settings (read-only)
322
 * @param opts - Request options
323
 * @returns Promise resolving to runtime settings
324
 */
325
RED.runtime.settings.getRuntimeSettings(opts: RequestOptions): Promise<RuntimeSettings>;
326

327
/**
328
 * Get user settings
329
 * @param opts - Request options  
330
 * @returns Promise resolving to user settings
331
 */
332
RED.runtime.settings.getUserSettings(opts: RequestOptions): Promise<UserSettings>;
333
```
334

335
**Usage Examples:**
336

337
```javascript
338
// Get runtime information
339
const runtimeSettings = await RED.runtime.settings.getRuntimeSettings({});
340
console.log(`Node-RED version: ${runtimeSettings.version}`);
341
console.log(`Node.js version: ${runtimeSettings.nodeVersion}`);
342

343
// Get user preferences
344
const userSettings = await RED.runtime.settings.getUserSettings({});
345
console.log(`Theme: ${userSettings.theme}`);
346
```
347

348
### Library Management
349

350
Manage flow and node libraries for sharing and reuse.
351

352
```javascript { .api }
353
/**
354
 * Library management API
355
 */
356
interface LibraryAPI {
357
    getEntries(opts: RequestOptions & { library: string; type: string; path?: string }): Promise<LibraryEntry[]>;
358
    getEntry(opts: RequestOptions & { library: string; type: string; path: string }): Promise<LibraryEntry>;
359
    saveEntry(opts: RequestOptions & { library: string; type: string; path: string; meta: object; body: string }): Promise<void>;
360
}
361

362
/**
363
 * Get library entries
364
 * @param opts - Request options with library details
365
 * @returns Promise resolving to array of library entries
366
 */
367
RED.runtime.library.getEntries(opts: RequestOptions & { 
368
    library: string; 
369
    type: string; 
370
    path?: string 
371
}): Promise<LibraryEntry[]>;
372
```
373

374
### Context Management
375

376
Access and modify context storage programmatically.
377

378
```javascript { .api }
379
/**
380
 * Context management API
381
 */
382
interface ContextAPI {
383
    getValue(opts: RequestOptions & { scope: string; id: string; store?: string; key: string }): Promise<any>;
384
    setValue(opts: RequestOptions & { scope: string; id: string; store?: string; key: string; value: any }): Promise<void>;
385
    getKeys(opts: RequestOptions & { scope: string; id: string; store?: string }): Promise<string[]>;
386
    delete(opts: RequestOptions & { scope: string; id: string; store?: string; key: string }): Promise<void>;
387
}
388

389
/**
390
 * Get context value
391
 * @param opts - Request options with context details
392
 * @returns Promise resolving to context value
393
 */
394
RED.runtime.context.getValue(opts: RequestOptions & { 
395
    scope: 'node' | 'flow' | 'global'; 
396
    id: string; 
397
    store?: string; 
398
    key: string 
399
}): Promise<any>;
400
```
401

402
**Usage Examples:**
403

404
```javascript
405
// Get global context value
406
const value = await RED.runtime.context.getValue({
407
    scope: "global",
408
    id: "global",
409
    key: "myValue"
410
});
411

412
// Set flow context value
413
await RED.runtime.context.setValue({
414
    scope: "flow",
415
    id: "flow-id",
416
    key: "counter",
417
    value: 42
418
});
419

420
// Get all keys in node context
421
const keys = await RED.runtime.context.getKeys({
422
    scope: "node",
423
    id: "node-id"
424
});
425
```
426

427
### Project Management
428

429
Manage Node-RED projects for version control and collaboration.
430

431
```javascript { .api }
432
/**
433
 * Project management API
434
 */
435
interface ProjectsAPI {
436
    listProjects(opts: RequestOptions): Promise<ProjectInfo[]>;
437
    getProject(opts: RequestOptions & { id: string }): Promise<ProjectInfo>;
438
    createProject(opts: RequestOptions & { project: ProjectConfig }): Promise<void>;
439
    setActiveProject(opts: RequestOptions & { id: string }): Promise<void>;
440
    updateProject(opts: RequestOptions & { id: string; update: Partial<ProjectConfig> }): Promise<void>;
441
    deleteProject(opts: RequestOptions & { id: string }): Promise<void>;
442
}
443
```
444

445
### Diagnostics
446

447
Get comprehensive diagnostic information about the runtime environment, system, and configuration.
448

449
```javascript { .api }
450
/**
451
 * Diagnostics API
452
 */
453
interface DiagnosticsAPI {
454
    get(opts: RequestOptions & { scope?: string }): Promise<DiagnosticsReport>;
455
}
456

457
/**
458
 * Get comprehensive diagnostic report
459
 * @param opts - Request options with optional scope ("basic" or "admin")
460
 * @returns Promise resolving to diagnostics information including runtime, system, and module details
461
 */
462
RED.runtime.diagnostics.get(opts: RequestOptions & { scope?: string }): Promise<DiagnosticsReport>;
463
```
464

465
**Usage Examples:**
466

467
```javascript
468
// Get basic diagnostic report
469
const basicReport = await RED.runtime.diagnostics.get({ scope: "basic" });
470
console.log(`Node-RED version: ${basicReport.runtime.version}`);
471
console.log(`Node.js version: ${basicReport.nodejs.version}`);
472
console.log(`Platform: ${basicReport.os.platform}`);
473
console.log(`Flow state: ${basicReport.runtime.flows.state}`);
474

475
// Get all installed modules
476
Object.keys(basicReport.runtime.modules).forEach(module => {
477
    console.log(`${module}: ${basicReport.runtime.modules[module]}`);
478
});
479

480
// Check containerization status
481
if (basicReport.os.containerised) {
482
    console.log(`Running in container: ${basicReport.os.containerised}`);
483
}
484
```
485

486
## Types
487

488
```javascript { .api }
489
interface RequestOptions {
490
    user?: UserObject;
491
    req?: http.IncomingMessage;
492
}
493

494
interface FlowConfig {
495
    id: string;
496
    type: string;
497
    name?: string;
498
    disabled?: boolean;
499
    info?: string;
500
    [key: string]: any;
501
}
502

503
interface DeploymentResult {
504
    revision: string;
505
}
506

507
interface NodeInfo {
508
    id: string;
509
    name: string;
510
    types: string[];
511
    enabled: boolean;
512
    local: boolean;
513
    module?: string;
514
    version?: string;
515
}
516

517
interface RuntimeSettings {
518
    version: string;
519
    nodeVersion: string;
520
    user?: UserObject;
521
    context?: {
522
        default: string;
523
        stores: string[];
524
    };
525
}
526

527
interface LibraryEntry {
528
    name: string;
529
    type: 'flows' | 'nodes';
530
    [key: string]: any;
531
}
532

533
interface ProjectInfo {
534
    name: string;
535
    active: boolean;
536
    current?: boolean;
537
    [key: string]: any;
538
}
539

540
interface DiagnosticsReport {
541
    report: "diagnostics";
542
    scope: string;
543
    time: {
544
        utc: string;
545
        local: string;
546
    };
547
    intl: {
548
        locale: string;
549
        timeZone: string;
550
    };
551
    nodejs: {
552
        version: string;
553
        arch: string;
554
        platform: string;
555
        memoryUsage: {
556
            rss: number;
557
            heapTotal: number;
558
            heapUsed: number;
559
            external: number;
560
            arrayBuffers: number;
561
        };
562
    };
563
    os: {
564
        containerised: boolean | string;
565
        wsl: boolean;
566
        totalmem: number;
567
        freemem: number;
568
        arch: string;
569
        loadavg: number[];
570
        platform: string;
571
        release: string;
572
        type: string;
573
        uptime: number;
574
        version: string;
575
    };
576
    runtime: {
577
        version: string;
578
        isStarted: boolean;
579
        flows: {
580
            state: string;
581
            started: boolean;
582
        };
583
        modules: { [moduleName: string]: string };
584
        settings: {
585
            available: boolean;
586
            apiMaxLength: string | number;
587
            disableEditor: boolean;
588
            contextStorage: { [storeName: string]: { module: string } };
589
            debugMaxLength: string | number;
590
            editorTheme: string | object;
591
            flowFile: string;
592
            mqttReconnectTime: string | number;
593
            serialReconnectTime: string | number;
594
            socketReconnectTime: string | number;
595
            socketTimeout: string | number;
596
            tcpMsgQueueSize: string | number;
597
            inboundWebSocketTimeout: string | number;
598
            runtimeState: string | object;
599
            adminAuth: "SET" | "UNSET";
600
            httpAdminRoot: string;
601
            httpAdminCors: "SET" | "UNSET";
602
            httpNodeAuth: "SET" | "UNSET";
603
            httpNodeRoot: string;
604
            httpNodeCors: "SET" | "UNSET";
605
            httpStatic: "SET" | "UNSET";
606
            httpStaticRoot: string;
607
            httpStaticCors: "SET" | "UNSET";
608
            uiHost: "SET" | "UNSET";
609
            uiPort: "SET" | "UNSET";
610
            userDir: "SET" | "UNSET";
611
            nodesDir: "SET" | "UNSET";
612
        };
613
    };
614
}
615

616
interface FlowState {
617
    state: string;
618
}
619

620
interface ModuleInfo {
621
    name: string;
622
    version?: string;
623
    user?: boolean;
624
    nodes: NodeInfo[];
625
    [key: string]: any;
626
}
627

628
interface TarballInfo {
629
    name: string;
630
    size: number;
631
    buffer: Buffer;
632
}
633

634
interface IconList {
635
    [moduleName: string]: string[];
636
}
637
```