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

// 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

// 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

// 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

// 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:

// 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:

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

{
  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

{
  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:)