Raindrop.io API

Build, debug, and explain integrations with Raindrop.io, including OAuth 2 authorization, bearer-token REST API calls, collections and raindrops CRUD flows,...

Security Scan

Instruction-only Raindrop.io integration helper that is internally consistent with its stated purpose and requests no installs or pre-declared credentials; it may ask the user for OAuth tokens when making live API calls.

Purpose & Capability

The name and description (Raindrop.io API, OAuth, REST/MCP flows) match the SKILL.md and reference file. All described actions (collections, raindrops, tags, import/export, MCP) are documented and expected for this skill.

Instruction Scope

SKILL.md provides detailed, scoped runtime instructions for choosing endpoints, auth flows, rate-limit handling, and when to ask the user for credentials. It does instruct the agent to request client credentials or bearer tokens from the user for live calls — expected for an API helper, but users should be aware they'll be asked to provide secrets if they want live requests.

Install Mechanism

No install spec and no code files that execute on disk; the skill is instruction-only, which is the lowest install risk.

Credentials

The skill declares no required environment variables or primary credential. The instructions say to use existing environment tokens if present or ask the user for credentials. That is proportionate to an API helper, but the skill may read/use tokens found in the environment even though none are declared — users should be aware of that behavior.

Persistence & Privilege

always is false and there are no install hooks or persistent privileges requested. The skill can be invoked by the agent normally; no elevated or persistent system privileges are requested.

Assessment

This skill is an instruction-only Raindrop.io API helper and appears coherent with its description. It will not install software, but to perform live API calls it will ask for OAuth client credentials or a bearer token (or use one already present in the environment). Before proceeding: only provide tokens/credentials you control and are comfortable sharing, prefer test tokens or least-privilege scopes, and be ready to revoke tokens after use. If you do not want to share secrets, ask the agent to produce example requests or mock responses instead of making live calls. Because the skill can use any token it finds in the environment, consider running it in a session that does not contain other sensitive credentials.

Overview

Use this skill to work against the official Raindrop.io developer platform at https://developer.raindrop.io/. Prefer the documented REST API v1 for application logic and the MCP server for AI-client integrations.

Workflow

1. Decide whether the task belongs to the REST API or the MCP server.
2. Choose an authentication path before writing requests.
3. Map the user task to the smallest relevant endpoint group.
4. Preserve Raindrop.io-specific constraints such as rate limits, collection tree reconstruction, and usage terms.

Choose The Surface

• Use REST API v1 when building scripts, backends, browser clients, importers, exporters, or bookmark-management features.
• Use the MCP server when connecting an AI client or agent directly to Raindrop.io bookmark data.
• Do not conflate them:
  • REST base: https://api.raindrop.io/rest/v1
  • MCP endpoint: https://api.raindrop.io/rest/v2/ai/mcp

Authentication

• For quick personal testing, prefer the app console's test token if the user only needs access to their own data.
• For external applications, use the OAuth 2 authorization-code flow documented in references/raindrop-reference.md.
• For authenticated REST calls, send Authorization: Bearer <access_token>.
• For MCP clients, prefer interactive OAuth 2.1 when the client supports it. Bearer tokens also work.
• Ask the user for client credentials or a token if they want live API calls and those secrets are not already present in the environment.

Endpoint Mapping

• Collections:
  • Use collection methods for list, get, create, update, delete, reorder, expand, empty, merge, and remove-many actions.
  • Read the nested-structure section before recreating a sidebar tree. The docs explicitly require multiple calls.
  • Read sharing when inviting collaborators or managing access.
• Raindrops:
  • Use single-raindrop methods for one bookmark at a time.
  • Use multiple-raindrop methods for search, pagination, filters, bulk update, move, and delete.
• Highlights:
  • Use highlight routes for bookmark text highlights and notes.
• User, tags, filters:
  • Use user routes for current-user and public-user data.
  • Use tags routes for list, rename, merge, and delete.
  • Use filters to surface broken links, duplicates, important items, untagged content, and grouped counts.
• Import, export, backups:
  • Use import helpers to parse URLs, check whether URLs already exist, or parse HTML bookmark export files.
  • Use export routes for csv, html, or zip.
  • Use backups routes when the user needs generated backup IDs or downloadable backup files.

Guardrails

• Respect the published usage terms. The docs explicitly forbid building a product that harms, competes with, or replaces Raindrop.io.
• Assume a rate limit of 120 requests per minute per authenticated user for OAuth-based requests unless the live headers indicate otherwise.
• Handle 429 with backoff based on the rate-limit headers.
• Send JSON bodies with Content-Type: application/json.
• Use ISO 8601 timestamps as documented.
• When exact payload fields matter, load references/raindrop-reference.md and follow the relevant section instead of guessing.

Reference File

Load references/raindrop-reference.md when you need endpoint details, auth parameters, route examples, or MCP setup notes.