Inkdrop Notes

Interact with Inkdrop's local HTTP server to manage notes, notebooks, and tags.

Prerequisites

1. Inkdrop desktop app installed and running
2. Local HTTP server enabled in Inkdrop preferences (Preferences → API → Enable Local HTTP Server)
3. Note the port, username, and password from the Inkdrop preferences

Setup

Set environment variables:

export INKDROP_URL="http://localhost:19840"   # default port
export INKDROP_AUTH="username:password"        # from Inkdrop preferences

For OpenClaw, store credentials in a secrets file (e.g., workspace secrets.md) and source them at runtime. Avoid persisting plaintext credentials in shell profiles.

Connection

Base URL: http://localhost:19840 (or INKDROP_URL env var)
Auth: Basic auth via INKDROP_AUTH env var (user:password)

Verify connection:

curl -s -u "$INKDROP_AUTH" "${INKDROP_URL:-http://localhost:19840}/"
# Returns: {"version":"5.x.x","ok":true}

API Reference

All endpoints use Basic auth. Replace USER:PASS with your $INKDROP_AUTH value.

List Notes

curl -s -u $INKDROP_AUTH http://localhost:19840/notes

Query params:

• keyword — search text (same qualifiers as Inkdrop search)
• limit — max results (default: all)
• skip — offset for pagination
• sort — updatedAt, createdAt, or title
• descending — reverse order (boolean)

Get Single Document

curl -s -u $INKDROP_AUTH "http://localhost:19840/<docid>"

The docid is the full _id (e.g., note:abc123, book:xyz). Works for notes, books, tags, files.

Optional params:

• rev — fetch specific revision
• attachments — include attachment data (boolean, use for file documents)

Create Note

curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/notes \
  -H "Content-Type: application/json" \
  -d '{
    "doctype": "markdown",
    "title": "Note Title",
    "body": "Markdown content here",
    "bookId": "book:inbox",
    "status": "none",
    "tags": []
  }'

_id is auto-generated. bookId is required — use book:inbox as default or look up notebooks first.

Update Note

POST with _id and _rev (required to avoid conflicts):

# 1. Get current _rev
REV=$(curl -s -u $INKDROP_AUTH "http://localhost:19840/note:abc123" | python3 -c "import sys,json; print(json.load(sys.stdin)['_rev'])")

# 2. Update with _rev
curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/notes \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "note:abc123",
    "_rev": "'"$REV"'",
    "doctype": "markdown",
    "title": "Updated Title",
    "body": "Updated content",
    "bookId": "book:inbox",
    "status": "none"
  }'

Delete Document

curl -s -u $INKDROP_AUTH -X DELETE "http://localhost:19840/<docid>"

List Notebooks

curl -s -u $INKDROP_AUTH http://localhost:19840/books

Create Notebook

curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/books \
  -H "Content-Type: application/json" \
  -d '{"name": "My Notebook"}'

List Tags

curl -s -u $INKDROP_AUTH http://localhost:19840/tags

Create Tag

curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/tags \
  -H "Content-Type: application/json" \
  -d '{"_id": "tag:mytag", "name": "mytag", "color": "blue"}'

List/Create Files (Attachments)

curl -s -u $INKDROP_AUTH http://localhost:19840/files

Create with POST to /files. Files are primarily image attachments for notes.

Changes Feed

curl -s -u $INKDROP_AUTH "http://localhost:19840/_changes?since=0&limit=50&include_docs=true"

Params: since (sequence number), limit, descending, include_docs, conflicts, attachments.

Returns changes in order they were made. Useful for syncing or watching for updates.

Helper Script

The included scripts/inkdrop.sh wraps common operations:

export INKDROP_AUTH="username:password"

# List all notes
./scripts/inkdrop.sh notes

# Search notes
./scripts/inkdrop.sh search "project ideas"

# Get a specific note
./scripts/inkdrop.sh get "note:abc123"

# Create a note (title, bookId, body)
./scripts/inkdrop.sh create "My Note" "book:inbox" "Note content here"

# List notebooks
./scripts/inkdrop.sh books

# List tags
./scripts/inkdrop.sh tags

# Delete a document
./scripts/inkdrop.sh delete "note:abc123"

Note Model

Status Values

• none — Default
• active — In progress
• onHold — Paused
• completed — Done
• dropped — Abandoned

Conventions

• Default notebook for quick captures: book:inbox
• Use existing notebooks when context is clear (match by name via GET /books)
• Use markdown formatting in note bodies
• Always fetch _rev before updating to avoid conflicts
• Tag IDs use tag:<name> format