/raindrop-api

name: raindrop-api
description: >
  This skill provides comprehensive instructions for interacting with the Raindrop.io bookmarks service
  via its REST API using curl and jq. It covers authentication, CRUD operations for collections, raindrops
  (bookmarks), tags, highlights, filters, import/export, and backups. Use this skill whenever the user asks
  to work with their bookmarks from Raindrop.io, including reading, creating, updating, deleting, searching,
  or organising bookmarks and collections.

Raindrop.io API Skill

This skill enables interaction with the Raindrop.io bookmarks service through its REST API. Use `curl` and `jq` for direct REST calls.

**Official API documentation**: https://developer.raindrop.io/

Authentication

Token Resolution

Resolve the API token in this order:

1. Check environment variable `RAINDROP_TOKEN` 2. Check if the user has provided a token in the conversation context 3. If neither is available, use AskUserQuestion to request the token from the user

To verify a token exists in the environment:

[ -n "$RAINDROP_TOKEN" ] && echo "Token available" || echo "Token not set"

**Quick setup**: For personal use or development, generate a test token at https://app.raindrop.io/settings/integrations — open your app and copy the "Test token". Test tokens do not expire.

For full OAuth2 flow details, see the [Authentication](#authentication-oauth2-flow) section below.

Making Authenticated Requests

All requests require the Authorization header with Bearer token:

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/ENDPOINT"

For POST/PUT requests with JSON body:

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  "https://api.raindrop.io/rest/v1/ENDPOINT"

Verifying Authentication

Test the token by retrieving the current user:

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/user" | jq '.user.fullName'

Base URL and Conventions

• **Base URL**: `https://api.raindrop.io/rest/v1/`
• **Data Format**: JSON for all request/response bodies
• **Timestamps**: ISO 8601 format
• **Rate Limit**: 120 requests per minute per authenticated user
• **CORS**: Supported for browser-based apps

Confirmation Requirement

**Before executing any destructive action (DELETE, bulk update, move to trash), always ask the user for confirmation using AskUserQuestion.** A single confirmation suffices for a logical group of related actions.

Destructive actions include:

• Deleting raindrops, collections, or tags
• Bulk updating or moving raindrops
• Merging or removing tags
• Removing collaborators from shared collections
• Clearing trash

Read-only operations (GET requests) do not require confirmation.

Endpoints Reference

Raindrops (Bookmarks)

Docs: https://developer.raindrop.io/v1/raindrops

Single Raindrop Operations

| Operation | Method | Endpoint | |-----------|--------|----------| | Get raindrop | GET | `/raindrop/{id}` | | Create raindrop | POST | `/raindrop` | | Update raindrop | PUT | `/raindrop/{id}` | | Remove raindrop | DELETE | `/raindrop/{id}` | | Upload file | PUT | `/raindrop/file` | | Upload cover | PUT | `/raindrop/{id}/cover` | | Get permanent copy | GET | `/raindrop/{id}/cache` | | Suggest (new URL) | POST | `/raindrop/suggest` | | Suggest (existing) | GET | `/raindrop/{id}/suggest` |

Docs: https://developer.raindrop.io/v1/raindrops/single

**Raindrop creation/update fields:**

• `link` (string, required for creation) - Bookmark URL
• `title` (string) - Bookmark title
• `excerpt` (string) - Short description
• `note` (string) - User notes (supports Markdown)
• `tags` (array of strings) - Tag names
• `collection` (object) - `{"$id": collectionId}`
• `type` (string) - `link`, `article`, `image`, `video`, `document`, `audio`
• `important` (boolean) - Mark as favourite
• `order` (number) - Sort order (ascending)
• `media` (array) - Media/thumbnail info
• `highlights` (array) - Text highlights
• `cover` (string) - Cover image URL, or `<screenshot>` for auto-capture
• `pleaseParse` (object) - `{}` to trigger background metadata parsing
• `created` (string) - ISO 8601 creation date
• `lastUpdate` (string) - ISO 8601 last update date
• `reminder` (object) - Reminder settings

**Deletion behaviour**: Removing a raindrop moves it to Trash (collection ID `-99`). Removing from Trash deletes permanently.

Multiple Raindrop Operations

| Operation | Method | Endpoint | |-----------|--------|----------| | Get raindrops | GET | `/raindrops/{collectionId}` | | Create multiple | POST | `/raindrops` | | Update multiple | PUT | `/raindrops/{collectionId}` | | Remove multiple | DELETE | `/raindrops/{collectionId}` | | Export | GET | `/raindrops/{collectionId}/export.{format}` |

Docs: https://developer.raindrop.io/v1/raindrops/multiple

**collectionId values:**

• `0` - All raindrops
• `-1` - Unsorted
• `-99` - Trash
• Any positive integer - Specific collection

**Query parameters for GET /raindrops/{collectionId}:**

• `sort` - Sort order: `-created` (default), `created`, `score`, `-sort`, `title`, `-title`, `domain`, `-domain`
• `perpage` - Results per page (max 50)
• `page` - Page number (0-indexed)
• `search` - Search query (see `references/search-operators.md`)
• `nested` - Boolean, include child collection bookmarks

**Bulk update fields** (PUT with `ids` array or `search` query):

• `important` (boolean)
• `tags` (array) - Appends tags; empty array clears all
• `media` (array) - Appends; empty array clears
• `cover` (string) - URL or `<screenshot>`
• `collection` (object) - `{"$id": collectionId}` to move

**Export formats**: `csv`, `html`, `zip`

Collections

Docs: https://developer.raindrop.io/v1/collections

| Operation | Method | Endpoint | |-----------|--------|----------| | List root collections | GET | `/collections` | | List