logseq

# Logseq Plugin API Interact with your local Logseq instance through its JavaScript Plugin API. This skill enables reading, writing, querying, and automating workflows in your Logseq graph. ## Prerequisites **Logseq must be running locally** with a plugin that exposes the API. The standard way is: 1. **Install a bridge plugin** that exposes `logseq` API via HTTP (e.g., via a custom plugin or localhost endpoint) 2. **Alternative**: Use Node.js with `@logseq/libs` package to script against the running Logseq instance The API is primarily designed for in-browser plugins, so accessing it from external scripts requires a bridge/proxy. ## Core API Namespaces The Logseq Plugin API is organized into these main proxies: ### `logseq.App` Application-level operations: getting app info, user configs, current graph, commands, UI state, external links. **Key methods:** - `getInfo()` - Get app version and info - `getUserConfigs()` - Get user preferences (theme, format, language, etc.) - `getCurrentGraph()` - Get current graph info (name, path, URL) - `registerCommand(type, opts, action)` - Register custom commands - `pushState(route, params, query)` - Navigate to routes ### `logseq.Editor` Block and page editing operations: creating, updating, moving, querying content. **Key methods:** - `getBlock(uuid)` - Get block by UUID - `getCurrentPage()` - Get current page entity - `getCurrentPageBlocksTree()` - Get all blocks on current page - `getPageBlocksTree(page)` - Get all blocks for a specific page - `insertBlock(target, content, opts)` - Insert a new block - `updateBlock(uuid, content)` - Update block content - `createPage(pageName, properties, opts)` - Create a new page - `deletePage(pageName)` - Delete a page - `getPageLinkedReferences(page)` - Get backlinks to a page - `registerSlashCommand(tag, action)` - Add custom slash commands ### `logseq.DB` Database queries using Datalog. **Key methods:** - `q(query, ...inputs)` - Run Datalog query - `datascriptQuery(query, ...inputs)` - Direct Datascript query ### `logseq.UI` UI operations: messages, dialogs, main UI visibility. **Key methods:** - `showMsg(content, status)` - Show toast notification - `queryElementById(id)` - Query DOM elements ### `logseq.Git` Git operations for the current graph. **Key methods:** - `execCommand(args)` - Execute git command ### `logseq.Assets` Asset management. **Key methods:** - `listFilesOfCurrentGraph(path)` - List files in graph ## Common Workflows ### Read Content ```javascript // Get current page const page = await logseq.Editor.getCurrentPage(); // Get all blocks on a page const blocks = await logseq.Editor.getPageBlocksTree('Daily Notes'); // Get a specific block const block = await logseq.Editor.getBlock('block-uuid-here'); // Query with Datalog const results = await logseq.DB.q(` [:find (pull ?b [*]) :where [?b :block/marker "TODO"]] `); ``` ### Write Content ```javascript // Create a new page await logseq.Editor.createPage('Project Notes', { tags: 'project', status: 'active' }, { redirect: false }); // Insert a block const block = await logseq.Editor.insertBlock( 'target-block-uuid', '- New task item', { before: false, sibling: true } ); // Update a block await logseq.Editor.updateBlock('block-uuid', 'Updated content'); // Batch insert multiple blocks const blocks = [ { content: 'First item' }, { content: 'Second item', children: [ { content: 'Nested item' } ]} ]; await logseq.Editor.insertBatchBlock('parent-uuid', blocks, { sibling: false }); ``` ### Task Management ```javascript // Find all TODO items const todos = await logseq.DB.q(` [:find (pull ?b [*]) :where [?b :block/marker ?marker] [(contains? #{"TODO" "DOING"} ?marker)]] `); // Mark task as DONE await logseq.Editor.updateBlock('task-uuid', 'DONE Task content'); // Get tasks on current page const page = await logseq.Editor.getCurrentPage(); const blocks = await logseq.Editor.getPageBlocksTree(page.name); const tasks = blocks.filter(b => b.marker === 'TODO' || b.marker === 'DOING'); ``` ### Navigation and UI ```javascript // Navigate to a page logseq.App.pushState('page', { name: 'Project Notes' }); // Show notification logseq.UI.showMsg('✅ Task completed!', 'success'); // Get app config const configs = await logseq.App.getUserConfigs(); console.log('Theme:', configs.preferredThemeMode); console.log('Format:', configs.preferredFormat); ``` ## Implementation Approaches Since Logseq's Plugin API is browser-based, you have several options: ### Option 1: Bridge Plugin Create a minimal Logseq plugin that exposes API calls via HTTP: ```javascript // In Logseq plugin (index.js) logseq.ready(() => { // Expose API endpoints logseq.provideModel({ async handleAPICall({ method, args }) { return await logseq.Editor[method](...args); } }); }); // Then call from external script via HTTP POST ``` ### Option 2: Node.js Script with @logseq/libs For automation scripts, use the `@logseq/libs` package: ```bash npm install @logseq/libs ``` **Note:** This requires a running Logseq instance and proper connection setup. ### Option 3: Direct Plugin Development Develop a full Logseq plugin following the plugin samples at: https://github.com/logseq/logseq-plugin-samples ## API Reference For complete API documentation, see: - **API Docs**: https://logseq.github.io/plugins/ - **Plugin Samples**: https://github.com/logseq/logseq-plugin-samples - **Type Definitions**: `references/api-types.md` (extracted from `@logseq/libs`) ## Key Data Structures ### BlockEntity ```typescript { id: number, // Entity ID uuid: string, // Block UUID content: string, // Block content format: 'markdown' | 'org', page: { id: number }, // Parent page parent: { id: number }, // Parent block left: { id: number }, // Previous sibling properties: {}, // Block properties marker?: string, // TODO/DOING/DONE children?: [] // Child blocks } ``` ### PageEntity ```typescript { id: number, uuid: string, name: string, // Page name (lowercase) originalName: string, // Original case 'journal?': boolean, properties: {}, journalDay?: number, // YYYYMMDD for journals } ``` ## Tips & Best Practices 1. **Always check for null**: API methods may return `null` if entity doesn't exist 2. **Use UUIDs over IDs**: Block UUIDs are stable, entity IDs can change 3. **Batch operations**: Use `insertBatchBlock` for multiple inserts 4. **Query efficiently**: Datalog queries are powerful but can be slow on large graphs 5. **Properties are objects**: Access with `block.properties.propertyName` 6. **Format matters**: Respect user's preferred format (markdown vs org-mode) 7. **Async all the way**: All API calls return Promises ## Common Gotchas - **Page names are lowercase**: When querying, use lowercase page names - **Journal pages**: Use `journalDay` format (YYYYMMDD) not date strings - **Block hierarchy**: Respect parent/child relationships when inserting - **Format differences**: Markdown uses `-` for bullets, Org uses `*` - **Properties syntax**: Different between markdown (`prop::`) and org (`:PROPERTIES:`)