raindrop-api

Files (4)

• SKILL.md
• collections-sharing.md · references/
• highlights.md · references/
• search-operators.md · references/

SKILL.md (first lines)

# 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:

```bash
[ -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:

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

For POST/PUT requests with JSON body:

```bash
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:

```bash
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

From intellectronica/agent-skills, CC0-1.0.

More from intellectronica/agent-skills