# Joplin Manage Tags

> Create, list, update, delete tags and tag/untag notes in Joplin

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

---


# Joplin Manage Tags

This skill manages tags in Joplin and handles tagging/untagging notes via the REST API.

## Configuration

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

## List All Tags

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

### Pagination

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

## Get a Tag

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

## Create a Tag

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

**Note**: Tag titles are case-insensitive and typically lowercase.

## Rename a Tag

```bash
curl -s -X PUT "http://localhost:${JOPLIN_PORT:-41184}/tags/TAG_ID?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "new-tag-name"
  }'
```

## Delete a Tag

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

This removes the tag from all notes. Confirm with the user before deleting.

## List Notes with a Specific Tag

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

## Add a Tag to a Note

```bash
curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/tags/TAG_ID/notes?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "NOTE_ID"
  }'
```

## Remove a Tag from a Note

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

## List Tags on a Note

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

## Finding a Tag by Name

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

Or filter from the full list:

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/tags?token=$JOPLIN_TOKEN&fields=id,title" | jq '.items[] | select(.title == "tag-name")'
```

## Bulk Tagging Workflow

To tag multiple notes with the same tag:

1. Find or create the tag to get its ID.
2. For each note, POST to `/tags/TAG_ID/notes` with the note ID.

## Workflow

1. Resolve tag names to IDs when needed (search or list).
2. Resolve note titles to IDs when needed (search notes).
3. Perform the requested operation.
4. Confirm destructive operations (delete) with the user.
5. Report success with tag name and ID.

## Error Handling

- **403**: Invalid token
- **404**: Tag or note not found — verify IDs
- **Connection refused**: Joplin not running