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 回の確認で十分です。

削除操作には以下が含まれます:

• レインドロップ、コレクション、またはタグの削除
• 一括更新またはレインドロップの移動
• タグのマージまたは削除
• 共有コレクションからのコラボレーターの削除
• ゴミ箱のクリア

読み取り専用操作 (GET リクエスト) は確認不要です。

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

レインドロップ (ブックマーク)

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

単一レインドロップ操作

操作	メソッド	エンドポイント
レインドロップを取得	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) に移動します。ゴミ箱から削除すると完全に削除されます。

複数レインドロップ操作

操作	メソッド	エンドポイント
レインドロップを取得	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

コレクション

ドキュメント: 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}
レインドロップハイライトを取得	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: 認可

ユーザーを以下にリダイレクト:

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

ブックマークを検索

# すべてのコレクションを検索
curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/0?search=YOUR_QUERY" | jq '.items[] | {title, link}'

# タグフィルター付きで検索
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 '.'

すべてのコレクション (ルート + 子) をリスト表示

# ルートコレクション
curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/collections" | jq '.items[] | {id: ._id, title}'

# 子コレクション
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

ブックマークをエクスポート

# すべてのブックマークを CSV としてエクスポート
curl -s -H "Authorization: Bearer $RAINDROP_TOKEN" \
  "https://api.raindrop.io/rest/v1/raindrops/0/export.csv" -o bookmarks.csv

# 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 - ページあたりのアイテム数 (最大 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 を使用してデータを抽出およびフォーマット