# Joplin Manage Resources

> Upload, download, list, and manage attachments and resources in Joplin

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

---


# Joplin Manage Resources

This skill manages resources (file attachments) in Joplin via the REST API.

## Configuration

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

## List All Resources

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/resources?token=$JOPLIN_TOKEN&fields=id,title,mime,filename,size&order_by=updated_time&order_dir=DESC&limit=50"
```

### Pagination

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

## Get Resource Metadata

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/resources/RESOURCE_ID?token=$JOPLIN_TOKEN&fields=id,title,mime,filename,size,created_time,updated_time"
```

## Download a Resource File

```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/resources/RESOURCE_ID/file?token=$JOPLIN_TOKEN" -o OUTPUT_PATH
```

Example:
```bash
curl -s "http://localhost:${JOPLIN_PORT:-41184}/resources/RESOURCE_ID/file?token=$JOPLIN_TOKEN" -o "/tmp/downloaded_file.pdf"
```

## Upload a Resource

```bash
curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/resources?token=$JOPLIN_TOKEN" \
  -F "data=@/path/to/file" \
  -F 'props={"title":"My File Title"}'
```

### Upload with explicit filename and MIME type

```bash
curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/resources?token=$JOPLIN_TOKEN" \
  -F "data=@/path/to/file;type=application/pdf;filename=document.pdf" \
  -F 'props={"title":"Document Title","filename":"document.pdf"}'
```

### Upload response

The response returns the resource metadata including its `id`:
```json
{
  "id": "abc123...",
  "title": "My File Title",
  "mime": "application/pdf",
  "filename": "document.pdf",
  "size": 12345
}
```

## Link a Resource in a Note

After uploading, use the resource ID to embed it in a note's body:

- **Image**: `![description](:/${resource_id})`
- **File/attachment**: `[filename](:/${resource_id})`

Example — create a note with an attached image:
```bash
# 1. Upload the image
RESPONSE=$(curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/resources?token=$JOPLIN_TOKEN" \
  -F "data=@/path/to/photo.jpg" \
  -F 'props={"title":"Photo"}')

RESOURCE_ID=$(echo "$RESPONSE" | jq -r '.id')

# 2. Create a note referencing the image
curl -s -X POST "http://localhost:${JOPLIN_PORT:-41184}/notes?token=$JOPLIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg title "Note with Photo" --arg body "Here is the photo:\n\n![](:/${RESOURCE_ID})" '{title: $title, body: $body}')"
```

## Update Resource Metadata

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

## Delete a Resource

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

**Warning**: This permanently deletes the file. Any note references to this resource will break (show as missing attachment). Confirm with the user before deleting.

## List Resources Attached to a Note

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

## Workflow

1. For uploads: verify the source file exists, upload it, return the resource ID and markdown link syntax.
2. For downloads: get the resource metadata first to determine filename/type, then download.
3. For listing: show resources with title, filename, type, and size.
4. Confirm before deleting resources (destructive operation).
5. When attaching to notes, provide the correct markdown link syntax.

## Error Handling

- **403**: Invalid token
- **404**: Resource not found — verify the ID
- **413**: File too large
- **Connection refused**: Joplin not running

## Size Display Helper

Format file sizes for display:
- < 1 KB: show bytes
- < 1 MB: show KB
- < 1 GB: show MB
- >= 1 GB: show GB