# Joplin Create Note

> Create, update, or delete notes in Joplin

- Skill: `leixinsun/joplin-create-note` (Agent Skill)
- Install (CLI): `npx skillmds@latest add leixinsun/joplin-create-note`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leixinsun/joplin-create-note/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-create-note

---


# Joplin Create/Edit/Delete Note

This skill creates, updates, and deletes notes in Joplin via the REST API.

## Configuration

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

## Create a Note

```bash
curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/notes?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "NOTE_TITLE",
    "body": "MARKDOWN_BODY",
    "parent_id": "NOTEBOOK_ID",
    "is_todo": 0,
    "tags": "tag1,tag2"
  }'
```

### Fields

| Field | Required | Description |
|-------|----------|-------------|
| `title` | Yes | Note title |
| `body` | No | Note content in Markdown (or HTML if `markup_language=2`) |
| `parent_id` | No | Notebook ID to place note in. If omitted, goes to default notebook. |
| `is_todo` | No | `0` = regular note (default), `1` = todo/checkbox item |
| `todo_due` | No | Due date as Unix timestamp in milliseconds |
| `todo_completed` | No | Completion timestamp in ms (`0` = not completed) |
| `tags` | No | Comma-separated tag titles. Tags are created if they don't exist. |
| `markup_language` | No | `1` = Markdown (default), `2` = HTML |
| `source_url` | No | Source URL for the note |

### Finding the notebook ID

If the user specifies a notebook by name, look it up first:

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

Or list all notebooks:

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

## Update a Note

```bash
curl -s -X PUT "http://localhost:${JOPLIN_PORT:-41184}/notes/NOTE_ID?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "body": "Updated markdown content"
  }'
```

Only include fields you want to change. Omitted fields are not modified.

### Finding a note to update

Search by title:

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/search?query=title:NOTE_TITLE&token=$JOPLIN_TOKEN&fields=id,title,parent_id,updated_time"
```

## Delete a Note

```bash
curl -s -X DELETE "http://localhost:${JOPLIN_PORT:-41184}/notes/NOTE_ID?token=$JOPLIN_TOKEN"
```

**Always confirm with the user before deleting a note.**

## Create a Note with Resource Links

To reference an existing resource (attachment) in a note:

```markdown
![image description](:/${resource_id})
[file name](:/${resource_id})
```

## Workflow

1. If user specifies a notebook name, resolve it to an ID first.
2. Create/update/delete the note.
3. Report back the note ID and title on success.
4. On error, report the error message and suggest fixes.

## Error Handling

- **403**: Invalid token — check `$JOPLIN_TOKEN`
- **404**: Note or notebook not found — verify the ID
- **Connection refused**: Joplin not running or Web Clipper disabled

## Tips

- When creating long notes, use a heredoc or write the body to a temp file to avoid shell escaping issues:
  ```bash
  BODY=$(cat <<'NOTEEOF'
  # My Note

  This is the **content** with special characters: "quotes", 'apostrophes', and $dollars.
  NOTEEOF
  )
  curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/notes?token=$JOPLIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg title "My Note" --arg body "$BODY" '{title: $title, body: $body}')"
  ```
- Use `jq` for constructing JSON payloads to handle escaping properly.