Raindrop.io API

概述

使用本技能对接 Raindrop.io 官方开发者平台：https://developer.raindrop.io/。应用逻辑优先采用已正式文档化的 REST API v1；AI 客户端集成则优先使用 MCP 服务器。

工作流程

1. 判断任务应归属 REST API 还是 MCP 服务器。
2. 在编写请求前，选定认证方式。
3. 将用户需求映射到最小且相关的端点分组。
4. 严格遵守 Raindrop.io 特有的约束条件，包括速率限制、收藏夹树结构重建规则及使用条款。

选择接口面（Surface）

• 构建脚本、后端服务、浏览器客户端、导入器、导出器或书签管理功能时，请使用 REST API v1。
• 当需将 AI 客户端或智能体直接接入 Raindrop.io 的书签数据时，请使用 MCP 服务器。
• 二者不可混用：
  • REST 基础地址：https://api.raindrop.io/rest/v1
  • MCP 端点地址：https://api.raindrop.io/rest/v2/ai/mcp

认证

• 快速个人测试场景下，若用户仅需访问自身数据，优先使用应用控制台（app console）提供的测试令牌（test token）。
• 面向外部应用时，请采用 references/raindrop-reference.md 中所记载的 OAuth 2 授权码（authorization-code）流程。
• 发起已认证的 REST 请求时，须在请求头中携带 Authorization: Bearer 。
• MCP 客户端推荐在支持的前提下使用交互式 OAuth 2.1；Bearer 令牌亦可正常工作。
• 若用户需要执行实时 API 调用，且相关密钥（如 client credentials 或 access_token）尚未存在于当前环境中，则应主动向用户索取。

端点映射

• 收藏夹（Collections）：
  • 对列表查询、获取单个、创建、更新、删除、重排序、展开、清空、合并、批量移除等操作，请使用收藏夹相关方法。
  • 重建侧边栏树状结构前，请务必阅读“嵌套结构”（nested-structure）章节——文档明确要求此类操作需通过多次调用完成。
  • 涉及协作邀请或权限管理时，请查阅共享（sharing）相关接口说明。
• 书签条目（Raindrops）：
  • 单次处理一个书签时，请使用单书签（single-raindrop）方法。
  • 执行搜索、分页、过滤、批量更新、移动或批量删除等操作时，请使用多书签（multiple-raindrop）方法。
• 高亮标注（Highlights）：
  • 处理书签中的文本高亮与备注内容时，请使用高亮（highlight）路由。
• 用户（User）、标签（Tags）、筛选器（Filters）：
  • 获取当前用户或公开用户信息时，请使用用户（user）路由。
  • 执行标签列表查询、重命名、合并或删除等操作时，请使用标签（tags）路由。
  • 识别失效链接、重复项、重要条目、未打标内容，以及按分组统计数量时，请使用筛选器（filters）路由。
• 导入（Import）、导出（Export）、备份（Backups）：
  • 使用导入辅助接口解析 URL、校验 URL 是否已存在，或解析 HTML 格式的书签导出文件。
  • 导出为 csv、html 或 zip 格式时，请使用导出（export）路由。
  • 当用户需要生成备份 ID 或下载备份文件时，请使用备份（backups）路由。

安全守则（Guardrails）

• 严格遵守官方公布的使用条款。文档明确禁止开发任何损害、竞争或替代 Raindrop.io 的产品。
• 除非响应头中另有说明，OAuth 认证请求默认遵循 每分钟每用户 120 次请求 的速率限制。
• 遇到 429 响应时，须依据速率限制响应头（rate-limit headers）实施退避重试策略。
• 发送 JSON 请求体时，必须设置请求头 Content-Type: application/json。
• 时间戳格式须严格采用文档中规定的 ISO 8601 标准。
• 当请求载荷（payload）字段精度至关重要时，请加载并参考 references/raindrop-reference.md 中对应章节，切勿凭猜测构造字段。

参考文件

如需查阅端点详情、认证参数、路由示例或 MCP 配置说明，请加载 references/raindrop-reference.md 文件。