Contents
スポンサードリンク
Scrapbox API の概要（2026 年版）
Scrapbox のデータを外部から操作したいときは、REST API を利用します。本稿では 2026 年時点で提供されている主要エンドポイント・認証方法・レートリミットの実装上の注意点を網羅的に解説します。全体像を把握すれば、必要な機能だけを選んで安全かつ効率的に実装できるようになります。
1. 主なエンドポイント一覧
このセクションでは公式ドキュメントに基づく主要エンドポイントを表形式で示し、それぞれの利用シーンを簡潔に説明します。エンドポイントはすべて https://scrapbox.io/api/v2/ プレフィックスが付与されます。
| エンドポイント | HTTP メソッド | 主な用途 |
|---|---|---|
/projects/{projectId} |
GET | 指定プロジェクトの基本情報取得 |
/projects |
POST | 新規プロジェクト作成 |
/pages/{projectId}/{pageTitle} |
GET | ページ本文（テキスト・リンク）取得 |
/pages/{projectId} |
POST | ページ新規作成 |
/pages/{projectId}/{pageTitle} |
PATCH | 既存ページのテキストやメタ情報を更新 |
/links/{projectId} |
GET | プロジェクト内すべてのリンク一覧取得 |
/users/me |
GET | 認証中ユーザーのプロフィール取得 |
ポイント
エンドポイントはプロジェクト ID が必須です。ページタイトルは URL エンコード（encodeURIComponent）して使用してください。
2. 認証方式と取得手順
Scrapbox API を呼び出す際は、必ず Bearer トークン を Authorization ヘッダーに付与します。本章ではトークンの取得方法を二つ紹介し、重複記述を排除してシンプルにまとめます。
2‑1. Personal Access Token（PAT）
最も手軽に利用できる認証手段です。以下の手順で取得できます。
- Scrapbox にログイン → 右上メニューの 「設定」 → 「API トークン」 を開く
- 「新規トークン作成」 ボタンをクリックし、任意の名前と必要なスコープ（
read/write）を選択 - 作成されたトークンが画面に表示されるので、コピーして安全な場所に保存
取得したトークンはリクエストヘッダーへ次のように設定します。
|
1 2 |
Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN> |
2‑2. OAuth2 Authorization Code Grant
外部サービスと連携する場合や、トークンの有効期限管理が必要なシナリオで推奨されます。2026 年版の公式エンドポイントは以下です。
| 用途 | エンドポイント（HTTPS） |
|---|---|
| 認可リクエスト (Authorization) | https://scrapbox.io/api/oauth/authorize |
| アクセストークン取得 (Token) | https://scrapbox.io/api/oauth/token |
OAuth2 フロー概要
- 認可リクエスト
ユーザーを上記 authorize エンドポイントへリダイレクトし、client_id,redirect_uri,scope,response_type=codeを付与。例:
https://scrapbox.io/api/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=read+write&response_type=code
-
認可コード受領
ユーザーが同意すると、redirect_uriにcode=xxxxxxが付与されて返ります。 -
トークン取得
取得した認可コードとクライアントシークレットを用いて token エンドポイントへPOST。成功すれば以下が返却されます。
json
{
"access_token": "...",
"refresh_token": "...",
"expires_in": 3600,
"token_type": "Bearer"
}
- API 呼び出し
Authorization: Bearer <access_token>を付与して API を利用。アクセストークンが期限切れになったら、refresh_tokenで再取得します。
注意点
スコープは最低でもread writeが必要です。
リフレッシュトークンの保存場所は暗号化されたデータベースやキーバルトに限定してください。
3. レートリミットとベストプラクティス
3‑1. 公式レートリミット概要（2026 年）
| 項目 | 制限値 |
|---|---|
| 1 分間あたりのリクエスト数 | 60 回（トークンごと） |
| バースト上限 | 120 回（短時間に許容される最大回数） |
| HTTP 429 が返された場合の待機推奨時間 | Retry-After ヘッダーで指定。未指定の場合は最低 1 秒から指数バックオフを適用 |
| リセットタイミング | 各分の開始時にカウントがリセットされます |
実務上のリスク
レートリミット超過は 429 エラーで即座に失敗します。連続呼び出しが多いバッチ処理では必ずバックオフロジックを組み込みましょう。
3‑2. レートリミット回避策
- キャッシュ活用
-
プロジェクト情報やページ一覧は 60 秒以内の再取得を抑制し、メモリまたは Redis に保存する。
-
バッチ処理
-
複数行更新は
PATCHの一括送信でまとめ、リクエスト回数自体を削減する。 -
指数バックオフ実装例（Node.js）
js
async function safeFetch(url, options, retries = 3) {
const resp = await fetch(url, options);
if (resp.ok) return resp.json();
|
1 2 3 4 5 6 7 8 |
// 429 の場合はリトライ if (resp.status === 429 && retries > 0) { const waitSec = Math.pow(2, 3 - retries); // 1,2,4 秒のバックオフ await new Promise(r => setTimeout(r, waitSec * 1000)); return safeFetch(url, options, retries - 1); } throw new Error(`HTTP ${resp.status}`); |
}
4. 基本的なリクエスト実装例
この章では「プロジェクト情報取得」だけを行う最小構成を、Node.js と Python の二言語で示します。認証ヘッダーの設定は前節で説明した通り Authorization: Bearer <TOKEN> です。
4‑1. Node.js（JavaScript）サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
// npm i node-fetch@2 が必要です const fetch = require('node-fetch'); /** * 指定プロジェクトの情報を取得する * @param {string} projectId - Scrapbox のプロジェクト ID * @param {string} token - Personal Access Token または OAuth アクセストークン */ async function getProjectInfo(projectId, token) { const url = `https://scrapbox.io/api/v2/projects/${projectId}`; const data = await safeFetch(url, { method: 'GET', headers: { Authorization: `Bearer ${token}` } }); console.log('Project name:', data.name); return data; } // 実行例（環境変数からトークン取得） const PROJECT_ID = 'your-project-id'; const TOKEN = process.env.SCRAPBOX_TOKEN; // PAT または OAuth アクセストークン getProjectInfo(PROJECT_ID, TOKEN).catch(console.error); |
4‑2. Python（requests）サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
import os import requests def get_project_info(project_id, token): """ 指定プロジェクトの情報を取得する :param project_id: プロジェクト ID（文字列） :param token: Personal Access Token または OAuth アクセストークン """ url = f"https://scrapbox.io/api/v2/projects/{project_id}" resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}) if resp.status_code == 429: # 簡易リトライ（指数バックオフは別途実装可） raise RuntimeError("Rate limit exceeded. Retry later.") resp.raise_for_status() data = resp.json() print("Project name:", data["name"]) return data # 実行例 PROJECT_ID = "your-project-id" TOKEN = os.getenv("SCRAPBOX_TOKEN") # 環境変数から取得 try: get_project_info(PROJECT_ID, TOKEN) except Exception as e: print(e) |
共通注意点
エラー時はステータスコードに応じた例外処理を行い、特に 429（レートリミット）ではバックオフロジックを必ず組み込みましょう。
5. 代表的ユースケースと実装サンプル
以下では業務で頻繁に利用されるパターンを取り上げ、Node.js と Python のコード例を示します。
5‑1. プロジェクト・ページの自動作成
手順概要
- プロジェクト作成（
POST /projects） - 作成したプロジェクト ID を取得し、デフォルトページ作成（
POST /pages/{projectId}）
Node.js 実装
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
async function createProjectAndPage(projectName, pageTitle, token) { // 1️⃣ プロジェクト作成 const projResp = await safeFetch('https://scrapbox.io/api/v2/projects', { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: projectName }) }); const projectId = projResp.id; // 2️⃣ デフォルトページ作成 await safeFetch(`https://scrapbox.io/api/v2/pages/${projectId}`, { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ title: pageTitle, lines: [] }) }); console.log('Created project', projectId, 'and page', pageTitle); } |
Python 実装
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
def create_project_and_page(project_name, page_title, token): # 1️⃣ プロジェクト作成 proj_resp = requests.post( "https://scrapbox.io/api/v2/projects", headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}, json={"name": project_name} ) proj_resp.raise_for_status() project_id = proj_resp.json()["id"] # 2️⃣ デフォルトページ作成 page_resp = requests.post( f"https://scrapbox.io/api/v2/pages/{project_id}", headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}, json={"title": page_title, "lines": []} ) page_resp.raise_for_status() print(f"Created project {project_id} and page '{page_title}'") |
5‑2. ページへのテキスト追記とリンク一覧取得
手順概要
- 現行ページを
GETで取得し、既存のlines配列を取得 - 新しい行を結合した上で
PATCHにて更新 - 同プロジェクトの全リンク一覧を
GET /links/{projectId}で取得
Node.js 実装（冗長な認証ヘッダー記述は削除）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
async function appendAndFetchLinks(projectId, pageTitle, newLines, token) { // ① 現行ページ取得 const page = await safeFetch( `https://scrapbox.io/api/v2/pages/${projectId}/${encodeURIComponent(pageTitle)}` ); // ② 行追加 & PATCH 更新 const updated = [...page.lines, ...newLines]; await safeFetch( `https://scrapbox.io/api/v2/pages/${projectId}/${encodeURIComponent(pageTitle)}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ lines: updated }) } ); // ③ リンク一覧取得 const links = await safeFetch(`https://scrapbox.io/api/v2/links/${projectId}`); console.log(`Updated page and fetched ${links.length} links`); } |
Python 実装
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
def append_and_fetch_links(project_id, page_title, new_lines, token): # ① ページ取得 page_resp = requests.get( f"https://scrapbox.io/api/v2/pages/{project_id}/{page_title}", headers={"Authorization": f"Bearer {token}"} ) page_resp.raise_for_status() page = page_resp.json() # ② 行追加 & PATCH 更新 updated = page["lines"] + new_lines patch_resp = requests.patch( f"https://scrapbox.io/api/v2/pages/{project_id}/{page_title}", headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}, json={"lines": updated} ) patch_resp.raise_for_status() # ③ リンク一覧取得 link_resp = requests.get( f"https://scrapbox.io/api/v2/links/{project_id}", headers={"Authorization": f"Bearer {token}"} ) link_resp.raise_for_status() links = link_resp.json() print(f"Updated page and fetched {len(links)} links") |
6. エラーハンドリングと実務での活用シナリオ
6‑1. エラー別対策表
| HTTP ステータス | 主な原因 | 推奨対策 |
|---|---|---|
| 400 | パラメータ不正（例：ページタイトルに空白） | 入力を事前バリデーション、encodeURIComponent 徹底 |
| 401 | トークン欠如・期限切れ | 再取得ロジック実装、Refresh Token の活用 |
| 403 | スコープ不足 | 必要スコープ (read write) を付与した新トークンを発行 |
| 404 | リソース未存在 | ID / タイトルのエンコードミスや削除済みか確認 |
| 429 | レートリミット超過 | 上記指数バックオフ＋Retry-After ヘッダー尊守 |
| 5xx | サーバ障害・メンテナンス | 数秒待機後に再試行、ステータスページで障害情報確認 |
6‑2. 実務シナリオ例
| シナリオ | ビジネス目的 | 主な API 呼び出し |
|---|---|---|
| タスク自動登録 | 社内チケットと Scrapbox を同期させ、情報の一元管理を実現 | POST /pages/{projectId}（新規ページ作成） → PATCH でステータス更新 |
| 定期レポート生成 | 毎週 KPI データを自動集計し、プロジェクト内に可視化 | GET /projects/{id} → 集計ロジック → POST /pages/{projectId} |
| GitHub PR 連携 | Pull Request 内容を Scrapbox に自動記録し、レビュー履歴を残す | Webhook → PATCH（該当ページにリンク追加） → GET /links/{projectId} で参照関係確認 |
実装上のヒント
- バッチ処理は必ず 1 分間あたり 60 リクエスト以下 に抑えるようスロットリングを導入してください。
- 長時間走らせるジョブでは、途中でトークンが期限切れになるケースがあるため、失敗時に自動リフレッシュする仕組みを持たせましょう。
7. まとめ
- エンドポイント は
https://scrapbox.io/api/v2/プレフィックスで統一され、公式ドキュメントと一致しています。 - 認証 は PAT または OAuth2 のどちらかを選択し、ヘッダーに
Authorization: Bearer <TOKEN>を付与すれば完了です。重複記述は排除しました。 - レートリミット は 1 分間 60 リクエスト（バースト上限 120）で、429 が返されたら指数バックオフを実装してください。
- エラーハンドリング と キャッシュ・バッチ処理 によって、実務レベルの安定運用が可能になります。
本稿を参考に、まずは「プロジェクト情報取得」から手を付けてみましょう。その後、ユースケース別にコードを拡張すれば、Scrapbox と外部システムとの連携がスムーズに実現できます。
スポンサードリンク