{"skill":{"slug":"inkdrop","displayName":"Inkdrop","summary":"Read, create, update, search, and delete notes in Inkdrop via its local HTTP server API. Use when the user asks to take notes, save ideas, manage project not...","description":"---\nname: inkdrop\ndescription: Read, create, update, search, and delete notes in Inkdrop via its local HTTP server API. Use when the user asks to take notes, save ideas, manage project notes, read notes, search notes, or interact with Inkdrop in any way. Also use when organizing thoughts, project backlogs, or task lists that should persist in Inkdrop.\nenv:\n  INKDROP_AUTH:\n    required: true\n    description: \"Basic auth credentials (user:password) from Inkdrop preferences\"\n  INKDROP_URL:\n    required: false\n    description: \"Inkdrop local server URL (default: http://localhost:19840)\"\n---\n\n# Inkdrop Notes\n\nInteract with Inkdrop's local HTTP server to manage notes, notebooks, and tags.\n\n## Prerequisites\n\n1. [Inkdrop](https://inkdrop.app) desktop app installed and running\n2. Local HTTP server enabled in Inkdrop preferences (Preferences → API → Enable Local HTTP Server)\n3. Note the port, username, and password from the Inkdrop preferences\n\n## Setup\n\nSet environment variables:\n\n```bash\nexport INKDROP_URL=\"http://localhost:19840\"   # default port\nexport INKDROP_AUTH=\"username:password\"        # from Inkdrop preferences\n```\n\nFor OpenClaw, store credentials in a secrets file (e.g., workspace `secrets.md`) and source them at runtime. Avoid persisting plaintext credentials in shell profiles.\n\n## Connection\n\n```\nBase URL: http://localhost:19840 (or INKDROP_URL env var)\nAuth: Basic auth via INKDROP_AUTH env var (user:password)\n```\n\nVerify connection:\n\n```bash\ncurl -s -u \"$INKDROP_AUTH\" \"${INKDROP_URL:-http://localhost:19840}/\"\n# Returns: {\"version\":\"5.x.x\",\"ok\":true}\n```\n\n## API Reference\n\nAll endpoints use Basic auth. Replace `USER:PASS` with your `$INKDROP_AUTH` value.\n\n### List Notes\n\n```bash\ncurl -s -u $INKDROP_AUTH http://localhost:19840/notes\n```\n\nQuery params:\n- `keyword` — search text (same qualifiers as Inkdrop search)\n- `limit` — max results (default: all)\n- `skip` — offset for pagination\n- `sort` — `updatedAt`, `createdAt`, or `title`\n- `descending` — reverse order (boolean)\n\n### Get Single Document\n\n```bash\ncurl -s -u $INKDROP_AUTH \"http://localhost:19840/<docid>\"\n```\n\nThe `docid` is the full `_id` (e.g., `note:abc123`, `book:xyz`). Works for notes, books, tags, files.\n\nOptional params:\n- `rev` — fetch specific revision\n- `attachments` — include attachment data (boolean, use for file documents)\n\n### Create Note\n\n```bash\ncurl -s -u $INKDROP_AUTH -X POST http://localhost:19840/notes \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"doctype\": \"markdown\",\n    \"title\": \"Note Title\",\n    \"body\": \"Markdown content here\",\n    \"bookId\": \"book:inbox\",\n    \"status\": \"none\",\n    \"tags\": []\n  }'\n```\n\n`_id` is auto-generated. `bookId` is required — use `book:inbox` as default or look up notebooks first.\n\n### Update Note\n\nPOST with `_id` and `_rev` (required to avoid conflicts):\n\n```bash\n# 1. Get current _rev\nREV=$(curl -s -u $INKDROP_AUTH \"http://localhost:19840/note:abc123\" | python3 -c \"import sys,json; print(json.load(sys.stdin)['_rev'])\")\n\n# 2. Update with _rev\ncurl -s -u $INKDROP_AUTH -X POST http://localhost:19840/notes \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"_id\": \"note:abc123\",\n    \"_rev\": \"'\"$REV\"'\",\n    \"doctype\": \"markdown\",\n    \"title\": \"Updated Title\",\n    \"body\": \"Updated content\",\n    \"bookId\": \"book:inbox\",\n    \"status\": \"none\"\n  }'\n```\n\n### Delete Document\n\n```bash\ncurl -s -u $INKDROP_AUTH -X DELETE \"http://localhost:19840/<docid>\"\n```\n\n### List Notebooks\n\n```bash\ncurl -s -u $INKDROP_AUTH http://localhost:19840/books\n```\n\n### Create Notebook\n\n```bash\ncurl -s -u $INKDROP_AUTH -X POST http://localhost:19840/books \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"My Notebook\"}'\n```\n\n### List Tags\n\n```bash\ncurl -s -u $INKDROP_AUTH http://localhost:19840/tags\n```\n\n### Create Tag\n\n```bash\ncurl -s -u $INKDROP_AUTH -X POST http://localhost:19840/tags \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"_id\": \"tag:mytag\", \"name\": \"mytag\", \"color\": \"blue\"}'\n```\n\n### List/Create Files (Attachments)\n\n```bash\ncurl -s -u $INKDROP_AUTH http://localhost:19840/files\n```\n\nCreate with POST to `/files`. Files are primarily image attachments for notes.\n\n### Changes Feed\n\n```bash\ncurl -s -u $INKDROP_AUTH \"http://localhost:19840/_changes?since=0&limit=50&include_docs=true\"\n```\n\nParams: `since` (sequence number), `limit`, `descending`, `include_docs`, `conflicts`, `attachments`.\n\nReturns changes in order they were made. Useful for syncing or watching for updates.\n\n## Helper Script\n\nThe included `scripts/inkdrop.sh` wraps common operations:\n\n```bash\nexport INKDROP_AUTH=\"username:password\"\n\n# List all notes\n./scripts/inkdrop.sh notes\n\n# Search notes\n./scripts/inkdrop.sh search \"project ideas\"\n\n# Get a specific note\n./scripts/inkdrop.sh get \"note:abc123\"\n\n# Create a note (title, bookId, body)\n./scripts/inkdrop.sh create \"My Note\" \"book:inbox\" \"Note content here\"\n\n# List notebooks\n./scripts/inkdrop.sh books\n\n# List tags\n./scripts/inkdrop.sh tags\n\n# Delete a document\n./scripts/inkdrop.sh delete \"note:abc123\"\n```\n\n## Note Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `_id` | string | `note:<id>` (auto-generated) |\n| `_rev` | string | Revision token (required for updates) |\n| `title` | string | Note title |\n| `body` | string | Markdown content |\n| `doctype` | string | Always `\"markdown\"` |\n| `bookId` | string | Notebook ID (e.g., `book:inbox`) |\n| `tags` | string[] | Array of tag IDs |\n| `status` | string | `none`, `active`, `onHold`, `completed`, `dropped` |\n| `pinned` | boolean | Pin to top |\n| `share` | string | `private` or `public` |\n| `createdAt` | number | Unix timestamp (ms) |\n| `updatedAt` | number | Unix timestamp (ms) |\n\n## Status Values\n\n- `none` — Default\n- `active` — In progress\n- `onHold` — Paused\n- `completed` — Done\n- `dropped` — Abandoned\n\n## Conventions\n\n- Default notebook for quick captures: `book:inbox`\n- Use existing notebooks when context is clear (match by name via `GET /books`)\n- Use markdown formatting in note bodies\n- Always fetch `_rev` before updating to avoid conflicts\n- Tag IDs use `tag:<name>` format\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":375,"installsAllTime":14,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1771418138406,"updatedAt":1779077107465},"latestVersion":{"version":"1.0.1","createdAt":1771418371010,"changelog":"Declare env vars in metadata, fix credential storage advice","license":null},"metadata":null,"owner":{"handle":"iamngoni","userId":"s1766cfwtq4tgss8k0pwfsyp91885qkj","displayName":"Ngonidzashe Mangudya","image":"https://avatars.githubusercontent.com/u/38191932?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779921926780}}