# 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 29

### 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 537

#### axios

##### Properties:

Name | Type | Description
--- | --- | ---
`Axios` | axios | library for HTTP requests. See https://axios-http.com for documentation

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

#### currentNote

##### Properties:

Name | Type | Description
--- | --- | ---
`note` | BNote | where the script is currently executing. Don't mix this up with the concept of active note

Source:
  - services/backend_script_api.js, line 33

#### dayjs

##### Properties:

Name | Type | Description
--- | --- | ---
`day.js` | dayjs | library for date manipulation. See https://day.js.org for documentation

Source:
  - services/backend_script_api.js, line 47

#### originEntity

##### Properties:

Name | Type | Description
--- | --- | ---
`entity` | AbstractBeccaEntity | whose event triggered this execution

Source:
  - services/backend_script_api.js, line 35

#### sql

##### Properties:

Name | Type | Description
--- | --- | ---
`sql` | module:sql |

Source:
  - services/backend_script_api.js, line 437

#### startNote

##### Properties:

Name | Type | Description
--- | --- | ---
`note` | BNote | where the script started executing

Source:
  - services/backend_script_api.js, line 31

#### xml2js

##### Properties:

Name | Type | Description
--- | --- | ---
`xml2js` | axios | library for XML parsing. See https://github.com/Leonidas-from-XIV/node-xml2js for documentation

Source:
  - services/backend_script_api.js, line 49

### Methods

#### 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 198

##### Returns:

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

Type
  Object

#### createNewNote() → {Object}

##### Properties:

Name | Type | Description
--- | --- | ---
`params` | object | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`parentNoteId` | string |  |  |
`title` | string |  |  |
`content` | string | buffer |  |  |
`type` | string |  |  | 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 221

##### 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
--- | --- | --- | --- | ---
`extraOptions.json` | boolean | <optional> | false | should the note be JSON
`extraOptions.isProtected` | boolean | <optional> | false | should the note be protected
`extraOptions.type` | string | <optional> | 'text' | note type
`extraOptions.mime` | string | <optional> | 'text/html' | MIME type of the note
`extraOptions.attributes` | Array.<object> | <optional> | [] | attributes to be created for this note ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`type` | string |  | 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 241

##### 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
--- | --- | --- | --- | ---
`opts.id` | string |  |  | id of the launcher, only alphanumeric at least 6 characters long
`opts.type` | string |  |  | 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)
`opts.title` | string |  |  |
`opts.isVisible` | boolean | <optional> | false | if true, will be created in the "Visible launchers", otherwise in "Available launchers"
`opts.icon` | string | <optional> |  | name of the boxicon to be used (e.g. "bx-time")
`opts.keyboardShortcut` | string | <optional> |  | will activate the target note/script upon pressing, e.g. "ctrl+e"
`opts.targetNoteId` | string | <optional> |  | for type "note"
`opts.scriptNoteId` | string | <optional> |  | for type "script"
`opts.widgetNoteId` | string | <optional> |  | for type "customWidget"

Source:
  - services/backend_script_api.js, line 464

##### 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 181

##### 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 158

##### 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 148

##### Returns:

Type
  Object

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

##### Parameters:

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

Source:
  - services/backend_script_api.js, line 425

##### 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 530

##### Returns:

Type
  Promise.<void>

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

Source:
  - services/backend_script_api.js, line 443

##### Returns:

- object representing basic info about running Trilium version

Type
  Object | *

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

##### Parameters:

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

Source:
  - services/backend_script_api.js, line 78

##### Returns:

Type
  BAttribute | null

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

##### Parameters:

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

Source:
  - services/backend_script_api.js, line 71

##### 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 324

##### Returns:

Type
  BNote | null

#### 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 57

##### Returns:

Type
  string | null

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

Returns month note for given date. If such 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 355

##### Returns:

Type
  BNote | null

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

##### Parameters:

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

Source:
  - services/backend_script_api.js, line 64

##### 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 137

##### 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 127

##### Returns:

Type
  Array.<BNote>

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

Returns root note of the calendar.

Source:
  - services/backend_script_api.js, line 314

##### 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 333

##### 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 345

##### Returns:

Type
  BNote | null

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

Returns year note for given year. If such 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 365

##### 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 287

##### 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 418

##### Returns:

random string

Type
  string

#### 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 113

##### 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 89

##### 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 399

##### 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
--- | --- | --- | --- | ---
`sortConfig.sortBy` | string | <optional> | title | 'title', 'dateCreated', 'dateModified' or a label name See https://github.com/zadam/trilium/wiki/Sorting for details.
`sortConfig.reverse` | boolean | <optional> | false |
`sortConfig.foldersFirst` | boolean | <optional> | false |

Source:
  - services/backend_script_api.js, line 379

##### 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 170

##### Returns:

Type
  void

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

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 409

##### Returns:

result of func callback

Type
  ?

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

##### Parameters:

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

Source:
  - services/backend_script_api.js, line 432

##### Returns:

unescaped string

Type
  string