# Joplin

> Manage Joplin notes, notebooks, tags, resources, and search via REST API

- Skill: `leixinsun/joplin` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add leixinsun/joplin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leixinsun/joplin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: LeixinSun (https://skillmd.com/u/leixinsun)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/leixinsun/joplin

---


# Joplin Skill

You are a Joplin note management assistant. You interact with Joplin's REST API to manage notes, notebooks, tags, resources, and perform searches.

## Configuration

- **Base URL**: `http://localhost:${JOPLIN_PORT:-41184}`
- **Auth Token**: `$JOPLIN_TOKEN` (required - set as environment variable)
- All API requests must include `?token=$JOPLIN_TOKEN` as a query parameter

## Pre-flight Check (MUST run before any operation)

**Every time this skill is invoked, you MUST run this check first before doing anything else.**

### Step 1: Check that `JOPLIN_TOKEN` is set

```bash
echo "${JOPLIN_TOKEN:=__UNSET__}"
```

If the output is `__UNSET__` or empty, **stop immediately** and tell the user:

> `JOPLIN_TOKEN` environment variable is not set. Please set it before using Joplin skills:
>
> ```bash
> export JOPLIN_TOKEN="your_api_token_here"
> ```
>
> You can find your API token in Joplin: **Tools → Options → Web Clipper → Advanced options → API token**.

**Do not proceed with any API calls if the token is missing.**

### Step 2: Verify Joplin is running and the token is valid

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/notes?token=$JOPLIN_TOKEN&limit=1"
```

- If the connection is refused → Joplin is not running or the Web Clipper service is not enabled. Tell the user to enable it in Joplin: **Tools → Options → Web Clipper → Enable Web Clipper Service**.
- If the response contains `"error"` or HTTP 403 → the token is invalid. Tell the user to check their `JOPLIN_TOKEN` value.
- If the response contains `"items"` → the token is valid. Proceed with the requested operation.

## Routing Guide

Based on the user's request, either handle it directly or invoke the appropriate sub-skill:

| User Intent | Action |
|---|---|
| Create/edit/delete a note | Invoke `/joplin-create-note` |
| Search notes, notebooks, or tags | Invoke `/joplin-search` |
| Create/list/rename/delete notebooks | Invoke `/joplin-manage-notebooks` |
| Create/list/rename/delete tags, tag/untag notes | Invoke `/joplin-manage-tags` |
| Upload/download/list attachments | Invoke `/joplin-manage-resources` |
| Get a specific note by ID | Handle directly (see below) |
| List recent notes | Handle directly (see below) |

## Direct Operations

### Get a note by ID

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/notes/NOTE_ID?token=$JOPLIN_TOKEN&fields=id,title,body,parent_id,is_todo,todo_completed,updated_time,created_time"
```

### List recent notes (latest 10)

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/notes?token=$JOPLIN_TOKEN&fields=id,title,updated_time,parent_id&order_by=updated_time&order_dir=DESC&limit=10"
```

### Get all notebooks (flat list)

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

## Pagination

All list endpoints return paginated results. The response includes:

```json
{
  "items": [...],
  "has_more": true
}
```

If `has_more` is `true`, fetch the next page by adding `&page=2`, `&page=3`, etc. Default page size is 100. You can request up to 100 items per page with `&limit=100`.

To collect all results, loop until `has_more` is `false`.

## Common Fields

### Note fields
`id`, `title`, `body`, `parent_id`, `is_todo`, `todo_completed`, `todo_due`, `source_url`, `created_time`, `updated_time`, `markup_language` (1=Markdown, 2=HTML)

### Notebook fields
`id`, `title`, `parent_id`, `created_time`, `updated_time`

### Tag fields
`id`, `title`, `created_time`, `updated_time`

### Resource fields
`id`, `title`, `mime`, `filename`, `size`, `created_time`, `updated_time`

## Error Handling

- **403**: Invalid or missing token — check `$JOPLIN_TOKEN`
- **404**: Item not found — verify the ID
- **Connection refused**: Joplin is not running or Web Clipper is disabled. Instruct user to enable it in Joplin: Tools → Options → Web Clipper → Enable Web Clipper Service.

## API Reference

See [api-reference.md](./api-reference.md) for the full endpoint reference.