API reference

Create a new character. Requires at least name.

addCharacter(data: CharacterInput) → Promise<Character>

Create a new document in the project. Returns the created doc metadata.

addDoc(data: DocInput) → Promise<DocMetadata>

Create a new file in the project. Returns the created file metadata.

addFile(data: FileInput) → Promise<FileMetadata>

Save an image (a base64 string or a data: URI) into the project and return a reference to the saved image. Assign it to a character/worldbuilding portrait or landscape. Requires the project.write.images scope. Pairs with net.fetch({ responseType: 'base64' }) to import a remote image.

addImage(data: string, fileName?: string) → Promise<string>

Create a new note. Requires location.

addNote(data: NoteInput) → Promise<Note>

Create a new worldbuilding element. Requires name and type.

addWorldbuildingElement(data: WorldbuildingInput) → Promise<WorldbuildingElement>

Create an empty flow map. Requires project.write.flowmaps.

createFlowMap(name: string) → Promise<FlowMap>

Delete a flow map. Requires project.write.flowmaps.

deleteFlowMap(flowMapId: string) → Promise<boolean>

Get all cardboard grids with their cells.

getCardboards() → Promise<CardboardGrid[]>

Get a character by ID.

getCharacterById(id: string) → Promise<Character | null>

Get all characters.

getCharacters() → Promise<Character[]>

Get all collections.

getCollections() → Promise<Collection[]>

Get the project's custom worldbuilding templates. Read-only.

getCustomWorldbuildingTemplates() → Promise<CustomWorldbuildingTemplate[]>

Get the raw content of a document by its ID. Returns a ProseMirror/TipTap JSON string, or null. Same format as getFileContent().

getDocContent(docId: string) → Promise<string | null>

Get all documents (metadata only).

getDocs() → Promise<DocMetadata[]>

Get the raw content of a file by its ID. Returns the file content as a ProseMirror/TipTap JSON string (the internal document format), or null if the file does not exist or has no content. You must JSON.parse() the result to obtain a ProseMirrorDocument object, or pass the raw string directly to tintero.convert.toHtml() / toMarkdown() / toText(). Those methods accept both the raw string and a parsed object.

getFileContent(fileId: string) → Promise<string | null>

Get the version snapshots of a file by its ID. Read-only.

getFileSnapshots(fileId: string) → Promise<FileSnapshot[]>

Get all project files (metadata only, no content).

getFiles() → Promise<FileMetadata[]>

Get one flow map by its ID, or null if it does not exist. Requires project.read.flowmaps.

getFlowMapById(flowMapId: string) → Promise<FlowMap | null>

Get all flow maps (nodes and connections). Requires project.read.flowmaps.

getFlowMaps() → Promise<FlowMap[]>

Get the project's folder tree structure.

getFolders() → Promise<FolderInfo[]>

Get a project image as a base64 data URL. Accepts the image fileName or relativePath (e.g. "portrait.png" or "images/portrait.png"). Returns a string like "data:image/png;base64,..." or null if not found. Use this to display project images inside plugin iframes.

getImageData(imageRef: string) → Promise<string | null>

Get all images metadata.

getImages() → Promise<ImageInfo[]>

Get project metadata (name, dates, description).

getMetadata() → Promise<ProjectMetadata>

Get all notes.

getNotes() → Promise<Note[]>

Get all plot grids with their columns and cells.

getPlotGrids() → Promise<PlotGrid[]>

Get the scenes defined within a file by its ID. Read-only.

getScenes(fileId: string) → Promise<Scene[]>

Get all project tags.

getTags() → Promise<string[]>

Get all timelines (lanes, blocks, notes, milestones). Read-only.

getTimelines() → Promise<Timeline[]>

Get the per-day word count log. Read-only.

getWordCountLog() → Promise<WordCountLog[]>

Get all worldbuilding elements.

getWorldbuilding() → Promise<WorldbuildingElement[]>

Get worldbuilding elements by type (e.g. "location", "faction").

getWorldbuildingByType(type: string) → Promise<WorldbuildingElement[]>

Get the user's writing goals (words/chapters/minutes targets). Read-only.

getWritingGoals() → Promise<WritingGoal[]>

Get the per-day writing-minutes log. Read-only.

getWritingMinutesLog() → Promise<WritingMinutesLog[]>

Delete a worldbuilding element by ID.

removeWorldbuildingElement(id: string) → Promise<void>

Rename a flow map. Requires project.write.flowmaps.

renameFlowMap(flowMapId: string, name: string) → Promise<FlowMap>

Search the chapter PROSE (not the metadata) for a term, matching whole words and ignoring accents. Returns the chapters where it occurs, how many times, and a few excerpts around the matches. Use it to answer "where/how does X appear" when the metadata is not enough. Bounded on purpose: maxChapters (250 by default) keeps a large manuscript from being read end to end on every call. Pass several forms of the same name (full name, first name) as an array to match any of them in one pass.

searchProse(term: string | string[], options?: ProseSearchOptions) → Promise<ProseSearchHit[]>

Update an existing character's fields. Only provided fields are changed.

updateCharacter(id: string, data: Partial<CharacterInput>) → Promise<void>

Update the content of a document. Same format as updateFileContent().

updateDocContent(docId: string, jsonContent: string) → Promise<void>

Update document metadata (not content). Only provided fields are changed.

updateDocMeta(id: string, data: DocMetaUpdate) → Promise<void>

Update the content of a file. jsonContent must be a ProseMirror/TipTap JSON string, i.e. the result of JSON.stringify(proseMirrorDocumentObject). To build a document from other formats, use tintero.convert.fromHtml(), fromMarkdown(), or fromText() first, then JSON.stringify() the returned object before passing it here.

updateFileContent(fileId: string, jsonContent: string) → Promise<void>

Update file metadata (not content). Only provided fields are changed.

updateFileMeta(id: string, data: FileMetaUpdate) → Promise<void>

Replace a flow map's nodes and connections. The payload is validated in full BEFORE anything is written, so a malformed one leaves the project untouched: ids must be unique strings, every connection must point at a node in the same payload, coordinates must be finite numbers and colours must be plain CSS colours. Requires project.write.flowmaps.

updateFlowMap(flowMapId: string, update: FlowMapUpdate) → Promise<FlowMap>

Replace all project tags.

updateTags(tags: string[]) → Promise<void>

Update an existing worldbuilding element.

updateWorldbuildingElement(id: string, data: Partial<WorldbuildingInput>) → Promise<void>

The chapters a character appears in, according to the project metadata.

chaptersWithCharacter(character: string) → Promise<string>

Appearance counts per character, most frequent first. With an argument, that character's chapters.

characterAppearanceCounts(character?: string) → Promise<string>

Resolve a chapter by number ("chapter 7"), id, or a fragment of its title.

findChapter(reference: string) → Promise<string>

The author-written synopsis of a chapter. Cheap: prefer it over the full prose.

getChapterSynopsis(chapter: string) → Promise<string>

The prose of a chapter resolved by reference, clipped to 20.000 characters.

getChapterText(chapter: string) → Promise<string>

The full profile of a character (traits, backstory, goals, fears) by id or name.

getCharacterProfile(character: string) → Promise<string>

A character's relationships with other characters, with the names resolved.

getCharacterRelationships(character: string) → Promise<string>

The text of a non-chapter document (synopsis, world bible) by id, name or title fragment.

getDocument(document: string) → Promise<string>

The full profile of a worldbuilding element by id or name.

getWorldbuildingProfile(element: string) → Promise<string>

Every chapter with its number, status, length, whether it has a summary, and its characters.

listChapters() → Promise<string>

A summary of a chapter the author never summarised, generated on demand. Scopes: ai.summarize AND project.read.fileContent (the summary is derived from the prose). It calls the AI server configured in Tintero's settings, so it costs the user time and quota; returns the author's own summary when there is one, without calling any model.

summarizeChapter(chapter: string) → Promise<string>

Joins two existing nodes with an arrow. Both node ids must exist or the call fails.

addFlowMapConnection(flowMapId: string, connection: FlowMapConnectionInput) → Promise<FlowMapConnection>

Adds a node to a flow map and returns it, with the id Tintero assigned.

addFlowMapNode(flowMapId: string, node: FlowMapNodeInput) → Promise<FlowMapNode>

Puts a chapter, a scene or a worldbuilding event on a lane. A document block needs fileId; an event block needs eventId. The id of the block is assigned by Tintero.

addTimelineBlock(timelineId: string, laneId: string, block: TimelineBlockInput) → Promise<TimelineBlock>

Adds a lane (one strand of the story) and returns it.

addTimelineLane(timelineId: string, name: string) → Promise<TimelineLane>

Adds a milestone across every lane (a turning point, a climax).

addTimelineMilestone(timelineId: string, milestone: { text: string; position: number; color?: string }) → Promise<TimelineMilestone>

Names a stretch of the axis: an act, a part, a season.

addTimelineSegment(timelineId: string, segment: { name: string; startCol: number; spanCols: number; color?: string }) → Promise<TimelineSegment>

Puts a chapter (file) or a document (doc) into a collection.

addToCollection(collectionId: string, itemId: string, itemType: 'file' | 'doc') → Promise<void>

Creates a note collection and returns it.

createCollection(name: string) → Promise<Collection>

Creates a flow map and returns it.

createFlowMap(name: string) → Promise<FlowMap>

Creates a scene inside a chapter. Unlike the editor's own dialog, it needs the chapter id.

createScene(fileId: string, scene: SceneInput) → Promise<Scene>

Creates a timeline and returns it. parentId hangs it off a block of another timeline.

createTimeline(name: string, parentId?: string) → Promise<Timeline>

Deletes a collection. The chapters and documents in it are not deleted.

deleteCollection(collectionId: string) → Promise<void>

Deletes a flow map with its nodes and arrows.

deleteFlowMap(flowMapId: string) → Promise<void>

Deletes a note and its body.

deleteNote(noteId: string) → Promise<void>

Deletes a scene from the chapter that owns it.

deleteScene(sceneId: string) → Promise<void>

Deletes a timeline and everything on it.

deleteTimeline(timelineId: string) → Promise<void>

Removes an arrow.

removeFlowMapConnection(flowMapId: string, connectionId: string) → Promise<void>

Removes a node. Arrows that pointed at it are left dangling, so remove them too.

removeFlowMapNode(flowMapId: string, nodeId: string) → Promise<void>

Takes an item out of a collection.

removeFromCollection(collectionId: string, itemId: string, itemType: 'file' | 'doc') → Promise<void>

Removes a block from a lane.

removeTimelineBlock(timelineId: string, laneId: string, blockId: string) → Promise<void>

Renames a collection.

renameCollection(collectionId: string, name: string) → Promise<void>

Renames a flow map.

renameFlowMap(flowMapId: string, name: string) → Promise<void>

Sets how the axis is labelled. These are labels, never real dates. Pass null to unset it.

setTimelineAxis(timelineId: string, axis: { unit?: string; start: number; step: number } | null) → Promise<void>

Rewrites a note's body and colour. The body hash is resealed, which is what sync compares.

updateNote(noteId: string, data: { content: string; type?: string }) → Promise<void>

Edits a scene. Only the fields you pass change.

updateScene(sceneId: string, updates: Partial<SceneInput>) → Promise<Scene | null>

Adds an empty column at the right.

addCardboardColumn(gridId: string) → Promise<void>

Adds a sticky note or a checkbox to a card. Image, audio and pdf notes need an asset and are not available here.

addCardboardNote(gridId: string, cellId: string, note: { kind: 'sticky' | 'checkbox'; title?: string; content?: string; color?: string; checked?: boolean }) → Promise<CardboardCell>

Pins a chapter, doc, character or worldbuilding element to a card. The target must exist.

addCardboardReference(gridId: string, cellId: string, refType: 'chapter' | 'doc' | 'character' | 'worldbuilding', targetId: string) → Promise<CardboardCell>

Adds an empty row at the bottom.

addCardboardRow(gridId: string) → Promise<void>

Adds a plot column at the right and returns it.

addPlotGridColumn(gridId: string, name?: string) → Promise<PlotGridColumn>

Adds a row at the bottom.

addPlotGridRow(gridId: string) → Promise<void>

Adds a banner above a row (an act, a part). rowIndex equal to the row count puts it after the last row.

addPlotGridRowNote(gridId: string, rowIndex: number, note?: { content?: string; color?: string; height?: number }) → Promise<{ id: string; rowIndex: number; content: string; color?: string; height?: number }>

Empties a cell.

clearPlotGridCell(gridId: string, cellId: string) → Promise<void>

Creates a cardboard with empty cells and returns it. rows and cols default to 3.

createCardboard(name: string, rows?: number, cols?: number) → Promise<CardboardGrid>

Creates a plot grid with the chapters column and two empty plot columns, three rows.

createPlotGrid(name: string) → Promise<PlotGrid>

Deletes a cardboard with every card on it.

deleteCardboard(gridId: string) → Promise<void>

Deletes a column and its cards. The columns to the right move left.

deleteCardboardColumn(gridId: string, colIndex: number) → Promise<void>

Removes a note from a card.

deleteCardboardNote(gridId: string, cellId: string, noteId: string) → Promise<CardboardCell>

Deletes a row and its cards. The rows below move up. A cardboard keeps at least one row.

deleteCardboardRow(gridId: string, rowIndex: number) → Promise<void>

Deletes a plot grid with everything in it.

deletePlotGrid(gridId: string) → Promise<void>

Deletes a column and its cells. The chapters column (position 0) cannot be deleted.

deletePlotGridColumn(gridId: string, columnId: string) → Promise<void>

Deletes a row and its cells. The rows below move up, and so do the banners anchored below it.

deletePlotGridRow(gridId: string, rowIndex: number) → Promise<void>

Deletes a banner.

deletePlotGridRowNote(gridId: string, noteId: string) → Promise<void>

Swaps a plot column with its neighbour. The chapters column stays where it is.

movePlotGridColumn(gridId: string, columnId: string, direction: 'left' | 'right') → Promise<boolean>

Swaps a row with the one above or below.

movePlotGridRow(gridId: string, rowIndex: number, direction: 'up' | 'down') → Promise<boolean>

Unpins a reference from a card. A card left empty goes back to unassigned.

removeCardboardReference(gridId: string, cellId: string, referenceId: string) → Promise<CardboardCell>

Renames a cardboard.

renameCardboard(gridId: string, name: string) → Promise<void>

Renames a plot grid.

renamePlotGrid(gridId: string, name: string) → Promise<void>

Renames a column.

renamePlotGridColumn(gridId: string, columnId: string, name: string) → Promise<void>

Labels a row or a column (an act, a character arc). An empty label removes the header.

setCardboardHeader(gridId: string, axis: 'row' | 'col', index: number, label: string, color?: string) → Promise<void>

Sets the cell of a column and a row, creating it if needed. A chapter cell only fits in the chapters column (position 0) and needs the chapter id in referenceId; a note cell fits anywhere else.

setPlotGridCell(gridId: string, columnId: string, rowIndex: number, cell: { type: 'unassigned' | 'chapter' | 'note'; referenceId?: string; content?: string; color?: string }) → Promise<PlotGridCell>

Changes the title, status, tags or color of a card. Other fields are ignored.

updateCardboardCell(gridId: string, cellId: string, patch: { title?: string; status?: string; tags?: string[]; color?: string }) → Promise<CardboardCell>

Changes the text, color or height of a banner.

updatePlotGridRowNote(gridId: string, noteId: string, changes: { content?: string; color?: string; height?: number }) → Promise<void>

Delete a file from the project directory (relative path).

deleteProjectFile(location: string) → Promise<void>

Get the current platform as a compound string: "<os> | <runtime>". Examples: "darwin | Desktop", "win32 | Desktop", "linux | Desktop", "ios | Mobile", "android | Mobile", "unknown | Web".

getPlatform() → Promise<string>

Read a file from the project directory (relative path).

readProjectFile(location: string) → Promise<string | null>

Save the project metadata to disk.

saveProject() → Promise<void>

Write a file to the project directory (relative path).

writeProjectFile(location: string, content: string) → Promise<void>

Close the plugin's open dialog.

closeDialog() → Promise<void>

Hide the application sidebar.

hideSidebar() → Promise<void>

Check if the application is currently in fullscreen mode.

isFullscreen() → Promise<boolean>

Open a modal dialog for this plugin.

openDialog(options?: DialogOptions) → Promise<void>

Render HTML into the active context. If a dialog is open for this plugin, renders into the dialog. Otherwise, renders into the sidebar panel's #plugin-root.

render(html: string) → Promise<void>

Show a toast notification.

showNotification(message: string, type?: NotificationType, durationMs?: number) → Promise<void>

Show the application sidebar.

showSidebar() → Promise<void>

Toggle fullscreen mode (Desktop only).

toggleFullscreen() → Promise<void>

Toggle the application sidebar visibility.

toggleSidebar() → Promise<void>

Get a stored value by key. Returns null if not found.

get(key: string) → Promise<any | null>

Get all stored key-value pairs.

getAll() → Promise<Record<string, any>>

Remove a stored key.

remove(key: string) → Promise<void>

Store a value. Values are JSON-serializable.

set(key: string, value: any) → Promise<void>

Get all plugin settings (manifest defaults merged with stored overrides).

get() → Promise<Record<string, any>>

Get a specific setting field value.

getField(key: string) → Promise<any | null>

Get a sanitized copy of application settings (AI credentials excluded).

getSettings() → Promise<AppSettings>

Get a specific setting field by dot path (e.g. "generalSettings.languageIsoCode").

getSettingsField(path: string) → Promise<any | null>

Modify application settings. Allowed sections: generalSettings, trophySettings, hideSettings, editorSettings, editorToolbarSettings. AI settings cannot be modified.

updateSettings(changes: Partial<Pick<AppSettings, 'generalSettings' | 'trophySettings' | 'hideSettings' | 'editorSettings' | 'editorToolbarSettings'>>) → Promise<void>

Create a backup. Returns the backup ID. Keep it to find the backup later. name becomes the user-visible label (empty or blank = no label); the entry's name is an internal folder id, so list().find(b => b.name === name) no longer finds it.

create(name?: string, observations?: string) → Promise<string>

Get a specific backup by ID.

getById(id: string) → Promise<BackupEntry | null>

List all backups.

list() → Promise<BackupEntry[]>

Restore a backup. WARNING: This replaces the current project data.

restore(id: string) → Promise<void>

Subscribe to an event.

on(event: PluginEvent, callback: EventCallback) → void

Unsubscribe from an event.

off(event: PluginEvent, callback: EventCallback) → void

Trigger a file download to the user's device.

exportFile(fileName: string, content: string, mimeType?: string) → Promise<void>

Register this plugin as a book exporter (all files concatenated).

registerBookExporter(config: BookExporterConfig) → Promise<void>

Register this plugin as a file exporter. The convert function is called when the user exports.

registerExporter(config: FileExporterConfig) → Promise<void>

Register this plugin as a project exporter.

registerProjectExporter(config: ProjectExporterConfig) → Promise<void>

Register this plugin as a file importer. The convert function receives raw file data.

registerImporter(config: FileImporterConfig) → Promise<void>

Register this plugin as a project importer.

registerProjectImporter(config: ProjectImporterConfig) → Promise<void>

Get the currently active/focused document, or null if no editor is open.

getActiveDocument() → Promise<OpenDocument | null>

Get all documents currently open in editor tabs.

getOpenDocuments() → Promise<OpenDocument[]>

Get the current text selection in the active editor. Returns null if no editor is open. Positions are ProseMirror document positions (use with insertAt/replaceRange).

getSelection() → Promise<EditorSelection | null>

Get the word count of the active document. Returns 0 if no editor is open.

getWordCount() → Promise<number>

Insert HTML content at a specific position in the active editor.

insertAt(position: number, html: string) → Promise<void>

Insert a read-only block showing one of the project's flow maps.

insertFlowMap(flowMapId: string, position?: number) → Promise<void>

Open an item of the project in Tintero, as if the user had clicked it in the file tree. If it is already open, its tab becomes the active one. Works with the ids of documents, characters, worldbuilding elements, images, audio and PDFs: the id alone identifies the kind, so there is no type to pass. It takes the user to the editor. Called from an app view, that view is hidden, not destroyed: it keeps running and its state is intact if the user comes back within 10 minutes (and without opening another project in between). Rejects if nothing in the open project has that id, and when called from an app view the user has left (hidden): a view nobody is looking at cannot move them elsewhere.

open(id: string) → Promise<void>

Replace a range of content in the active editor.

replaceRange(from: number, to: number, html: string) → Promise<void>

Replace the current selection with HTML content. If the selection is empty (cursor only), inserts at the cursor position.

replaceSelection(html: string) → Promise<void>

Clear the console log buffer.

clear() → Promise<void>

Get all stored console log entries. Requires debug.console scope.

getLogs() → Promise<ConsoleEntry[]>

Convert HTML to ProseMirror JSON. Supports standard HTML elements: <p>, <h1>–<h6>, <strong>, <em>, <a>, <ul>, <ol>, <blockquote>, <code>, <table>, etc.

fromHtml(html: string) → Promise<ProseMirrorDocument>

Convert Markdown to ProseMirror JSON. Parses standard Markdown syntax (headings, bold, italic, links, lists, code blocks).

fromMarkdown(markdown: string) → Promise<ProseMirrorDocument>

Convert plain text to ProseMirror JSON. Each line becomes a paragraph node.

fromText(text: string) → Promise<ProseMirrorDocument>

Convert ProseMirror JSON to clean HTML. Returns HTML fragment (no <html>/<body> wrapper). Supports headings, paragraphs, lists, bold, italic, links, images. Accepts a parsed ProseMirrorDocument object or a raw JSON string.

toHtml(json: ProseMirrorDocument | string) → Promise<string>

Convert ProseMirror JSON to Markdown. Uses ATX-style headings (#), bold, *italic*, [links](url). Accepts a parsed ProseMirrorDocument object or a raw JSON string.

toMarkdown(json: ProseMirrorDocument | string) → Promise<string>

Convert ProseMirror JSON to plain text. Extracts text content, discarding all formatting. Accepts a parsed ProseMirrorDocument object or a raw JSON string (as returned by getFileContent()).

toText(json: ProseMirrorDocument | string) → Promise<string>

Perform an HTTP request to an external host (proxied by the host app). Requires the net.fetch scope and the target host must be listed in the plugin manifest's network.domains allow-list (the user approves those domains at install time). Requests to any other host are rejected. Supports exact hosts and leading-wildcard subdomains (*.example.com).

fetch(url: string, options?: NetFetchOptions) → Promise<NetFetchResponse>

getNowPlaying() → Promise<MediaNowPlaying | null>

getState() → Promise<'idle' | 'playing' | 'paused' | 'buffering' | 'ended'>

next() → Promise<void>

pause() → Promise<void>

Play a public YouTube video or playlist (URL or id) in the host's background player.

play(source: string) → Promise<void>

previous() → Promise<void>

resume() → Promise<void>

Set the volume, 0–100.

setVolume(volume: number) → Promise<void>

stop() → Promise<void>