✓ Verified 💻 Development ✓ Enhanced Data

Inkdrop

Read, create, update, search, and delete notes in Inkdrop via its local HTTP server API.

Rating: 3.8 (373 reviews)
Downloads: 16,111 downloads
Version: 1.0.0

Overview

Read, create, update, search, and delete notes in Inkdrop via its local HTTP server API.

Complete Documentation

View Source →

Inkdrop Notes

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

Prerequisites

Inkdrop desktop app installed and running
Local HTTP server enabled in Inkdrop preferences (Preferences → API → Enable Local HTTP Server)
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

Field	Type	Description
_id	string	note: (auto-generated)
_rev	string	Revision token (required for updates)
title	string	Note title
body	string	Markdown content
doctype	string	Always "markdown"
bookId	string	Notebook ID (e.g., book:inbox)
tags	string[]	Array of tag IDs
status	string	none, active, onHold, completed, dropped
pinned	boolean	Pin to top
share	string	private or public
createdAt	number	Unix timestamp (ms)
updatedAt	number	Unix 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: format

Installation

Terminal bash


openclaw install inkdrop

Copied!

💻Code Examples

export INKDROP_AUTH="username:password" # from Inkdrop preferences

export-inkdropauthusernamepassword--from-inkdrop-preferences.txt

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

# Returns: {"version":"5.x.x","ok":true}

-returns-version5xxoktrue.txt

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

curl--s--u-inkdropauth-httplocalhost19840notes.txt

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

curl--s--u-inkdropauth-httplocalhost19840docid.txt

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

}'

-.txt

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

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

curl--s--u-inkdropauth-httplocalhost19840files.txt

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"

curl--s--u-inkdropauth-httplocalhost19840changessince0limit50includedocstrue.txt

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:

example.sh

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": []
  }'

example.sh

# 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"
  }'

example.sh

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

Related Skills

✓ Verified 💻 Development

4claw

4claw — a moderated imageboard for AI agents.

🧠 Claude-Ready #ai_and-llms

✓ Verified 💻 Development

Aap Passport

Agent Attestation Protocol - The Reverse Turing Test.

🧠 Claude-Ready #ai_and-llms

✓ Verified 💻 Development

Acestep Lyrics Transcription

Transcribe audio to timestamped lyrics using OpenAI Whisper or ElevenLabs Scribe API.

⚡ GPT-Optimized #ai_and-llms #api #script

✓ Verified 💻 Development

Adaptive Suite

A continuously adaptive skill suite that empowers Clawdbot.

🧠 Claude-Ready #ai_and-llms #bot

Overview

Complete Documentation

Inkdrop Notes

Prerequisites

Setup

Connection

API Reference

List Notes

Get Single Document

Create Note

Update Note

Delete Document

List Notebooks

Create Notebook

List Tags

Create Tag

List/Create Files (Attachments)

Changes Feed

Helper Script

Note Model

Status Values

Conventions

Installation

💻Code Examples

export INKDROP_AUTH="username:password" # from Inkdrop preferences

# Returns: {"version":"5.x.x","ok":true}

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

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

}'

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

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

Tags

Quick Info

Ready to Install?

Resources

Related Skills

4claw

Aap Passport

Acestep Lyrics Transcription

Adaptive Suite