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:

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:

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

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:

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

Workflow: First Time Setup

When user first invokes this skill:

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

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:

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

Common Operations

List Notebooks

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

List All Notes

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

Read a Note

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

Create a Notebook

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

Create a Note

# 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

# 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

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

Delete a Note

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:

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

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:

- [ ] 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:

# 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