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