raindrop-api

Raindrop.io API スキル

このスキルを使用すると、REST API を通じて Raindrop.io ブックマークサービスを操作できます。直接 REST リクエストを行うには、curl と jq を使用します。

公式 API ドキュメント: https://developer.raindrop.io/

認証

トークンの解決

次の順序で API トークンを解決します。

1. 環境変数 RAINDROP_TOKEN を確認します
2. 会話のコンテキストでユーザーがトークンを提供しているか確認します
3. いずれも利用できない場合は、AskUserQuestion を使用してユーザーにトークンを求めます

環境にトークンが存在することを確認するには、次のコマンドを実行します。

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

簡単なセットアップ: 個人利用や開発用には、https://app.raindrop.io/settings/integrations でテストトークンを生成できます。アプリを開き、「Test token」をコピーしてください。テストトークンは有効期限がありません。

OAuth2 フローの詳細については、以下の認証セクションをご覧ください。

認証済みリクエストの送信

すべてのリクエストには、Bearer トークンを含む Authorization ヘッダーが必要です。

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

JSON ボディを含む POST／PUT リクエストの場合：

curl -s -X POST \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  "https://api.raindrop.io/rest/v1/ENDPOINT"

認証の確認

現在のユーザー情報を取得して、トークンをテストします。

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

ベース URL と規約

• ベース URL: https://api.raindrop.io/rest/v1/
• データ形式: すべてのリクエスト／レスポンスボディで JSON を使用
• タイムスタンプ: ISO 8601 形式
• レート制限: 認証済みユーザーごとに 1 分あたり 120 リクエスト
• CORS: ブラウザベースのアプリでサポートされています

確認要件

破壊的な操作（DELETE、一括更新、ゴミ箱への移動）を実行する前に、必ず AskUserQuestion を使用してユーザーに確認してください。 関連する操作をひとまとまりとして行う場合、確認は 1 回で十分です。

破壊的な操作には、次のものが含まれます。

• raindrop、コレクション、タグの削除
• raindrop の一括更新または移動
• タグの統合または削除
• 共有コレクションからの共同編集者の削除
• ゴミ箱を空にする操作

読み取り専用の操作（GET リクエスト）には確認は不要です。

エンドポイントリファレンス

Raindrop（ブックマーク）

ドキュメント：https://developer.raindrop.io/v1/raindrops

単一の Raindrop に対する操作

操作	メソッド	エンドポイント
raindrop を取得	GET	/raindrop/{id}
raindrop を作成	POST	/raindrop
raindrop を更新	PUT	/raindrop/{id}
raindrop を削除	DELETE	/raindrop/{id}
ファイルをアップロード	PUT	/raindrop/file
カバーをアップロード	PUT	/raindrop/{id}/cover
永続コピーを取得	GET	/raindrop/{id}/cache
新しい URL を提案	POST	/raindrop/suggest
既存の raindrop を提案	GET	/raindrop/{id}/suggest

ドキュメント：https://developer.raindrop.io/v1/raindrops/single

Raindrop の作成／更新フィールド：

• 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（オブジェクト）- リマインダー設定

削除時の動作: raindrop を削除すると、ゴミ箱（コレクション ID -99）に移動します。ゴミ箱から削除すると、完全に削除されます。

複数の Raindrop 操作

操作	メソッド	エンドポイント
Raindrop を取得	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 - すべての Raindrop
• -1 - 未整理
• -99 - ゴミ箱
• 任意の正の整数 - 特定のコレクション

GET /raindrops/{collectionId} のクエリパラメーター：

• sort - 並べ替え順：-created（デフォルト）、created、score、-sort、title、-title、domain、-domain
• perpage - 1 ページあたりの結果数（最大 50）
• page - ページ番号（0 から始まります）
• search - 検索クエリ（references/search-operators.md を参照）
• nested - ブール値。子コレクションのブックマークを含めるかどうか

一括更新フィールド（ids 配列または search クエリを指定した PUT）：

• important（ブール値）
• tags（配列）- タグを追加します。空の配列を指定するとすべてクリアされます
• media（配列）- 追加します。空の配列を指定するとクリアされます
• cover（文字列）- URL または <screenshot>
• collection（オブジェクト）- 移動するには {"$id": collectionId} を指定します

エクスポート形式：csv、html、zip

コレクション

ドキュメント：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 を参照してください。

タグ

ドキュメント：https://developer.raindrop.io/v1/tags

操作	メソッド	エンドポイント
タグを取得	GET	/tags/{collectionId}
タグ名を変更	PUT	/tags/{collectionId}
タグを統合	PUT	/tags/{collectionId}
タグを削除	DELETE	/tags/{collectionId}

collectionId：すべてのコレクションのタグを取得するには、省略するか 0 を指定します。

タグ取得レスポンス：

{
  "result": true,
  "items": [{"_id": "tagname", "count": 42}]
}

タグ名の変更：

curl -s -X PUT \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"replace": "new-name", "tags": ["old-name"]}' \
  "https://api.raindrop.io/rest/v1/tags/0"

タグの統合（同じエンドポイントを使用し、配列に複数のタグを指定）：

curl -s -X PUT \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"replace": "merged-name", "tags": ["tag1", "tag2", "tag3"]}' \
  "https://api.raindrop.io/rest/v1/tags/0"

タグの削除：

curl -s -X DELETE \
  -H "Authorization: Bearer $RAINDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["tag-to-remove"]}' \
  "https://api.raindrop.io/rest/v1/tags/0"

ハイライト

ドキュメント：https://developer.raindrop.io/v1/highlights

操作	メソッド	エンドポイント
すべてのハイライトを取得	GET	/highlights
コレクションのハイライトを取得	GET	/highlights/{collectionId}
Raindrop のハイライトを取得	GET	/raindrop/{id}
ハイライトを追加	PUT	/raindrop/{id}
ハイライトを更新	PUT	/raindrop/{id}
ハイライトを削除	PUT	/raindrop/{id}

詳細については、references/highlights.md を参照してください。

フィルター

ドキュメント：https://developer.raindrop.io/v1/filters

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

すべてのコレクションには 0 を使用します。リンク切れ、重複、お気に入り、タグなしのアイテム、タグ、コンテンツタイプの集計数を返します。

クエリパラメーター：

• tagsSort - -count（デフォルト）または _id（アルファベット順）
• search - 追加の検索フィルター

ユーザー

ドキュメント：https://developer.raindrop.io/v1/user

操作	メソッド	エンドポイント
現在のユーザーを取得	GET	/user
ユーザーを更新	PUT	/user

インポート

ドキュメント：https://developer.raindrop.io/v1/import

操作	メソッド	エンドポイント
URL を解析	GET	/import/url/parse?url={url}
URL の存在を確認	POST	/import/url/exists
HTML ブックマークファイルを解析	POST	/import/file

バックアップ

ドキュメント：https://developer.raindrop.io/v1/backups

操作	メソッド	エンドポイント
バックアップを一覧表示	GET	/backups
バックアップをダウンロード	GET	/backup/{id}.{format}
新しいバックアップを生成	GET	/backup

形式：html または csv

認証：OAuth2 フロー

ドキュメント：https://developer.raindrop.io/v1/authentication/token

他のユーザーのデータにアクセスするアプリ（個人利用以外）では、完全な OAuth2 フローを使用します。

ステップ 1：認可

ユーザーを次の URL に誘導します。

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

ステップ 2：コードをトークンに交換

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 '.'

レスポンス：

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

ステップ 3：トークンを更新

アクセストークンの有効期限は 2 週間です。次の方法で更新します。

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 '.'

エラー処理

HTTP ステータスコードを確認します。

• 200 - 成功
• 204 - 成功、コンテンツなし
• 400 - 不正なリクエスト
• 401 - 認証に失敗しました（トークンを確認してください）
• 403 - アクセス禁止（権限が不足しています）
• 404 - リソースが見つかりません
• 429 - レート制限に達しました（120 リクエスト/分を超過）
• 5xx - サーバーエラー

エラー処理の例

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

よく使われるパターン

コレクション内のすべてのブックマークを一覧表示

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

ブックマークを作成

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 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}'

検索クエリの構文全体については、references/search-operators.md を参照してください。

ブックマークをコレクションに移動

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 '.'

すべてのタグを取得

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

コレクションを作成

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 '.'

すべてのコレクションを一覧表示（ルート＋子）

# 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"}'

すべてのブックマークをページネーションで取得

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 all bookmarks as CSV
curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/0/export.csv" -o bookmarks.csv

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

URL がすでに保存されているか確認

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 '.'

ページネーション

Raindrop はカーソルベースではなく、ページベースのページネーションを使用します。

• page - ページ番号（0 から始まります）
• perpage - 1 ページあたりのアイテム数（最大 50、ハイライトの場合のデフォルトは 25）

返されたアイテム数が perpage より少ない場合、最後のページに到達しています。

ネストされたコレクション構造

コレクションは階層構造で整理されています。サイドバー全体を再構築するには、次の手順が必要です。

1. GET /user - コレクションの並び順を含む groups 配列を返します
2. GET /collections - ルートコレクション
3. GET /collections/childrens - ネストされたコレクション

ルートコレクションの並び順は、ユーザーの groups[].collections 配列に保存されます。子コレクションの並び順は、コレクションの sort フィールドに保存されます。

参考資料

特定のトピックに関する詳細なドキュメントについては、次を参照してください。

• references/search-operators.md - 検索クエリの構文と演算子
• references/collections-sharing.md - コレクションの共有と共同編集者
• references/highlights.md - ハイライトの管理

ワークフローの概要

1. トークンを解決 - 環境、コンテキスト、またはユーザーに確認
2. 認証を検証 - GET /user でテスト
3. 読み取り操作 - 確認なしで直接実行
4. 書き込み操作 - 実行前に確認を求める
5. ページネーションを処理 - アイテム数が perpage 未満になるまでページ番号を増やしてループ
6. レスポンスを解析 - jq を使用してデータを抽出し、整形