Raindrop.io API Skill

Manage bookmarks via Raindrop.io REST API.

Prerequisites

User must have RAINDROP_TOKEN env var set. If not configured, instruct them to:

Create app at https://app.raindrop.io/settings/integrations
Generate test token
Add export RAINDROP_TOKEN="..." to ~/.zshrc.local

Authentication

All requests require:

Authorization: Bearer $RAINDROP_TOKEN

Base URL

https://api.raindrop.io/rest/v1/

Helper Script

Use scripts/raindrop.sh for API calls:

./scripts/raindrop.sh GET /collections
./scripts/raindrop.sh POST /raindrop '{"link":"https://example.com","pleaseParse":{}}'
./scripts/raindrop.sh PUT /raindrop/123 '{"tags":["new-tag"]}'
./scripts/raindrop.sh DELETE /raindrop/123

Quick Reference

Collections

Action	Method	Endpoint
List root	GET	`/collections`
List children	GET	`/collections/childrens`
Get one	GET	`/collection/{id}`
Create	POST	`/collection`
Update	PUT	`/collection/{id}`
Delete	DELETE	`/collection/{id}`

Raindrops (Bookmarks)

Action	Method	Endpoint
List	GET	`/raindrops/{collectionId}`
Get one	GET	`/raindrop/{id}`
Create	POST	`/raindrop`
Update	PUT	`/raindrop/{id}`
Delete	DELETE	`/raindrop/{id}`
Search	GET	`/raindrops/0?search=...`

Special collection IDs: 0 = all, -1 = unsorted, -99 = trash

Action	Method	Endpoint
List all	GET	`/tags`
List in collection	GET	`/tags/{collectionId}`
Rename	PUT	`/tags/{collectionId}`
Delete	DELETE	`/tags/{collectionId}`

Highlights

Action	Method	Endpoint
List all	GET	`/highlights`
In collection	GET	`/highlights/{collectionId}`
Add/Update/Remove	PUT	`/raindrop/{id}`

Colors: blue, brown, cyan, gray, green, indigo, orange, pink, purple, red, teal, yellow

Common Operations

Create bookmark with auto-parse

./scripts/raindrop.sh POST /raindrop '{
  "link": "https://example.com",
  "collection": {"$id": 12345},
  "tags": ["tag1", "tag2"],
  "pleaseParse": {}
}'

Search bookmarks

./scripts/raindrop.sh GET '/raindrops/0?search=keyword&sort=-created'

Search operators:

#tag - by tag
type:article - by type (link, article, image, video, document, audio)
domain:example.com - by domain
created:>2024-01-01 - by date
important:true - favorites only

Create collection

./scripts/raindrop.sh POST /collection '{
  "title": "My Collection",
  "public": false
}'

Add highlight to bookmark

./scripts/raindrop.sh PUT /raindrop/123 '{
  "highlights": [{"text": "highlighted text", "color": "yellow", "note": "my note"}]
}'

Bulk tag bookmarks

./scripts/raindrop.sh PUT /raindrops/0 '{
  "ids": [1, 2, 3],
  "tags": ["new-tag"]
}'

Export collection

curl -s "https://api.raindrop.io/rest/v1/raindrops/{collectionId}/export.csv" \
  -H "Authorization: Bearer $RAINDROP_TOKEN" > bookmarks.csv

Formats: csv, html, zip

Rate Limits

120 requests/minute. Check headers: X-RateLimit-Limit, RateLimit-Remaining, X-RateLimit-Reset

Detailed Reference

See references/API-REFERENCE.md for complete endpoint documentation.

raindrop