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:

Install a bridge plugin that exposes
```
logseq
```
API via HTTP (e.g., via a custom plugin or localhost endpoint)
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 &quot;TODO&quot;]]);

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

Always check for null: API methods may return
```
null
```
if entity doesn't exist
Use UUIDs over IDs: Block UUIDs are stable, entity IDs can change
Batch operations: Use
```
insertBatchBlock
```
for multiple inserts
Query efficiently: Datalog queries are powerful but can be slow on large graphs
Properties are objects: Access with
```
block.properties.propertyName
```
Format matters: Respect user's preferred format (markdown vs org-mode)
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:
```
)

Logseq

AI Skill Market Insights

Be Part of the 0+ Developer Community

Logseq Plugin API

Prerequisites

Core API Namespaces

`logseq.App`

`logseq.Editor`

`logseq.DB`

`logseq.UI`

`logseq.Git`

`logseq.Assets`

Common Workflows

Read Content

Write Content

Task Management

Navigation and UI

Implementation Approaches

Option 1: Bridge Plugin

Option 2: Node.js Script with @logseq/libs

Option 3: Direct Plugin Development

API Reference

Key Data Structures

BlockEntity

PageEntity

Tips & Best Practices

Common Gotchas

Quick Start

Manual Installation

TEAR & SHARE

Tags

writing-plans

executing-plans

plan-ceo-review

Office Automation

Todo Manager

Channels

Learn

Compare

Company