Joplin Manage Notebooks

Joplin Manage Notebooks

This skill manages notebooks (folders) in Joplin via the REST API.

Configuration

• Base URL: http://localhost:${JOPLIN_PORT:-41184}
• Auth Token: $JOPLIN_TOKEN

List All Notebooks

curl -s "http://localhost:${JOPLIN_PORT:-41184}/folders?token=$JOPLIN_TOKEN&fields=id,title,parent_id"

Display as Tree

Notebooks can be nested. Use parent_id to build a tree:

• Top-level notebooks have parent_id = "" (empty string)
• Sub-notebooks have parent_id set to their parent's id

Present notebooks as a tree structure when displaying to the user.

Pagination

If has_more is true, fetch additional pages:

curl -s "http://localhost:${JOPLIN_PORT:-41184}/folders?token=$JOPLIN_TOKEN&fields=id,title,parent_id&page=2"

Get a Notebook

curl -s "http://localhost:${JOPLIN_PORT:-41184}/folders/NOTEBOOK_ID?token=$JOPLIN_TOKEN"

List Notes in a Notebook

curl -s "http://localhost:${JOPLIN_PORT:-41184}/folders/NOTEBOOK_ID/notes?token=$JOPLIN_TOKEN&fields=id,title,updated_time,is_todo,todo_completed&order_by=updated_time&order_dir=DESC"

Create a Notebook

curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/folders?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "NOTEBOOK_NAME"
  }'

Create a Sub-Notebook

curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/folders?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SUB_NOTEBOOK_NAME",
    "parent_id": "PARENT_NOTEBOOK_ID"
  }'

Rename a Notebook

curl -s -X PUT "http://localhost:${JOPLIN_PORT:-41184}/folders/NOTEBOOK_ID?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "NEW_NAME"
  }'

Move a Notebook (Change Parent)

curl -s -X PUT "http://localhost:${JOPLIN_PORT:-41184}/folders/NOTEBOOK_ID?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "NEW_PARENT_ID"
  }'

Set parent_id to "" to move a sub-notebook to the top level.

Delete a Notebook

curl -s -X DELETE "http://localhost:${JOPLIN_PORT:-41184}/folders/NOTEBOOK_ID?token=$JOPLIN_TOKEN"

Warning: Deleting a notebook permanently deletes all notes inside it. Always confirm with the user before deleting.

Finding a Notebook by Name

curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=NOTEBOOK_NAME&type=folder&token=$JOPLIN_TOKEN&fields=id,title"

Workflow

1. For list operations, fetch all notebooks and present them as a tree.
2. For create/update/delete, resolve notebook names to IDs first if needed.
3. Always confirm before deleting a notebook (destructive operation).
4. Report the notebook ID and title on success.

Error Handling

• 403: Invalid token
• 404: Notebook not found — verify the ID
• 409: Conflict — notebook name may already exist
• Connection refused: Joplin not running