# Interface Api

interface Api {
__private : { becca: default };
axios : AxiosStatic ;
cheerio : {
default: CheerioAPI ;
version: string;
contains(container: Element , contained: Element ): boolean;
html(options?: CheerioParserOptions ): string;
html(
dom: string | Element | Cheerio ,
options?: CheerioParserOptions ,
): string;
load(
html: string | Buffer< ArrayBufferLike >,
options?: CheerioParserOptions ,
): Root ;
load(element: Element | Element [], options?: CheerioParserOptions ): Root ;
parseHTML(
data: string,
context?: null | Document,
keepScripts?: boolean,
): Document[];
root(): Cheerio ;
xml(dom?: string | Element | Cheerio ): string;
};
currentNote : BNote ;
dayjs : __module;
logMessages : Record <string, string[]>;
logSpacedUpdates : Record <string, SpacedUpdate >;
originEntity ?: null | AbstractBeccaEntity <any>;
sql : any;
startNote ?: null | BNote ;
xml2js : node_modules/@types/xml2js ;
backupNow (backupName: string): Promise<string>;
createDataNote (
parentNoteId: string,
title: string,
content: {},
): NoteAndBranch ;
createNewNote (params: NoteParams ): NoteAndBranch ;
createNote (
parentNoteId: string,
title: string,
content: string,
extraOptions: Omit <
NoteParams ,
"title"
| "parentNoteId"
| "content"
| "type",
> & { attributes?: AttributeRow []; json?: boolean },
): NoteAndBranch ;
createOrUpdateLauncher (
opts: {
icon: string;
id: string;
isVisible: boolean;
keyboardShortcut: string;
scriptNoteId: string;
targetNoteId: string;
title: string;
type: "script" | "note" | "customWidget";
widgetNoteId?: string;
},
): { note: BNote };
createTextNote (
parentNoteId: string,
title: string,
content: string,
): NoteAndBranch ;
ensureNoteIsAbsentFromParent (noteId: string, parentNoteId: string): void;
ensureNoteIsPresentInParent (
noteId: string,
parentNoteId: string,
prefix: string,
): { branch: null | BBranch };
escapeHtml (string: string): string;
exportSubtreeToZipFile (
noteId: string,
format: "html" | "markdown",
zipFilePath: string,
): Promise<void>;
getAppInfo (): {
appVersion: string;
buildDate: string;
buildRevision: string;
clipperProtocolVersion: string;
dataDirectory: string;
dbVersion: number;
nodeVersion: string;
syncVersion: number;
utcDateTime: string;
};
getAttachment (attachmentId: string): null | BAttachment ;
getAttribute (attachmentId: string): null | BAttribute ;
getAttribute (attributeId: string): null | BAttribute ;
getBranch (branchId: string): null | BBranch ;
getDayNote (date: string, rootNote?: BNote ): Promise<null | BNote >;
getEtapiToken (etapiTokenId: string): null | BEtapiToken ;
getEtapiTokens (): BEtapiToken [];
getInstanceName (): null | string;
getMonthNote (date: string, rootNote: BNote ): Promise<null | BNote >;
getNote (noteId: string): null | BNote ;
getNotesWithLabel (name: string, value?: string): BNote [];
getNoteWithLabel (name: string, value?: string): null | BNote ;
getOption (optionName: string): null | BOption ;
getOptions (): BOption [];
getQuarterNote (date: string, rootNote: BNote ): Promise<null | BNote >;
getRevision (revisionId: string): null | BRevision ;
getRootCalendarNote (): null | BNote ;
getTodayNote (rootNote?: BNote ): Promise<null | BNote >;
getWeekFirstDayNote (date: string, rootNote: BNote ): Promise<null | BNote >;
getWeekNote (date: string, rootNote: BNote ): Promise<null | BNote >;
getYearNote (year: string, rootNote?: BNote ): null | BNote ;
log (message: string): void;
randomString (length: number): string;
runOnFrontend (script: () => string | void, params: []): void;
runOutsideOfSync (callback: () => void): Promise<void>;
searchForNote (query: string, searchParams: SearchParams ): null | BNote ;
searchForNotes (query: string, searchParams: SearchParams ): BNote [];
setNoteToParent (
noteId: string,
prefix: string,
parentNoteId: null | string,
): void;
sortNotes (
parentNoteId: string,
sortConfig: { foldersFirst?: boolean; reverse?: boolean; sortBy?: string },
): void;
toggleNoteInParent (
present: true,
noteId: string,
parentNoteId: string,
prefix: string,
): void;
transactional (func: () => void): any;
unescapeHtml (string: string): string;
}

- Defined in src/services/backend_script_api.ts:61

##### Index

### Properties

__private
axios
cheerio
currentNote
dayjs
logMessages
logSpacedUpdates
originEntity?
sql
startNote?
xml2js

### Methods

backupNow
createDataNote
createNewNote
createNote
createOrUpdateLauncher
createTextNote
ensureNoteIsAbsentFromParent
ensureNoteIsPresentInParent
escapeHtml
exportSubtreeToZipFile
getAppInfo
getAttachment
getAttribute
getBranch
getDayNote
getEtapiToken
getEtapiTokens
getInstanceName
getMonthNote
getNote
getNotesWithLabel
getNoteWithLabel
getOption
getOptions
getQuarterNote
getRevision
getRootCalendarNote
getTodayNote
getWeekFirstDayNote
getWeekNote
getYearNote
log
randomString
runOnFrontend
runOutsideOfSync
searchForNote
searchForNotes
setNoteToParent
sortNotes
toggleNoteInParent
transactional
unescapeHtml

## Properties

### __private

__private: { becca: default }

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

#### Type declaration

- ##### becca: default

  provides access to the backend in-memory object graph, see Becca

- Defined in src/services/backend_script_api.ts:403

### axios

axios: AxiosStatic

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

#### Deprecated

use native (browser compatible) fetch() instead

- Defined in src/services/backend_script_api.ts:85

### cheerio

cheerio: {
default: CheerioAPI ;
version: string;
contains(container: Element , contained: Element ): boolean;
html(options?: CheerioParserOptions ): string;
html(
dom: string | Element | Cheerio ,
options?: CheerioParserOptions ,
): string;
load(
html: string | Buffer< ArrayBufferLike >,
options?: CheerioParserOptions ,
): Root ;
load(element: Element | Element [], options?: CheerioParserOptions ): Root ;
parseHTML(
data: string,
context?: null | Document,
keepScripts?: boolean,
): Document[];
root(): Cheerio ;
xml(dom?: string | Element | Cheerio ): string;
}

cheerio library for HTML parsing and manipulation. See https://cheerio.js.org for documentation

- Defined in src/services/backend_script_api.ts:102

### currentNote

currentNote: BNote

Note where the script is currently executing. This comes into play when your script is spread in multiple code notes, the script starts in "startNote", but then through function calls may jump into another note (currentNote). A similar concept in C would be FILE Don't mix this up with the concept of active note.

- Defined in src/services/backend_script_api.ts:74

### dayjs

dayjs: __module

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

- Defined in src/services/backend_script_api.ts:90

### logMessages

logMessages: Record <string, string[]>

- Defined in src/services/backend_script_api.ts:207

### logSpacedUpdates

logSpacedUpdates: Record <string, SpacedUpdate >

- Defined in src/services/backend_script_api.ts:208

### `Optional` originEntity

originEntity?: null | AbstractBeccaEntity <any>

Entity whose event triggered this execution

- Defined in src/services/backend_script_api.ts:79

### sql

sql: any

sql

- Defined in src/services/backend_script_api.ts:333

### `Optional` startNote

startNote?: null | BNote

Note where the script started executing (entrypoint). As an analogy, in C this would be the file which contains the main() function of the current process.

- Defined in src/services/backend_script_api.ts:66

### xml2js

xml2js: node_modules/@types/xml2js

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

- Defined in src/services/backend_script_api.ts:96

## Methods

### backupNow

- backupNow(backupName: string): Promise<string>

  #### Parameters

  - backupName: string

    If the backupName is e.g. "now", then the backup will be written to "backup-now.db" file

  #### Returns Promise<string>

  resolves once the backup is finished

  - Defined in src/services/backend_script_api.ts:398

### createDataNote

- createDataNote(parentNoteId: string, title: string, content: {}): NoteAndBranch

  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

  - parentNoteId: string
  - title: string
  - content: {}

  #### Returns NoteAndBranch

  - Defined in src/services/backend_script_api.ts:184

### createNewNote

- createNewNote(params: NoteParams ): NoteAndBranch

  #### Parameters

  - params: NoteParams

  #### Returns NoteAndBranch

  object contains newly created entities note and branch

  - Defined in src/services/backend_script_api.ts:189

### createNote

- createNote(
  parentNoteId: string,
  title: string,
  content: string,
  extraOptions: Omit <
  NoteParams ,
  "title"
  | "parentNoteId"
  | "content"
  | "type",
  > & { attributes?: AttributeRow []; json?: boolean },
  ): NoteAndBranch

  #### Parameters

  - parentNoteId: string

    create new note under this parent

  - title: string
  - content: string
  - extraOptions: Omit < NoteParams , "title" | "parentNoteId" | "content" | "type"> & {
    attributes?: AttributeRow [];
    json?: boolean;
    }

    - ##### `Optional` attributes?: AttributeRow []

    - ##### `Optional` json?: boolean

      should the note be JSON

  #### Returns NoteAndBranch

  object contains newly created entities note and branch

  #### Deprecated

  please use createTextNote() with similar API for simpler use cases or createNewNote() for more complex needs

  - Defined in src/services/backend_script_api.ts:196

### createOrUpdateLauncher

- createOrUpdateLauncher(
  opts: {
  icon: string;
  id: string;
  isVisible: boolean;
  keyboardShortcut: string;
  scriptNoteId: string;
  targetNoteId: string;
  title: string;
  type: "script" | "note" | "customWidget";
  widgetNoteId?: string;
  },
  ): { note: BNote }

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

  #### Parameters

  - opts: {
    icon: string;
    id: string;
    isVisible: boolean;
    keyboardShortcut: string;
    scriptNoteId: string;
    targetNoteId: string;
    title: string;
    type: "script" | "note" | "customWidget";
    widgetNoteId?: string;
    }

    - ##### icon: string

      name of the boxicon to be used (e.g. "bx-time")

    - ##### id: string

      id of the launcher, only alphanumeric at least 6 characters long

    - ##### isVisible: boolean

      if true, will be created in the "Visible launchers", otherwise in "Available launchers"

    - ##### keyboardShortcut: string

      will activate the target note/script upon pressing, e.g. "ctrl+e"

    - ##### scriptNoteId: string

      for type "script"

    - ##### targetNoteId: string

      for type "note"

    - ##### title: string

    - ##### type: "script" | "note" | "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)

    - ##### `Optional` widgetNoteId?: string

      for type "customWidget"

  #### Returns { note: BNote }

  - Defined in src/services/backend_script_api.ts:340

### createTextNote

- createTextNote(
  parentNoteId: string,
  title: string,
  content: string,
  ): NoteAndBranch

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

  #### Parameters

  - parentNoteId: string
  - title: string
  - content: string

  #### Returns NoteAndBranch

  - Defined in src/services/backend_script_api.ts:178

### ensureNoteIsAbsentFromParent

- ensureNoteIsAbsentFromParent(noteId: string, parentNoteId: string): void

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

  #### Parameters

  - noteId: string
  - parentNoteId: string

  #### Returns void

  - Defined in src/services/backend_script_api.ts:165

### ensureNoteIsPresentInParent

- ensureNoteIsPresentInParent(
  noteId: string,
  parentNoteId: string,
  prefix: string,
  ): { branch: null | BBranch }

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

  #### Parameters

  - noteId: string
  - parentNoteId: string
  - prefix: string

    if branch is created between note and parent note, set this prefix

  #### Returns { branch: null | BBranch }

  - Defined in src/services/backend_script_api.ts:154

### escapeHtml

- escapeHtml(string: string): string

  #### Parameters

  - string: string

  #### Returns string

  escaped string

  - Defined in src/services/backend_script_api.ts:321

### exportSubtreeToZipFile

- exportSubtreeToZipFile(
  noteId: string,
  format: "html" | "markdown",
  zipFilePath: string,
  ): Promise<void>

  #### Parameters

  - noteId: string
  - format: "html" | "markdown"

    either 'html' or 'markdown'

  - zipFilePath: string

  #### Returns Promise<void>

  - Defined in src/services/backend_script_api.ts:367

### getAppInfo

- getAppInfo(): {
  appVersion: string;
  buildDate: string;
  buildRevision: string;
  clipperProtocolVersion: string;
  dataDirectory: string;
  dbVersion: number;
  nodeVersion: string;
  syncVersion: number;
  utcDateTime: string;
  }

  #### Returns {
  appVersion: string;
  buildDate: string;
  buildRevision: string;
  clipperProtocolVersion: string;
  dataDirectory: string;
  dbVersion: number;
  nodeVersion: string;
  syncVersion: number;
  utcDateTime: string;
  }

  - Defined in src/services/backend_script_api.ts:335

### getAttachment

- getAttachment(attachmentId: string): null | BAttachment

  #### Parameters

  - attachmentId: string

  #### Returns null | BAttachment

  - Defined in src/services/backend_script_api.ts:113

### getAttribute

- getAttribute(attachmentId: string): null | BAttribute

  #### Parameters

  - attachmentId: string

  #### Returns null | BAttribute

  - Defined in src/services/backend_script_api.ts:112
- getAttribute(attributeId: string): null | BAttribute

  #### Parameters

  - attributeId: string

  #### Returns null | BAttribute

  - Defined in src/services/backend_script_api.ts:119

### getBranch

- getBranch(branchId: string): null | BBranch

  #### Parameters

  - branchId: string

  #### Returns null | BBranch

  - Defined in src/services/backend_script_api.ts:111

### getDayNote

- getDayNote(date: string, rootNote?: BNote ): Promise<null | BNote >

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

  #### Parameters

  - date: string

    in YYYY-MM-DD format

  - `Optional` rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns Promise<null | BNote >

  #### Method

  - Defined in src/services/backend_script_api.ts:227

### getEtapiToken

- getEtapiToken(etapiTokenId: string): null | BEtapiToken

  #### Parameters

  - etapiTokenId: string

  #### Returns null | BEtapiToken

  - Defined in src/services/backend_script_api.ts:115

### getEtapiTokens

- getEtapiTokens(): BEtapiToken []

  #### Returns BEtapiToken []

  - Defined in src/services/backend_script_api.ts:116

### getInstanceName

- getInstanceName(): null | string

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

  #### Returns null | string

  - Defined in src/services/backend_script_api.ts:108

### getMonthNote

- getMonthNote(date: string, rootNote: BNote ): Promise<null | BNote >

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

  #### Parameters

  - date: string

    in YYYY-MM format

  - rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns Promise<null | BNote >

  - Defined in src/services/backend_script_api.ts:258

### getNote

- getNote(noteId: string): null | BNote

  #### Parameters

  - noteId: string

  #### Returns null | BNote

  - Defined in src/services/backend_script_api.ts:110

### getNotesWithLabel

- getNotesWithLabel(name: string, value?: string): BNote []

  Retrieves notes with given label name & value

  #### Parameters

  - name: string

    attribute name

  - `Optional` value: string

    attribute value

  #### Returns BNote []

  - Defined in src/services/backend_script_api.ts:139

### getNoteWithLabel

- getNoteWithLabel(name: string, value?: string): null | BNote

  Retrieves first note with given label name & value

  #### Parameters

  - name: string

    attribute name

  - `Optional` value: string

    attribute value

  #### Returns null | BNote

  - Defined in src/services/backend_script_api.ts:147

### getOption

- getOption(optionName: string): null | BOption

  #### Parameters

  - optionName: string

  #### Returns null | BOption

  - Defined in src/services/backend_script_api.ts:117

### getOptions

- getOptions(): BOption []

  #### Returns BOption []

  - Defined in src/services/backend_script_api.ts:118

### getQuarterNote

- getQuarterNote(date: string, rootNote: BNote ): Promise<null | BNote >

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

  #### Parameters

  - date: string

    in YYYY-MM format

  - rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns Promise<null | BNote >

  - Defined in src/services/backend_script_api.ts:266

### getRevision

- getRevision(revisionId: string): null | BRevision

  #### Parameters

  - revisionId: string

  #### Returns null | BRevision

  - Defined in src/services/backend_script_api.ts:114

### getRootCalendarNote

- getRootCalendarNote(): null | BNote

  Returns root note of the calendar.

  #### Returns null | BNote

  - Defined in src/services/backend_script_api.ts:218

### getTodayNote

- getTodayNote(rootNote?: BNote ): Promise<null | BNote >

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

  #### Parameters

  - `Optional` rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns Promise<null | BNote >

  - Defined in src/services/backend_script_api.ts:234

### getWeekFirstDayNote

- getWeekFirstDayNote(date: string, rootNote: BNote ): Promise<null | BNote >

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

  #### Parameters

  - date: string

    in YYYY-MM-DD format

  - rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns Promise<null | BNote >

  - Defined in src/services/backend_script_api.ts:242

### getWeekNote

- getWeekNote(date: string, rootNote: BNote ): Promise<null | BNote >

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

  #### Parameters

  - date: string

    in YYYY-MM-DD format

  - rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns Promise<null | BNote >

  - Defined in src/services/backend_script_api.ts:250

### getYearNote

- getYearNote(year: string, rootNote?: BNote ): null | BNote

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

  #### Parameters

  - year: string

    in YYYY format

  - `Optional` rootNote: BNote

    specify calendar root note, normally leave empty to use the default calendar

  #### Returns null | BNote

  - Defined in src/services/backend_script_api.ts:274

### log

- log(message: string): void

  Log given message to trilium logs and log pane in UI

  #### Parameters

  - message: string

  #### Returns void

  - Defined in src/services/backend_script_api.ts:213

### randomString

- randomString(length: number): string

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

  #### Parameters

  - length: number

    of the string

  #### Returns string

  random string

  - Defined in src/services/backend_script_api.ts:315

### runOnFrontend

- runOnFrontend(script: () => string | void, params: []): void

  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

  - script: () => string | void

    script to be executed on the frontend

  - params: []

    list of parameters to the anonymous function to be sent to frontend

  #### Returns void

  no return value is provided.

  - Defined in src/services/backend_script_api.ts:379

### runOutsideOfSync

- runOutsideOfSync(callback: () => void): Promise<void>

  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

  - callback: () => void

    function to be executed while sync process is not running

  #### Returns Promise<void>

  resolves once the callback is finished (callback is awaited)

  - Defined in src/services/backend_script_api.ts:392

### searchForNote

- searchForNote(query: string, searchParams: SearchParams ): null | BNote

  This is a powerful search method - you can search by attributes and their values, e.g.: "#dateModified =* MONTH AND #log". See https://triliumnext.github.io/Docs/Wiki/search.html for full documentation for all options

  #### Parameters

  - query: string
  - searchParams: SearchParams

  #### Returns null | BNote

  - Defined in src/services/backend_script_api.ts:131

### searchForNotes

- searchForNotes(query: string, searchParams: SearchParams ): BNote []

  This is a powerful search method - you can search by attributes and their values, e.g.: "#dateModified =* MONTH AND #log". See https://triliumnext.github.io/Docs/Wiki/search.html for full documentation for all options

  #### Parameters

  - query: string
  - searchParams: SearchParams

  #### Returns BNote []

  - Defined in src/services/backend_script_api.ts:125

### setNoteToParent

- setNoteToParent(
  noteId: string,
  prefix: string,
  parentNoteId: null | string,
  ): 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

  - noteId: string
  - prefix: string
  - parentNoteId: null | string

  #### Returns void

  #### Deprecated

  this method is pretty confusing and serves specialized purpose only

  - Defined in src/services/backend_script_api.ts:298

### sortNotes

- sortNotes(
  parentNoteId: string,
  sortConfig: { foldersFirst?: boolean; reverse?: boolean; sortBy?: string },
  ): void

  Sort child notes of a given note.

  #### Parameters

  - parentNoteId: string
  - sortConfig: { foldersFirst?: boolean; reverse?: boolean; sortBy?: string }

    - ##### `Optional` foldersFirst?: boolean

    - ##### `Optional` reverse?: boolean

    - ##### `Optional` sortBy?: string

      'title', 'dateCreated', 'dateModified' or a label name See https://triliumnext.github.io/Docs/Wiki/sorting.html for details.

  #### Returns void

  - Defined in src/services/backend_script_api.ts:279

### toggleNoteInParent

- toggleNoteInParent(
  present: true,
  noteId: string,
  parentNoteId: string,
  prefix: string,
  ): void

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

  #### Parameters

  - present: true

    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

  #### Returns void

  - Defined in src/services/backend_script_api.ts:173

### transactional

- transactional(func: () => void): any

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

  #### Parameters

  - func: () => void

  #### Returns any

  result of func callback

  - Defined in src/services/backend_script_api.ts:307

### unescapeHtml

- unescapeHtml(string: string): string

  #### Parameters

  - string: string

    to unescape

  #### Returns string

  unescaped string

  - Defined in src/services/backend_script_api.ts:327