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:

bash

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#

text

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

Verify connection:

bash

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#

bash

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#

bash

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#

bash

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

bash

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

bash

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

List Notebooks#

bash

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

Create Notebook#

bash

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

List Tags#

bash

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

Create Tag#

bash

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

bash

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

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

Changes Feed#

bash

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:

bash

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#

FieldTypeDescription_idstringnote:<id> (auto-generated)_revstringRevision token (required for updates)titlestringNote titlebodystringMarkdown contentdoctypestringAlways "markdown"``bookIdstringNotebook ID (e.g., book:inbox)tagsstring[]Array of tag IDsstatusstringnone, active, onHold, completed, dropped``pinnedbooleanPin to topsharestringprivate or public``createdAtnumberUnix timestamp (ms)updatedAtnumberUnix timestamp (ms)

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