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

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

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

Get Resource Metadata

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

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

Example:

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

Upload a Resource

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

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:

{
  "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:

# 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

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

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

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