Inkdrop

interact with inkdrop's local http server to manage notes, notebooks, and tags. use this skill when the user asks to take notes, save ideas, manage project notes, search notes, read notes, or organize thoughts, backlogs, and task lists that should persist in inkdrop.

intent

inkdrop is a local-first note app with a built-in http api. this skill lets you read, create, update, search, and delete notes and notebooks without leaving the terminal or automation flow. use it whenever note-taking, idea capture, knowledge management, or task list updates come up in conversation. requires inkdrop desktop app running on the user's machine with the local http server enabled.

inputs

external connection: inkdrop local http server

• url: http://localhost:19840 (configurable via INKDROP_URL env var; default port is 19840)
• auth method: http basic auth with credentials from inkdrop preferences
• status check: curl -s -u "$INKDROP_AUTH" "${INKDROP_URL:-http://localhost:19840}/" → {"version":"5.x.x","ok":true}

environment variables

• INKDROP_AUTH (required): basic auth credentials in format username:password. source from inkdrop preferences under Preferences → API → Enable Local HTTP Server. do not hardcode into shell profiles; use workspace secrets or temporary exports.
• INKDROP_URL (optional): full base url including port. defaults to http://localhost:19840 if unset.

prerequisite setup

1. inkdrop desktop app installed and running
2. local http server enabled in preferences (Preferences → API → Enable Local HTTP Server)
3. username and password noted from the same preferences pane

procedure

1. verify inkdrop connection

input: INKDROP_AUTH and INKDROP_URL env vars set

action: ping inkdrop api to confirm server is running and credentials are valid

curl -s -u "$INKDROP_AUTH" "${INKDROP_URL:-http://localhost:19840}/"

output: json response with "ok": true and version string. if request times out or returns 401, inkdrop server is not running or credentials are wrong. if response is empty or connection refused, server is not listening on the configured port.

---

2. list or search notes

input: optional keyword, limit, offset (skip), sort field, sort direction

action: fetch notes from /notes endpoint with query parameters

curl -s -u "$INKDROP_AUTH" \
  "${INKDROP_URL:-http://localhost:19840}/notes?keyword=<search_text>&limit=<count>&skip=<offset>&sort=<field>&descending=<true|false>"

query params

• keyword , text search (supports same qualifiers as inkdrop desktop search)
• limit , max results to return. omit for all results. note: large result sets may cause slow responses or memory issues.
• skip , result offset for pagination
• sort , field to sort by: updatedAt, createdAt, or title
• descending , boolean, reverse sort order

output: json array of note objects. each has _id, _rev, title, body, bookId, tags, status, createdAt, updatedAt. empty array if no matches.

---

3. get a single note or document

input: full document id (e.g., note:abc123, book:xyz, tag:mytag)

action: fetch specific document by id

curl -s -u "$INKDROP_AUTH" \
  "${INKDROP_URL:-http://localhost:19840}/<docid>?rev=<revision>&attachments=<true|false>"

query params

• rev , optional specific revision number to fetch historical version
• attachments , boolean, include base64-encoded attachment data (use for file documents or notes with embedded images)

output: single json object with all fields for that document. if document not found, returns 404. if revision does not exist, returns error.

---

4. create a new note

input: title (string), body (string, markdown), bookId (string, defaults to book:inbox), optional tags (array of tag ids), optional status (string)

action: post new note to /notes endpoint

curl -s -u "$INKDROP_AUTH" -X POST \
  "${INKDROP_URL:-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": []
  }'

required fields

• doctype: always "markdown"
• title: non-empty string
• bookId: valid notebook id. use book:inbox as fallback if notebook unknown. call /books first to list available notebooks if organizing into custom notebook.
• status: one of none, active, onHold, completed, dropped. default none.

output: json object with assigned _id (format note:<id>), _rev, and all submitted fields. use _id and _rev for future updates.

---

5. update an existing note

input: note id, current _rev (required to prevent conflicts), new title, body, status, tags, or other fields

action: fetch current _rev, then post updated note with both _id and _rev

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

# step 2: post update with _rev
curl -s -u "$INKDROP_AUTH" -X POST \
  "${INKDROP_URL:-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": "active"
  }'

critical: always fetch and include _rev before updating. omitting _rev or using stale _rev causes 409 conflict error and update fails.

output: json object with new _rev value. if _rev is stale or missing, returns 409 conflict error. user must retry with fresh _rev.

---

6. delete a note or document

input: document id (e.g., note:abc123)

action: send delete request to document endpoint

curl -s -u "$INKDROP_AUTH" -X DELETE \
  "${INKDROP_URL:-http://localhost:19840}/note:abc123"

output: json response confirming deletion (typically {"ok":true}). if document not found, returns 404. deletion is permanent and cannot be undone via api.

---

7. list notebooks

input: none

action: fetch all notebooks (books)

curl -s -u "$INKDROP_AUTH" \
  "${INKDROP_URL:-http://localhost:19840}/books"

output: json array of book objects. each has _id (format book:<id>), name, color, count (number of notes), createdAt, updatedAt.

---

8. create a new notebook

input: notebook name (string)

action: post new notebook to /books endpoint

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

output: json object with assigned _id (format book:<id>), name, and metadata. use returned _id as bookId when creating notes.

---

9. list tags

input: none

action: fetch all tags

curl -s -u "$INKDROP_AUTH" \
  "${INKDROP_URL:-http://localhost:19840}/tags"

output: json array of tag objects. each has _id (format tag:<name>), name, color, count (number of tagged notes).

---

10. create a new tag

input: tag name (string), optional color (string)

action: post new tag to /tags endpoint

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

note: _id must follow format tag:<name>. color is optional; valid values are inkdrop color names (e.g., blue, red, green).

output: json object with assigned _id and name. use in note tags array.

---

11. watch for changes (sync feed)

input: optional since (sequence number), limit, sort direction, include docs flag

action: fetch changes feed to detect updates made by other sessions or clients

curl -s -u "$INKDROP_AUTH" \
  "${INKDROP_URL:-http://localhost:19840}/_changes?since=0&limit=50&include_docs=true&descending=false"

query params

• since , sequence number to start from. use 0 for all changes. use previous last_seq to poll incrementally.
• limit , max changes to return per request
• descending , boolean, reverse chronological order
• include_docs , boolean, include full document body in response
• conflicts , boolean, include conflicted revisions

output: json object with results array (each entry has seq, id, changes), last_seq (use for next poll), pending (count of unpropagated changes). useful for real-time sync or detecting external updates.

---

decision points

if inkdrop server is not running or unreachable:

• step 1 ping returns connection refused or timeout
• action: prompt user to start inkdrop desktop app and ensure local http server is enabled in preferences
• do not retry automatically; wait for user to confirm server is ready

if credentials are invalid (401 unauthorized):

• step 1 ping returns 401
• action: prompt user to verify INKDROP_AUTH matches username:password from inkdrop preferences
• do not retry with different credentials; exit and ask user to reconfigure

if a note update returns 409 conflict:

• step 5 post fails because _rev is stale (note was modified by another client)
• action: fetch latest _rev again and retry update with fresh revision token
• if conflict persists after retry, ask user to inspect current note state before re-applying update

if search returns empty result set:

• step 2 query matches no notes
• action: return empty array gracefully. do not error. suggest user broaden search keyword or check if notes exist in requested notebook.

if bookId does not exist when creating a note:

• step 4 post references non-existent notebook id
• action: inkdrop api returns error. fall back to book:inbox and retry, or call /books first to let user pick a valid notebook.

if rate limit is hit (too many requests in short time):

• api returns 429 or 503
• action: backoff exponentially (wait 1s, then 2s, then 4s) and retry up to 3 times
• if still failing after backoffs, report timeout to user

if network timeout occurs during large result fetch:

• curl returns timeout error (e.g., max 30s)
• action: reduce limit parameter and retry with pagination (use skip parameter)
• if fetching single note times out, reduce use of attachments=true parameter

if attachment data is corrupted or missing:

• step 3 with attachments=true returns incomplete or null attachment field
• action: re-fetch without attachments or ask user to check file integrity in inkdrop app

output contract

list notes (step 2): json array of note objects. minimum fields: _id (string, format note:<id>), _rev (string), title (string), body (string, markdown), bookId (string), status (string), createdAt (number, unix ms), updatedAt (number, unix ms). may include tags (string array), pinned (boolean), share (string).

get single note (step 3): single json object with all note fields plus _rev for future updates. format: {"_id":"note:abc123","_rev":"2-xyz","title":"...","body":"...","bookId":"book:inbox",...}.

create note (step 4): json object with assigned _id (format note:<id>), _rev, and all submitted fields. location: returned in http response body. note is immediately queryable via /notes or /note:<id>.

update note (step 5): json object with new _rev and updated fields. location: returned in http response body. changes are immediately visible in subsequent queries.

delete note (step 6): json response {"ok":true}. note is removed from all queries and cannot be recovered. deleted document id is not reused.

list notebooks (step 7): json array of book objects. each: {"_id":"book:<id>","name":"...","count":<number>,"createdAt":<ms>,"updatedAt":<ms>}.

create notebook (step 8): json object with assigned _id (format book:<id>), name, and metadata. notebook is immediately available for use in note bookId field.

list tags (step 9): json array of tag objects. each: {"_id":"tag:<name>","name":"...","color":"...","count":<number>}.

create tag (step 10): json object with _id (format tag:<name>), name, and metadata. tag is immediately available for assignment to notes.

changes feed (step 11): json object with results (array of change entries), last_seq (use for incremental polling), pending (count of unpolled changes). each result entry: {"seq":<number>,"id":"<docid>","changes":[{"rev":"<rev>"}]}.

all error responses: http status code (401, 404, 409, 500) with json error body. example: {"error":"conflict","reason":"Document update conflict."}. client must check http status and parse error field.

outcome signal

note creation succeeded: user receives _id of new note in response and can immediately query /notes to see it listed.

note update succeeded: user receives new _rev in response. subsequent queries on that note id return updated title, body, or status fields.

search executed: user receives json array (possibly empty) of notes matching keyword. if array is not empty, at least one note title or body contains search term.

note deleted: user receives {"ok":true} response. subsequent queries for that note id return 404. note no longer appears in /notes list.

notebook created: user receives new bookId in response and can immediately use it to assign new notes to that notebook.

tag created: user receives new tag id (format tag:<name>) and can immediately add it to note tags array.

connection verified: curl to / endpoint returns {"version":"...","ok":true} with non-empty version string. no timeout or auth error occurs.

changes detected: polling /changes returns results array with seq numbers greater than previous last_seq. user can inspect id field to identify which documents changed and fetch their new state.

---

credits: original skill authored for clawhub. adapted and enriched to implexa standards with explicit inputs, decision points, and edge case handling.