Joplin

Manage Joplin notes via Server API - create, read, edit, search notes, notebooks, todos, and kanban boards

Install

openclaw skills install @slavaboiko/joplin-api-openclaw-skill

Joplin Server API Skill

Manage Joplin notes via the Joplin Server REST API (based on joppy).

CRITICAL: Always Execute Commands

NEVER assume or hallucinate results. You MUST:

Always run the actual commands using the Bash tool
Check for errors in JSON responses - report any errors to the user
Show real data from the API responses
If config is missing, offer to retrieve from 1Password or create manually

Setup

Credentials can be configured in two ways:

Option A: Config File

Create ~/.joplin-server-config:

bash

JOPLIN_SERVER_URL=https://your-joplin-server.com
JOPLIN_EMAIL=your-email@example.com
JOPLIN_PASSWORD=your-password
# Optional: skip TLS verification for self-signed certificates (security risk!)
# JOPLIN_SKIP_TLS_VERIFY=true

Option B: 1Password

If user prefers 1Password, retrieve credentials and create the config:

bash

# Get credentials from 1Password (adjust vault/item name as needed)
JOPLIN_URL=$(op read "op://Private/Joplin Server/url" 2>/dev/null)
JOPLIN_EMAIL=$(op read "op://Private/Joplin Server/username" 2>/dev/null)
JOPLIN_PASS=$(op read "op://Private/Joplin Server/password" 2>/dev/null)

# Write config file
cat > ~/.joplin-server-config << EOF
JOPLIN_SERVER_URL=$JOPLIN_URL
JOPLIN_EMAIL=$JOPLIN_EMAIL
JOPLIN_PASSWORD=$JOPLIN_PASS
EOF
chmod 600 ~/.joplin-server-config

Ask user for their 1Password vault name and item name if different from "Private/Joplin Server".

Client Usage

All commands use the bundled JavaScript client:

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js <command> [args...]

Available Commands

Command	Description
`ping`	Health check (no auth required)
`login`	Authenticate and verify connection
`list-notebooks`	List all notebooks
`list-notes`	List all notes
`get-note <id>`	Get note content
`add-notebook <title>`	Create a new notebook
`add-note <title> [parent_id] [body]`	Create a new note
`modify-note <id> <field> <value>`	Modify a note field
`delete-note <id>`	Delete a note
`search <query>`	Search notes by title/content

Response Format

All commands return JSON. Errors include an error field:

json

{"id": "abc123", "title": "My Note"}   // Success
{"ok": false, "error": "..."}          // Failure

Workflow: First Time Setup

When user first invokes this skill:

bash

# Step 1: Check if config exists
cat ~/.joplin-server-config 2>/dev/null || echo "CONFIG_MISSING"

# Step 2: If config exists, test connection
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js ping

If config is missing, ask user which setup method they prefer:

1Password - Ask for vault/item name, then run:

bash

JOPLIN_URL=$(op read "op://VAULT/ITEM/url")
JOPLIN_EMAIL=$(op read "op://VAULT/ITEM/username")
JOPLIN_PASS=$(op read "op://VAULT/ITEM/password")
cat > ~/.joplin-server-config << EOF
JOPLIN_SERVER_URL=$JOPLIN_URL
JOPLIN_EMAIL=$JOPLIN_EMAIL
JOPLIN_PASSWORD=$JOPLIN_PASS
EOF
chmod 600 ~/.joplin-server-config

Manual - User creates ~/.joplin-server-config with:

text

JOPLIN_SERVER_URL=https://your-server.com
JOPLIN_EMAIL=your-email
JOPLIN_PASSWORD=your-password

Common Operations

List Notebooks

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js list-notebooks

List All Notes

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js list-notes

Read a Note

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js get-note <note_id>

Create a Notebook

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-notebook "My Notebook"

Create a Note

bash

# Basic note
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-note "My Note Title"

# Note in a specific notebook
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-note "My Note Title" <notebook_id>

# Note with body content
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js add-note "My Note Title" <notebook_id> "Note body here"

Modify a Note

bash

# Update title
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js modify-note <note_id> title "New Title"

# Update body
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js modify-note <note_id> body "New body content"

Search Notes

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js search "search term"

Delete a Note

bash

node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js delete-note <note_id>

Sync Lock

The API client automatically handles Joplin's sync lock protocol:

Acquires a sync lock before write operations (add, modify, delete)
Releases the lock after the operation completes
Read operations (list, get, search) don't require locks

Item Types

Type	Value	Description
Note	1	Markdown notes
Folder	2	Notebooks
Resource	4	Attachments
Tag	5	Tags
NoteTag	6	Note-tag links

Note Content Format

Notes are returned as objects with these fields:

json

{
  "id": "abc123def456",
  "parent_id": "parent-folder-uuid",
  "title": "My Note Title",
  "body": "Note content in markdown...",
  "created_time": "2024-01-15T10:30:00.000Z",
  "updated_time": "2024-01-15T10:30:00.000Z",
  "type_": "1",
  "markup_language": "1"
}

TODOs

All TODOs go into the "TODOs" notebook.

Daily TODOs

Daily planning notes follow this naming format:

text

TODO#dd.mm.yy <Wd>

Where <Wd> is a 2-letter weekday: Mo, Tu, We, Th, Fr, Sa, Su

Examples:

TODO#16.03.26 Su (Sunday, March 16, 2026)
TODO#17.03.26 Mo (Monday, March 17, 2026)

Content format: One checkbox per line for individual tasks:

markdown

- [ ] Morning standup
- [ ] Review PR #123
- [ ] Deploy to staging
- [x] Send weekly report

General TODOs

Non-daily TODOs (projects, ideas, recurring tasks) also go in the "TODOs" notebook but:

Don't follow the TODO#dd.mm.yy naming format
Each note represents one individual task or topic
Use descriptive titles like "Fix authentication bug" or "Research caching options"

Kanban Notes (YesYouKan)

When editing kanban-formatted notes:

Column headings use # - Keep exact names: # Backlog, # In progress, # Done
Task headings use ##
Never modify the kanban-settings code block at the end
Preserve blank lines exactly as they appear

Error Handling

Error	Meaning
`CONFIG_MISSING`	No `~/.joplin-server-config` file
`Authentication failed`	Wrong credentials or server unreachable
`Request timeout`	Server not responding (check URL)
`Sync target has exclusive lock`	Another client is syncing
`404`	Item not found

Troubleshooting

If auth fails:

bash

# Test server reachability
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js ping

# Test login
node ${CLAUDE_SKILL_DIR}/scripts/joplin-server-api.js login

# Check config file
cat ~/.joplin-server-config

Joplin

Install

Joplin Server API Skill

CRITICAL: Always Execute Commands

Setup

Option A: Config File

Option B: 1Password

Client Usage

Available Commands

Response Format

Workflow: First Time Setup

Common Operations

List Notebooks

List All Notes

Read a Note

Create a Notebook

Create a Note

Modify a Note

Search Notes

Delete a Note

Sync Lock

Item Types

Note Content Format

TODOs

Daily TODOs

General TODOs

Kanban Notes (YesYouKan)

Error Handling

Troubleshooting

Related skills