raindrop-api_skill

Overview

This skill provides practical, curl + jq recipes and guidance for using the Raindrop.io REST API to manage bookmarks, collections, tags, highlights, filters, imports, and backups. It documents authentication (including quick test token and OAuth2), endpoint conventions, rate limits, and safe patterns for CRUD and bulk operations. Use it to automate, script, or debug interactions with your Raindrop.io account from the command line or CI scripts.

How this skill works

The skill shows how to resolve and send a Bearer token, build authenticated curl requests, and parse JSON responses with jq. It explains individual and bulk endpoints for raindrops, collections, tags, highlights, filters, user, import, and backups, plus common query parameters and export formats. It also includes error handling patterns, pagination loops, and a confirmation rule for destructive actions.

When to use it

• When you want to list, search, export, or back up bookmarks via scripts or cron jobs.
• When creating, updating, deleting, or moving single or multiple raindrops or collections.
• When managing tags (rename, merge, remove) across collections programmatically.
• When importing bookmarks from HTML or parsing URLs before creation.
• When you need to implement OAuth2 for an app that accesses other users' Raindrop accounts.

Best practices

• Resolve the API token from RAINDROP_TOKEN env var, fall back to user-provided token, and prompt if missing.
• Always include Authorization: Bearer $RAINDROP_TOKEN and Content-Type: application/json for body requests.
• Ask for explicit confirmation before any destructive action (DELETE, bulk updates, empty trash).
• Respect the 120 requests/min rate limit; implement retries and backoff on 429 responses.
• Use perpage and page parameters to paginate safely (max 50 per page) and iterate with a loop.

Example use cases

• Backup all bookmarks periodically by exporting collections to html or csv and downloading via /backup endpoints.
• Bulk-add a tag to a filtered set of raindrops using PUT /raindrops/{collectionId} with ids or a search query.
• Automate moving bookmarks into a collection programmatically with PUT /raindrop/{id} and collection {$id}.
• Merge or rename tags across all collections using PUT /tags/0 with replace and tags arrays.
• Import a browser bookmark HTML file using POST /import/file and verify parsed URLs before creation.