# Joplin Manage Notebooks

> Create, list, update, and delete notebooks in Joplin

- Skill: `leixinsun/joplin-manage-notebooks` (Agent Skill)
- Install (CLI): `npx skillmds@latest add leixinsun/joplin-manage-notebooks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leixinsun/joplin-manage-notebooks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: LeixinSun (https://skillmd.com/u/leixinsun)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/leixinsun/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

```bash
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:

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

## Get a Notebook

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

## List Notes in a Notebook

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
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