# JSDoc: Class: BackendScriptApi

# Class: BackendScriptApi

## BackendScriptApi()

#### new BackendScriptApi()

This is the main backend API interface for scripts. All the properties and methods are published in the "api" object available in the JS backend notes. You can use e.g. `api.log(api.startNote.title);`

Source:
  - services/backend_script_api.js, line 44

### Members

#### __private

This object contains "at your risk" and "no BC guarantees" objects for advanced use cases.

##### Properties:

Name | Type | Description
--- | --- | ---
`becca` | Becca | provides access to the backend in-memory object graph, see https://github.com/zadam/trilium/blob/master/src/becca/becca.js

Source:
  - services/backend_script_api.js, line 679

#### axios :axios

Axios library for HTTP requests. See https://axios-http.com for documentation

##### Type:

- axios

Deprecated:
  - use native (browser compatible) fetch() instead
Source:
  - services/backend_script_api.js, line 70

#### currentNote :BNote

Note where the script is currently executing. Don't mix this up with the concept of active note

##### Type:

- BNote

Source:
  - services/backend_script_api.js, line 54

#### dayjs :dayjs

day.js library for date manipulation. See https://day.js.org for documentation

##### Type:

- dayjs

Source:
  - services/backend_script_api.js, line 75

#### originEntity :AbstractBeccaEntity

Entity whose event triggered this execution

##### Type:

- AbstractBeccaEntity

Source:
  - services/backend_script_api.js, line 59

#### sql :module:sql

sql

##### Type:

- module:sql

Source:
  - services/backend_script_api.js, line 516

#### startNote :BNote

Note where the script started executing

##### Type:

- BNote

Source:
  - services/backend_script_api.js, line 49

#### xml2js :xml2js

xml2js library for XML parsing. See https://github.com/Leonidas-from-XIV/node-xml2js for documentation

##### Type:

- xml2js

Source:
  - services/backend_script_api.js, line 80

### Methods

#### backupNow(backupName) → {Promise}

##### Parameters:

Name | Type | Description
--- | --- | ---
`backupName` | string | If the backupName is e.g. "now", then the backup will be written to "backup-now.db" file

Source:
  - services/backend_script_api.js, line 672

##### Returns:

- resolves once the backup is finished

Type
  Promise

#### createDataNote(parentNoteId, title, content) → {Object}

Create data note - data in this context means object serializable to JSON. Created note will be of type 'code' and JSON MIME type. See also createNewNote() for more options.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parentNoteId` | string |
`title` | string |
`content` | object |

Source:
  - services/backend_script_api.js, line 276

##### Returns:

object having "note" and "branch" keys representing respective objects

Type
  Object

#### createNewNote(params) → {Object}

##### Parameters:

Name | Type | Description
--- | --- | ---

`params`

object

###### Properties

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`parentNoteId` | string |  |  |
`title` | string |  |  |
`content` | string | Buffer |  |  |
`type` | NoteType |  |  | text, code, file, image, search, book, relationMap, canvas
`mime` | string | <optional> |  | value is derived from default mimes for type
`isProtected` | boolean | <optional> | false |
`isExpanded` | boolean | <optional> | false |
`prefix` | string | <optional> | '' |
`notePosition` | int | <optional> |  | default is last existing notePosition in a parent + 10

Source:
  - services/backend_script_api.js, line 299

##### Returns:

object contains newly created entities note and branch

Type
  Object

#### createNote(parentNoteId, title, contentopt, extraOptionsopt) → {Object}

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`parentNoteId` | string |  |  | create new note under this parent
`title` | string |  |  |
`content` | string | <optional> | "" |

`extraOptions`

object

<optional>

{}

###### Properties

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`json` | boolean | <optional> | false | should the note be JSON
`isProtected` | boolean | <optional> | false | should the note be protected
`type` | string | <optional> | 'text' | note type
`mime` | string | <optional> | 'text/html' | MIME type of the note

`attributes`

Array.<object>

<optional>

[]

attributes to be created for this note

###### Properties

Name | Type | Attributes | Description
--- | --- | --- | ---
`type` | AttributeType |  | attribute type - label, relation etc.
`name` | string |  | attribute name
`value` | string | <optional> | attribute value

Deprecated:
  - please use createTextNote() with similar API for simpler use cases or createNewNote() for more complex needs
Source:
  - services/backend_script_api.js, line 319

##### Returns:

object contains newly created entities note and branch

Type
  Object

#### createOrUpdateLauncher(opts) → {Object}

Creates a new launcher to the launchbar. If the launcher (id) already exists, it will be updated.

##### Parameters:

Name | Type | Description
--- | --- | ---

`opts`

object

###### Properties

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`id` | string |  |  | id of the launcher, only alphanumeric at least 6 characters long
`type` | "note" | "script" | "customWidget" |  |  | one of * "note" - activating the launcher will navigate to the target note (specified in targetNoteId param) * "script" - activating the launcher will execute the script (specified in scriptNoteId param) * "customWidget" - the launcher will be rendered with a custom widget (specified in widgetNoteId param)
`title` | string |  |  |
`isVisible` | boolean | <optional> | false | if true, will be created in the "Visible launchers", otherwise in "Available launchers"
`icon` | string | <optional> |  | name of the boxicon to be used (e.g. "bx-time")
`keyboardShortcut` | string | <optional> |  | will activate the target note/script upon pressing, e.g. "ctrl+e"
`targetNoteId` | string | <optional> |  | for type "note"
`scriptNoteId` | string | <optional> |  | for type "script"
`widgetNoteId` | string | <optional> |  | for type "customWidget"

Source:
  - services/backend_script_api.js, line 543

##### Returns:

Type
  Object

#### createTextNote(parentNoteId, title, content) → {Object}

Create text note. See also createNewNote() for more options.

##### Parameters:

Name | Type | Description
--- | --- | ---
`parentNoteId` | string |
`title` | string |
`content` | string |

Source:
  - services/backend_script_api.js, line 259

##### Returns:

- object having "note" and "branch" keys representing respective objects

Type
  Object

#### ensureNoteIsAbsentFromParent(noteId, parentNoteId) → {void}

If there's a branch between note and parent note, remove it. Otherwise, do nothing.

##### Parameters:

Name | Type | Description
--- | --- | ---
`noteId` | string |
`parentNoteId` | string |

Source:
  - services/backend_script_api.js, line 236

##### Returns:

Type
  void

#### ensureNoteIsPresentInParent(noteId, parentNoteId, prefix) → {Object}

If there's no branch between note and parent note, create one. Otherwise, do nothing. Returns the new or existing branch.

##### Parameters:

Name | Type | Description
--- | --- | ---
`noteId` | string |
`parentNoteId` | string |
`prefix` | string | if branch is created between note and parent note, set this prefix

Source:
  - services/backend_script_api.js, line 226

##### Returns:

Type
  Object

#### escapeHtml(string) → {string}

##### Parameters:

Name | Type | Description
--- | --- | ---
`string` | string | to escape

Source:
  - services/backend_script_api.js, line 503

##### Returns:

escaped string

Type
  string

#### exportSubtreeToZipFile(noteId, format, zipFilePath) → {Promise.<void>}

##### Parameters:

Name | Type | Description
--- | --- | ---
`noteId` | string |
`format` | string | either 'html' or 'markdown'
`zipFilePath` | string |

Source:
  - services/backend_script_api.js, line 609

##### Returns:

Type
  Promise.<void>

#### getAppInfo() → {Object|*}

Source:
  - services/backend_script_api.js, line 522

##### Returns:

- object representing basic info about running Trilium version

Type
  Object | *

#### getAttachment(attachmentId) → {BAttachment|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`attachmentId` | string |

Source:
  - services/backend_script_api.js, line 116

##### Returns:

Type
  BAttachment | null

#### getAttribute(attributeId) → {BAttribute|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`attributeId` | string |

Source:
  - services/backend_script_api.js, line 109

##### Returns:

Type
  BAttribute | null

#### getAttribute(attributeId) → {BAttribute|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`attributeId` | string |

Source:
  - services/backend_script_api.js, line 156

##### Returns:

Type
  BAttribute | null

#### getBranch(branchId) → {BBranch|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`branchId` | string |

Source:
  - services/backend_script_api.js, line 102

##### Returns:

Type
  BBranch | null

#### getDayNote(date, rootNoteopt) → {BNote|null}

Returns day note for given date. If such note doesn't exist, it is created.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`date` | string |  | in YYYY-MM-DD format
`rootNote` | BNote | <optional> | specify calendar root note, normally leave empty to use the default calendar

Source:
  - services/backend_script_api.js, line 402

##### Returns:

Type
  BNote | null

#### getEtapiToken(etapiTokenId) → {BEtapiToken|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`etapiTokenId` | string |

Source:
  - services/backend_script_api.js, line 130

##### Returns:

Type
  BEtapiToken | null

#### getEtapiTokens() → {Array.<BEtapiToken>}

Source:
  - services/backend_script_api.js, line 136

##### Returns:

Type
  Array.<BEtapiToken>

#### getInstanceName() → {string|null}

Instance name identifies particular Trilium instance. It can be useful for scripts if some action needs to happen on only one specific instance.

Source:
  - services/backend_script_api.js, line 88

##### Returns:

Type
  string | null

#### getMonthNote(date, rootNoteopt) → {BNote|null}

Returns month note for given date. If such a note doesn't exist, it is created.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`date` | string |  | in YYYY-MM format
`rootNote` | BNote | <optional> | specify calendar root note, normally leave empty to use the default calendar

Source:
  - services/backend_script_api.js, line 433

##### Returns:

Type
  BNote | null

#### getNote(noteId) → {BNote|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`noteId` | string |

Source:
  - services/backend_script_api.js, line 95

##### Returns:

Type
  BNote | null

#### getNoteWithLabel(name, valueopt) → {BNote|null}

Retrieves first note with given label name & value

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string |  | attribute name
`value` | string | <optional> | attribute value

Source:
  - services/backend_script_api.js, line 215

##### Returns:

Type
  BNote | null

#### getNotesWithLabel(name, valueopt) → {Array.<BNote>}

Retrieves notes with given label name & value

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string |  | attribute name
`value` | string | <optional> | attribute value

Source:
  - services/backend_script_api.js, line 205

##### Returns:

Type
  Array.<BNote>

#### getOption(optionName) → {BOption|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`optionName` | string |

Source:
  - services/backend_script_api.js, line 143

##### Returns:

Type
  BOption | null

#### getOptions() → {Array.<BOption>}

Source:
  - services/backend_script_api.js, line 149

##### Returns:

Type
  Array.<BOption>

#### getRevision(revisionId) → {BRevision|null}

##### Parameters:

Name | Type | Description
--- | --- | ---
`revisionId` | string |

Source:
  - services/backend_script_api.js, line 123

##### Returns:

Type
  BRevision | null

#### getRootCalendarNote() → {BNote|null}

Returns root note of the calendar.

Source:
  - services/backend_script_api.js, line 392

##### Returns:

Type
  BNote | null

#### getTodayNote(rootNoteopt) → {BNote|null}

Returns today's day note. If such note doesn't exist, it is created.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`rootNote` | BNote | <optional> | specify calendar root note, normally leave empty to use the default calendar

Source:
  - services/backend_script_api.js, line 411

##### Returns:

Type
  BNote | null

#### getWeekNote(date, optionsopt, rootNoteopt) → {BNote|null}

Returns note for the first date of the week of the given date.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`date` | string |  | in YYYY-MM-DD format

`options`

object

<optional>

###### Properties

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`startOfTheWeek` | string | <optional> | monday | either "monday" (default) or "sunday"

`rootNote` | BNote | <optional> | specify calendar root note, normally leave empty to use the default calendar

Source:
  - services/backend_script_api.js, line 423

##### Returns:

Type
  BNote | null

#### getYearNote(year, rootNoteopt) → {BNote|null}

Returns year note for given year. If such a note doesn't exist, it is created.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`year` | string |  | in YYYY format
`rootNote` | BNote | <optional> | specify calendar root note, normally leave empty to use the default calendar

Source:
  - services/backend_script_api.js, line 443

##### Returns:

Type
  BNote | null

#### log(message) → {void}

Log given message to trilium logs and log pane in UI

##### Parameters:

Name | Type | Description
--- | --- | ---
`message` |  |

Source:
  - services/backend_script_api.js, line 365

##### Returns:

Type
  void

#### randomString(length) → {string}

Return randomly generated string of given length. This random string generation is NOT cryptographically secure.

##### Parameters:

Name | Type | Description
--- | --- | ---
`length` | int | of the string

Source:
  - services/backend_script_api.js, line 496

##### Returns:

random string

Type
  string

#### runOnFrontend(script, params) → {undefined}

Executes given anonymous function on the frontend(s). Internally, this serializes the anonymous function into string and sends it to frontend(s) via WebSocket. Note that there can be multiple connected frontend instances (e.g. in different tabs). In such case, all instances execute the given function.

##### Parameters:

Name | Type | Description
--- | --- | ---
`script` | string | script to be executed on the frontend
`params` | Array.<?> | list of parameters to the anonymous function to be sent to frontend

Source:
  - services/backend_script_api.js, line 622

##### Returns:

- no return value is provided.

Type
  undefined

#### runOutsideOfSync(callback) → {Promise}

Sync process can make data intermittently inconsistent. Scripts which require strong data consistency can use this function to wait for a possible sync process to finish and prevent new sync process from starting while it is running. Because this is an async process, the inner callback doesn't have automatic transaction handling, so in case you need to make some DB changes, you need to surround your call with api.transactional(...)

##### Parameters:

Name | Type | Description
--- | --- | ---
`callback` | function | function to be executed while sync process is not running

Source:
  - services/backend_script_api.js, line 665

##### Returns:

- resolves once the callback is finished (callback is awaited)

Type
  Promise

#### searchForNote(query, searchParamsopt) → {BNote|null}

This is a powerful search method - you can search by attributes and their values, e.g.: "#dateModified =* MONTH AND #log". See https://github.com/zadam/trilium/wiki/Search for full documentation for all options

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`query` | string |  |
`searchParams` | Object | <optional> |

Source:
  - services/backend_script_api.js, line 191

##### Returns:

Type
  BNote | null

#### searchForNotes(query, searchParamsopt) → {Array.<BNote>}

This is a powerful search method - you can search by attributes and their values, e.g.: "#dateModified =* MONTH AND #log". See https://github.com/zadam/trilium/wiki/Search for full documentation for all options

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`query` | string |  |
`searchParams` | Object | <optional> |

Source:
  - services/backend_script_api.js, line 167

##### Returns:

Type
  Array.<BNote>

#### setNoteToParent(noteId, prefix, parentNoteId) → {void}

This method finds note by its noteId and prefix and either sets it to the given parentNoteId or removes the branch (if parentNoteId is not given). This method looks similar to toggleNoteInParent() but differs because we're looking up branch by prefix.

##### Parameters:

Name | Type | Description
--- | --- | ---
`noteId` | string |
`prefix` | string |
`parentNoteId` | string | null |

Deprecated:
  - this method is pretty confusing and serves specialized purpose only
Source:
  - services/backend_script_api.js, line 477

##### Returns:

Type
  void

#### sortNotes(parentNoteId, sortConfigopt) → {void}

Sort child notes of a given note.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`parentNoteId` | string |  | this note's child notes will be sorted

`sortConfig`

object

<optional>

###### Properties

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`sortBy` | string | <optional> | title | 'title', 'dateCreated', 'dateModified' or a label name See https://github.com/zadam/trilium/wiki/Sorting for details.
`reverse` | boolean | <optional> | false |
`foldersFirst` | boolean | <optional> | false |

Source:
  - services/backend_script_api.js, line 457

##### Returns:

Type
  void

#### toggleNoteInParent(present, noteId, parentNoteId, prefix) → {void}

Based on the value, either create or remove branch between note and parent note.

##### Parameters:

Name | Type | Description
--- | --- | ---
`present` | boolean | true if we want the branch to exist, false if we want it gone
`noteId` | string |
`parentNoteId` | string |
`prefix` | string | if branch is created between note and parent note, set this prefix

Source:
  - services/backend_script_api.js, line 248

##### Returns:

Type
  void

#### transactional(func) → {any}

This functions wraps code which is supposed to be running in transaction. If transaction already exists, then we'll use that transaction.

##### Parameters:

Name | Type | Description
--- | --- | ---
`func` | function |

Source:
  - services/backend_script_api.js, line 487

##### Returns:

result of func callback

Type
  any

#### unescapeHtml(string) → {string}

##### Parameters:

Name | Type | Description
--- | --- | ---
`string` | string | to unescape

Source:
  - services/backend_script_api.js, line 510

##### Returns:

unescaped string

Type
  string