raindrop-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Raindrop.io API Skill

Raindrop.io API 使用指南

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/

本技能支持通过REST API与Raindrop.io书签服务进行交互，使用

curl

和

jq

直接调用REST接口。

官方API文档：https://developer.raindrop.io/

Authentication

身份验证

Token Resolution

Token 获取优先级

Resolve the API token in this order:

Check environment variable
```
RAINDROP_TOKEN
```
Check if the user has provided a token in the conversation context
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 section below.

按以下顺序获取API Token：

检查环境变量
```
RAINDROP_TOKEN
```
检查对话上下文是否有用户提供的Token
若以上都没有，使用AskUserQuestion向用户请求Token

验证环境中是否存在Token：

bash

[ -n "$RAINDROP_TOKEN" ] && echo "Token available" || echo "Token not set"

快速设置：个人使用或开发时，可在https://app.raindrop.io/settings/integrations生成测试Token——打开应用并复制「Test token」。测试Token不会过期。

完整OAuth2流程详情，请查看下方的身份验证：OAuth2流程章节。

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"

所有请求都需要携带包含Bearer Token的Authorization头：

bash

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

对于带JSON请求体的POST/PUT请求：

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'

通过获取当前用户信息来测试Token有效性：

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/user" | jq '.user.fullName'

Base URL and Conventions

基础URL与约定

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

基础URL：
```
https://api.raindrop.io/rest/v1/
```
数据格式：所有请求/响应体均为JSON格式
时间戳：ISO 8601格式
请求限制：每个已认证用户每分钟最多120次请求
CORS：支持基于浏览器的应用

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.

在执行任何破坏性操作（DELETE、批量更新、移至回收站）前，必须使用AskUserQuestion征得用户确认。 一组相关的逻辑操作只需一次确认即可。

破坏性操作包括：

删除雨滴、集合或标签
批量更新或移动雨滴
合并或移除标签
从共享集合中移除协作者
清空回收站

只读操作（GET请求）无需确认。

Endpoints Reference

端点参考

Raindrops (Bookmarks)

雨滴（书签）

Docs: https://developer.raindrop.io/v1/raindrops

文档：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.

操作	请求方法	端点
获取雨滴	GET	`/raindrop/{id}`
创建雨滴	POST	`/raindrop`
更新雨滴	PUT	`/raindrop/{id}`
删除雨滴	DELETE	`/raindrop/{id}`
上传文件	PUT	`/raindrop/file`
上传封面	PUT	`/raindrop/{id}/cover`
获取永久副本	GET	`/raindrop/{id}/cache`
推荐（新URL）	POST	`/raindrop/suggest`
推荐（已有）	GET	`/raindrop/{id}/suggest`

文档：https://developer.raindrop.io/v1/raindrops/single

雨滴创建/更新字段：

```
link
```
（字符串，创建时必填）- 书签URL
```
title
```
（字符串）- 书签标题
```
excerpt
```
（字符串）- 简短描述
```
note
```
（字符串）- 用户备注（支持Markdown）
```
tags
```
（字符串数组）- 标签名称
```
collection
```
（对象）-
```
{"$id": collectionId}
```
```
type
```
（字符串）-
```
link
```
,
```
article
```
,
```
image
```
,
```
video
```
,
```
document
```
,
```
audio
```
```
important
```
（布尔值）- 标记为收藏
```
order
```
（数字）- 排序顺序（升序）
```
media
```
（数组）- 媒体/缩略图信息
```
highlights
```
（数组）- 文本高亮
```
cover
```
（字符串）- 封面图片URL，或
```
<screenshot>
```
自动捕获
```
pleaseParse
```
（对象）-
```
{}
```
触发后台元数据解析
```
created
```
（字符串）- ISO 8601格式创建日期
```
lastUpdate
```
（字符串）- ISO 8601格式最后更新日期
```
reminder
```
（对象）- 提醒设置

删除行为：删除雨滴会将其移至回收站（集合ID

-99

）。从回收站删除则会永久删除。

Multiple Raindrop Operations

多个雨滴操作

Operation	Method	Endpoint
Get raindrops	GET	`/raindrops/{collectionId}`
Create multiple	POST	`/raindrops`
Update multiple	PUT	`/raindrops/{collectionId}`
Remove multiple	DELETE	`/raindrops/{collectionId}`
Export	GET	`/raindrops/{collectionId}/export.{format}`

Docs: https://developer.raindrop.io/v1/raindrops/multiple

collectionId values:

```
0
```
- All raindrops
```
-1
```
- Unsorted
```
-99
```
- Trash
Any positive integer - Specific collection

Query parameters for GET /raindrops/{collectionId}:

sort

- Sort order:

-created

(default),

created

score

-sort

title

-title

domain

-domain

```
perpage
```
- Results per page (max 50)
```
page
```
- Page number (0-indexed)
```
search
```
- Search query (see
```
references/search-operators.md
```
)
```
nested
```
- Boolean, include child collection bookmarks

Bulk update fields (PUT with

ids

array or

search

query):

```
important
```
(boolean)
```
tags
```
(array) - Appends tags; empty array clears all
```
media
```
(array) - Appends; empty array clears
```
cover
```
(string) - URL or
```
<screenshot>
```
```
collection
```
(object) -
```
{"$id": collectionId}
```
to move

Export formats:

csv

html

zip

操作	请求方法	端点
获取多个雨滴	GET	`/raindrops/{collectionId}`
批量创建	POST	`/raindrops`
批量更新	PUT	`/raindrops/{collectionId}`
批量删除	DELETE	`/raindrops/{collectionId}`
导出	GET	`/raindrops/{collectionId}/export.{format}`

文档：https://developer.raindrop.io/v1/raindrops/multiple

collectionId取值：

```
0
```
- 所有雨滴
```
-1
```
- 未分类
```
-99
```
- 回收站
任意正整数 - 指定集合

GET /raindrops/{collectionId}的查询参数：

sort

- 排序方式：

-created

（默认）、

created

、

score

、

-sort

、

title

、

-title

、

domain

、

-domain

```
perpage
```
- 每页结果数（最大50）
```
page
```
- 页码（从0开始）
```
search
```
- 搜索查询（详见
```
references/search-operators.md
```
）
```
nested
```
- 布尔值，是否包含子集合书签

批量更新字段（PUT请求需携带

ids

数组或

search

查询）：

```
important
```
（布尔值）
```
tags
```
（数组）- 追加标签；空数组清空所有标签
```
media
```
（数组）- 追加媒体；空数组清空
```
cover
```
（字符串）- URL或
```
<screenshot>
```
```
collection
```
（对象）-
```
{"$id": collectionId}
```
用于移动雨滴

导出格式：

csv

html

zip

Collections

集合

Docs: https://developer.raindrop.io/v1/collections

Operation	Method	Endpoint
List root collections	GET	`/collections`
List child collections	GET	`/collections/childrens`
Get collection	GET	`/collection/{id}`
Create collection	POST	`/collection`
Update collection	PUT	`/collection/{id}`
Upload cover	PUT	`/collection/{id}/cover`
Delete collection	DELETE	`/collection/{id}`
Delete multiple	DELETE	`/collections`
Reorder/expand all	PUT	`/collections`
Merge collections	PUT	`/collections/merge`
Remove empty	PUT	`/collections/clean`
Empty trash	DELETE	`/collection/-99`
System collection counts	GET	`/user/stats`
Search covers/icons	GET	`/collections/covers/{text}`
Featured covers	GET	`/collections/covers`

Docs: https://developer.raindrop.io/v1/collections/methods

Collection fields:

```
title
```
(string) - Collection name
```
view
```
(string) - Display style:
```
list
```
,
```
simple
```
,
```
grid
```
,
```
masonry
```
```
public
```
(boolean) - Public accessibility
```
parent
```
(object) -
```
{"$id": parentCollectionId}
```
for nesting
```
sort
```
(number) - Sort position
```
cover
```
(array) - Cover image URLs
```
expanded
```
(boolean) - Whether subcollections are expanded
```
color
```
(string) - Collection colour

System collections (non-removable):

ID
```
-1
```
- "Unsorted"
ID
```
-99
```
- "Trash"

Access levels (

access.level

```
1
```
- Read only
```
2
```
- Collaborator (write)
```
3
```
- Collaborator (write + manage)
```
4
```
- Owner

For sharing/collaborators, see

references/collections-sharing.md

文档：https://developer.raindrop.io/v1/collections

操作	请求方法	端点
列出根集合	GET	`/collections`
列出子集合	GET	`/collections/childrens`
获取集合	GET	`/collection/{id}`
创建集合	POST	`/collection`
更新集合	PUT	`/collection/{id}`
上传封面	PUT	`/collection/{id}/cover`
删除集合	DELETE	`/collection/{id}`
批量删除	DELETE	`/collections`
重新排序/展开所有	PUT	`/collections`
合并集合	PUT	`/collections/merge`
移除空集合	PUT	`/collections/clean`
清空回收站	DELETE	`/collection/-99`
系统集合统计	GET	`/user/stats`
搜索封面/图标	GET	`/collections/covers/{text}`
精选封面	GET	`/collections/covers`

文档：https://developer.raindrop.io/v1/collections/methods

集合字段：

```
title
```
（字符串）- 集合名称
```
view
```
（字符串）- 显示样式：
```
list
```
,
```
simple
```
,
```
grid
```
,
```
masonry
```
```
public
```
（布尔值）- 是否公开访问
```
parent
```
（对象）-
```
{"$id": parentCollectionId}
```
用于嵌套
```
sort
```
（数字）- 排序位置
```
cover
```
（数组）- 封面图片URL
```
expanded
```
（布尔值）- 是否展开子集合
```
color
```
（字符串）- 集合颜色

系统集合（不可删除）：

ID
```
-1
```
- 「未分类」
ID
```
-99
```
- 「回收站」

访问级别（

access.level

）：

```
1
```
- 只读
```
2
```
- 协作者（可编辑）
```
3
```
- 协作者（可编辑+管理）
```
4
```
- 所有者

关于共享/协作者的详情，请查看

references/collections-sharing.md

。

Operation	Method	Endpoint
Get tags	GET	`/tags/{collectionId}`
Rename tag	PUT	`/tags/{collectionId}`
Merge tags	PUT	`/tags/{collectionId}`
Remove tag(s)	DELETE	`/tags/{collectionId}`

操作	请求方法	端点
获取标签	GET	`/tags/{collectionId}`
重命名标签	PUT	`/tags/{collectionId}`
合并标签	PUT	`/tags/{collectionId}`
移除标签	DELETE	`/tags/{collectionId}`

Highlights

高亮

Docs: https://developer.raindrop.io/v1/highlights

Operation	Method	Endpoint
Get all highlights	GET	`/highlights`
Get collection highlights	GET	`/highlights/{collectionId}`
Get raindrop highlights	GET	`/raindrop/{id}`
Add highlight	PUT	`/raindrop/{id}`
Update highlight	PUT	`/raindrop/{id}`
Delete highlight	PUT	`/raindrop/{id}`

For details, see

references/highlights.md

文档：https://developer.raindrop.io/v1/highlights

操作	请求方法	端点
获取所有高亮	GET	`/highlights`
获取集合高亮	GET	`/highlights/{collectionId}`
获取雨滴高亮	GET	`/raindrop/{id}`
添加高亮	PUT	`/raindrop/{id}`
更新高亮	PUT	`/raindrop/{id}`
删除高亮	PUT	`/raindrop/{id}`

详情请查看

references/highlights.md

。

Filters

筛选

Docs: https://developer.raindrop.io/v1/filters

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/filters/{collectionId}" | jq '.'

Use

for all collections. Returns aggregated counts for broken links, duplicates, favourites, untagged items, tags, and content types.

Query parameters:

```
tagsSort
```
-
```
-count
```
(default) or
```
_id
```
(alphabetical)
```
search
```
- Additional search filter

文档：https://developer.raindrop.io/v1/filters

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/filters/{collectionId}" | jq '.'

使用

表示所有集合。返回失效链接、重复项、收藏、未标记项、标签及内容类型的聚合统计。

查询参数：

```
tagsSort
```
-
```
-count
```
（默认）或
```
_id
```
（按字母顺序）
```
search
```
- 额外的搜索筛选条件

User

用户

Docs: https://developer.raindrop.io/v1/user

Operation	Method	Endpoint
Get current user	GET	`/user`
Update user	PUT	`/user`

文档：https://developer.raindrop.io/v1/user

操作	请求方法	端点
获取当前用户	GET	`/user`
更新用户信息	PUT	`/user`

Import

导入

Docs: https://developer.raindrop.io/v1/import

Operation	Method	Endpoint
Parse URL	GET	`/import/url/parse?url={url}`
Check URL existence	POST	`/import/url/exists`
Parse HTML bookmark file	POST	`/import/file`

文档：https://developer.raindrop.io/v1/import

操作	请求方法	端点
解析URL	GET	`/import/url/parse?url={url}`
检查URL是否已存在	POST	`/import/url/exists`
解析HTML书签文件	POST	`/import/file`

Backups

备份

Docs: https://developer.raindrop.io/v1/backups

Operation	Method	Endpoint
List backups	GET	`/backups`
Download backup	GET	`/backup/{id}.{format}`
Generate new backup	GET	`/backup`

Formats:

html

csv

文档：https://developer.raindrop.io/v1/backups

操作	请求方法	端点
列出备份	GET	`/backups`
下载备份	GET	`/backup/{id}.{format}`
生成新备份	GET	`/backup`

格式：

html

或

csv

Authentication: OAuth2 Flow

身份验证：OAuth2流程

Docs: https://developer.raindrop.io/v1/authentication/token

For apps accessing other users' data (not personal use), use the full OAuth2 flow:

文档：https://developer.raindrop.io/v1/authentication/token

对于需要访问其他用户数据的应用（非个人使用），请使用完整的OAuth2流程：

Step 1: Authorise

步骤1：授权

Direct users to:

https://raindrop.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code

引导用户访问：

https://raindrop.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code

Step 2: Exchange Code for Token

步骤2：用授权码交换Token

bash

curl -s -X POST "https://raindrop.io/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTH_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI",
    "grant_type": "authorization_code"
  }' | jq '.'

Response:

json

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 1209599,
  "token_type": "Bearer"
}

bash

curl -s -X POST "https://raindrop.io/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTH_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI",
    "grant_type": "authorization_code"
  }' | jq '.'

响应示例：

json

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 1209599,
  "token_type": "Bearer"
}

Step 3: Refresh Token

步骤3：刷新Token

Access tokens expire after two weeks. Refresh with:

bash

curl -s -X POST "https://raindrop.io/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "grant_type": "refresh_token"
  }' | jq '.'

访问令牌两周后过期，可通过以下方式刷新：

bash

curl -s -X POST "https://raindrop.io/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "grant_type": "refresh_token"
  }' | jq '.'

Error Handling

错误处理

Check HTTP status codes:

```
200
```
- Success
```
204
```
- Success, no content
```
400
```
- Bad request
```
401
```
- Authentication failed (check token)
```
403
```
- Forbidden (insufficient permissions)
```
404
```
- Resource not found
```
429
```
- Rate limited (120 req/min exceeded)
```
5xx
```
- Server error

检查HTTP状态码：

```
200
```
- 成功
```
204
```
- 成功，无返回内容
```
400
```
- 请求错误
```
401
```
- 身份验证失败（检查Token）
```
403
```
- 禁止访问（权限不足）
```
404
```
- 资源不存在
```
429
```
- 请求超限（超过每分钟120次限制）
```
5xx
```
- 服务器错误

Example with Error Handling

带错误处理的示例

bash

response=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/0")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
  echo "$body" | jq '.'
else
  echo "Error: HTTP $http_code"
  echo "$body"
fi

bash

response=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/0")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
  echo "$body" | jq '.'
else
  echo "Error: HTTP $http_code"
  echo "$body"
fi

Common Patterns

常见用法

List All Bookmarks in a Collection

列出集合中的所有书签

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/COLLECTION_ID?perpage=50" | jq '.items[] | {title, link}'

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/COLLECTION_ID?perpage=50" | jq '.items[] | {title, link}'

Create a Bookmark

创建书签

bash

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://example.com",
    "title": "Example Site",
    "tags": ["reference", "example"],
    "collection": {"$id": COLLECTION_ID},
    "pleaseParse": {}
  }' \
  "https://api.raindrop.io/rest/v1/raindrop" | jq '.'

bash

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://example.com",
    "title": "Example Site",
    "tags": ["reference", "example"],
    "collection": {"$id": COLLECTION_ID},
    "pleaseParse": {}
  }' \
  "https://api.raindrop.io/rest/v1/raindrop" | jq '.'

Search Bookmarks

搜索书签

bash

undefined

bash

undefined

Search across all collections

搜索所有集合

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/raindrops/0?search=YOUR_QUERY" | jq '.items[] | {title, link}'

Search with tag filter

按标签筛选搜索

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/raindrops/0?search=%23tagname" | jq '.items[] | {title, link}'


See `references/search-operators.md` for the complete search query syntax.

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/raindrops/0?search=%23tagname" | jq '.items[] | {title, link}'


完整的搜索查询语法请查看`references/search-operators.md`。

Move Bookmark to a Collection

移动书签到指定集合

bash

curl -s -X PUT \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"collection": {"$id": TARGET_COLLECTION_ID}}' \
  "https://api.raindrop.io/rest/v1/raindrop/RAINDROP_ID" | jq '.'

bash

curl -s -X PUT \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"collection": {"$id": TARGET_COLLECTION_ID}}' \
  "https://api.raindrop.io/rest/v1/raindrop/RAINDROP_ID" | jq '.'

Get All Tags

获取所有标签

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/tags/0" | jq '.items[] | {tag: ._id, count}'

bash

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/tags/0" | jq '.items[] | {tag: ._id, count}'

Create a Collection

创建集合

bash

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Collection", "view": "list"}' \
  "https://api.raindrop.io/rest/v1/collection" | jq '.'

bash

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Collection", "view": "list"}' \
  "https://api.raindrop.io/rest/v1/collection" | jq '.'

List All Collections (Root + Children)

列出所有集合（根集合+子集合）

bash

undefined

bash

undefined

Root collections

根集合

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/collections" | jq '.items[] | {id: ._id, title}'

Child collections

子集合

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/collections/childrens" | jq '.items[] | {id: ._id, title, parent: .parent."$id"}'

undefined

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/collections/childrens" | jq '.items[] | {id: ._id, title, parent: .parent."$id"}'

undefined

Paginate Through All Bookmarks

分页遍历所有书签

bash

page=0
while true; do
  response=$(curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
    "https://api.raindrop.io/rest/v1/raindrops/0?perpage=50&page=$page")

  count=$(echo "$response" | jq '.items | length')
  echo "$response" | jq '.items[] | {title, link}'

  if [ "$count" -lt 50 ]; then
    break
  fi
  page=$((page + 1))
done

bash

page=0
while true; do
  response=$(curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
    "https://api.raindrop.io/rest/v1/raindrops/0?perpage=50&page=$page")

  count=$(echo "$response" | jq '.items | length')
  echo "$response" | jq '.items[] | {title, link}'

  if [ "$count" -lt 50 ]; then
    break
  fi
  page=$((page + 1))
done

Export Bookmarks

导出书签

bash

undefined

bash

undefined

Export all bookmarks as CSV

导出所有书签为CSV

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/raindrops/0/export.csv" -o bookmarks.csv

Export as HTML

导出为HTML

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/raindrops/0/export.html" -o bookmarks.html

undefined

curl -s -H "Authorization: Bearer $RAINDROP_TOKEN"
"https://api.raindrop.io/rest/v1/raindrops/0/export.html" -o bookmarks.html

undefined

Check if URL Already Saved

检查URL是否已保存

bash

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com"]}' \
  "https://api.raindrop.io/rest/v1/import/url/exists" | jq '.'

bash

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com"]}' \
  "https://api.raindrop.io/rest/v1/import/url/exists" | jq '.'

Pagination

分页

Raindrop uses page-based pagination (not cursor-based):

```
page
```
- Page number (0-indexed)
```
perpage
```
- Items per page (max 50, default 25 for highlights)

When the number of items returned is less than

perpage

, you have reached the last page.

Raindrop使用基于页码的分页（而非游标分页）：

```
page
```
- 页码（从0开始）
```
perpage
```
- 每页条目数（最大50，高亮默认25）

当返回的条目数少于

perpage

时，说明已到达最后一页。

Nested Collection Structure

嵌套集合结构

Collections are organised hierarchically. Reconstructing the full sidebar requires:

```
GET /user
```
- Returns
```
groups
```
array with collection ordering
```
GET /collections
```
- Root collections
```
GET /collections/childrens
```
- Nested collections

Root collection sort order is persisted in the user's

groups[].collections

array. Child collection sort order is stored in the collection's

sort

field.

集合采用层级结构组织。重建完整侧边栏需要：

```
GET /user
```
- 返回包含集合排序信息的
```
groups
```
数组
```
GET /collections
```
- 获取根集合
```
GET /collections/childrens
```
- 获取嵌套集合

根集合的排序顺序保存在用户的

groups[].collections

数组中。子集合的排序顺序存储在集合的

sort

字段中。

Additional Reference

额外参考

For detailed documentation on specific topics, consult:

```
references/search-operators.md
```
- Search query syntax and operators
```
references/collections-sharing.md
```
- Collection sharing and collaborators
```
references/highlights.md
```
- Highlight management

关于特定主题的详细文档，请参考：

```
references/search-operators.md
```
- 搜索查询语法与运算符
```
references/collections-sharing.md
```
- 集合共享与协作者
```
references/highlights.md
```
- 高亮管理

Workflow Summary

工作流程总结

Resolve token - Environment, context, or ask user
Verify authentication - Test with
```
GET /user
```
Read operations - Execute directly without confirmation
Write operations - Ask for confirmation before executing
Handle pagination - Loop with page number until items < perpage
Parse responses - Use jq to extract and format data

获取Token - 优先从环境变量、上下文获取，否则询问用户
验证身份 - 调用
```
GET /user
```
测试
只读操作 - 直接执行无需确认
写入操作 - 执行前需征得用户确认
处理分页 - 循环递增页码，直到返回条目数小于每页限制
解析响应 - 使用jq提取并格式化数据