Notiondesk API を使用すると、Notion の編集内容が準備できた瞬間に公開できます。スクリプト、CI パイプライン、または独自のツールから、ヘルプセンター全体、コレクション、または記事を同期できます。スケジュールされた同期をオンまたはオフにすることもできます。コンテンツは Notion 内に保持され、同期時に再度読み込まれて変更が公開されます。
| 方法 | パス | 範囲 | する |
|---|---|---|---|
POST | /sites/{site_id}/sync | sync | ヘルプセンター全体を同期します |
POST | /sites/{site_id}/categories/{category_id}/sync | sync | 1つのコレクションとその記事を同期します |
POST | /sites/{site_id}/articles/{article_id}/sync | sync | 記事を1つ同期します |
PATCH | /sites/{site_id}/settings/auto-sync | sync | スケジュールされた同期をオンまたはオフにします |
同期機能は初めてですか？まずは「ヘルプセンターをNotionと同期する方法」をお読みください。
ヘルプセンター全体を同期する
Notiondesk は、Notion からすべての記事とコレクションを再度読み込み、変更内容を公開します。同期がキューに追加されるとすぐにルートは 204 No Content と応答し、同期はバックグラウンドで実行されます。
一度に実行されるサイト同期は1つだけです。ヘルプセンターの同期がキューに登録されているか実行中の場合（スケジュール設定、ダッシュボードからの開始、API経由での開始に関わらず）、別のトリガーが409 conflict_errorを返します。数分待ってから再度トリガーを実行してください。
前回同期以降に変更のないコンテンツは、再度翻訳されません。
コレクションを同期する
コレクションリストからコレクションのidを使用します。Notiondeskは、Notionからコレクションとその各記事を再度読み込み、前回の同期以降に編集された記事のみを公開します。変更されていない記事は翻訳も再課金もされません。
記事を1つ同期する
記事リストから記事のidを使用してください。
curl -i -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Idempotency-Key: 9b2e4c1a-sync-after-notion-edit"curl -i -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories/1761493027/sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Idempotency-Key: 2c8e5b7d-sync-billing"curl -i -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles/1761580412/sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Idempotency-Key: 4d7a0f3e-sync-getting-started"コレクションと記事の同期がサイト同期とどう違うのか
| サイト同期 | コレクションまたは記事の同期 | |
|---|---|---|
| Notionから読み取る | すべての記事とコレクション | 一つのコレクションとその中の記事、または一つの記事 |
| 同じアイテムの別の同期が実行されている間に | 回答数 409 __保存済み_45__ | 別の同期をキューに追加します。conflict_error に応答しません。 |
| 制限 | 一度に1つずつ同期します | キーの書き込み予算は1分あたり20リクエストです。 |
同期が完了するたびに、ヘルプセンター全体が更新されます。同期は、タイマーではなく、Notionで編集を行うたびに一度だけ実行してください。定期的な更新には、スケジュール同期を使用してください。
同期を確認する
同期トリガーは、同期が完了したときではなく、同期がキューに登録されたときに204を返します。API経由で開始された同期は、スケジュールされた実行のみを表示する同期ステータスには表示されません。
同期を確認するには、それが公開するコンテンツを読んでください。
- 同期を開始し、その時刻を記録してください。
- 編集された記事を30秒ごとに
GET /sites/{site_id}/articles/{article_id}とともに読み上げます。
last_updatedがあなたが記録した時刻よりも後になった場合、またはtextにあなたの編集内容が表示された場合は、停止してください。
sync_failedがtrueの場合、sync_error_codeにその理由が記載されています。Notion の記事を修正して、再度同期してください。
スケジュール同期をオンまたはオフにする
curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/auto-sync" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Content-Type: application/json" \
-d '{"auto_sync_enabled": true}'| 分野 | タイプ | 注記 |
|---|---|---|
auto_sync_enabled | ブール値 | Notiondesk がスケジュールに基づいて Notion から同期するかどうか |
ルートの応答は204 No Contentです。ヘルプセンターのauto_sync_enabledで新しい状態を確認し、同期ステータスでスケジュールを確認してください。
- JSONブール値
trueまたはfalseを送信してください。値0および"false"はtrueとして読み取られます。
- 同期頻度はAPI経由では変更できません。
auto_sync_frequencyを送信すると、400validation_errorが返されます。ダッシュボードで変更してください。
- プランには、定期的な同期を含める必要があります。
- スケジュール同期をオンにすると、自動翻訳が有効になっている間、無人同期が開始され、課金対象の翻訳が行われます。
このルートには、write ではなく sync スコープが必要です。なぜなら、このルートが無人同期の実行タイミングを決定するからです。
エラー
| 状態 | いつ | code |
|---|---|---|
| 400 | 自動同期のみ: ボディに不明なフィールドがあります (auto_sync_frequency を含む) | validation_error |
| 403 | キーにはsyncスコープがありません | insufficient_scope |
| 403 | ヘルプセンターが無効になっているか、ご利用のプランに定期同期が含まれていないか、キーの作成者がこのヘルプセンターを同期できない可能性があります。 | permission_denied |
| 404 | ヘルプセンター、コレクション、または記事がワークスペースに存在しません。 | not_found |
| 409 | サイト同期のみ：ヘルプセンターの同期は既にキューに登録されているか、実行中です | conflict_error |
| 409 | 同じ Idempotency-Key のリクエストがまだ処理中です | request_in_progress |
conflict_error と request_in_progress は、同じステータスを持つ異なるエラーです。code で分岐します。__ ND_TERM_5bcd8dee__ API エラー、レート制限、および再試行の処理を参照してください。
よくある質問
同期トリガーを再試行しても安全ですか？
はい、Idempotency-Key で応答します。同じキーで再試行すると、X-Idempotent-Replay: true とともに 204 が返され、最初の同期がまだ実行中であっても何もキューに追加されません。
同期が完了したかどうかは、どうすればわかりますか？
同期された記事またはコレクションを読み込んで、last_updated がトリガーよりも後になるか、text に編集内容が表示されるまで待ちます。sync_in_progress だけに頼らないでください。トリガー後、キューに登録された同期が開始されるまでの数秒間は false のままになることがあります。API トリガーによる同期は同期ステータスには表示されません。
記事1つだけを同期するべきか、それともヘルプセンター全体を同期するべきか？
記事を編集したら、その記事を1つ同期します。また、コレクション内の複数の記事を編集したら、そのコレクションを同期します。コレクション間で記事を移動するなど、大きな変更を加えた後は、ヘルプセンター全体を同期します。
GitHub Actionsから同期できますか？
はい。キーをリポジトリシークレットとして保存し、ワークフローステップでサイト同期ルートを呼び出します。__ ND_TERM_5bcd8dee__ API を使用して一般的なヘルプセンタータスクを自動化するを参照してください。