ShareDanCMS 公開API

投稿一覧取得API

指定した種別（postType）の公開済みの投稿一覧を返却するAPI。 - 公開済み（status が公開、かつ published_at がリクエスト時刻以前）のもののみ返却する。 - 上部固定（pinned）した投稿を先頭に、以降を並び順（sort_order）の昇順でソートして返却する。固定が複数ある場合は、その中で並び順（sort_order）の昇順に並ぶ。カテゴリ絞り込み時も固定を先頭にする。ページネーションはこの並び順に対して行う。 - category（カテゴリslug）による絞り込みが可能。 - ページネーションに対応する。 - 一覧では本文（body）は返却しない。本文は個別取得API（GET /api/v1/posts/{postType}/{slug}）で取得する。

必須ヘッダー

パラメータ

レスポンス

スキーマ

投稿個別取得API

slugを指定して公開済みの投稿を1件返却するAPI。 - 公開済み（status が公開、かつ published_at がリクエスト時刻以前）のもののみ返却する。 - 未公開・下書き・存在しないslugの場合は404を返却する。 - 多言語オプション有効時は locale で言語別の公開版（タイトル・本文・メタ等）を返す。対象言語の公開版が無い場合は原文を返し translation_available: false を含める（9.10.1）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

投稿パスワード照合API

パスワード保護された投稿（is_password_protected=true）の本文を、閲覧パスワードの照合と引き換えに取得するAPI（SCR-104）。 - 個別取得（GET /api/v1/posts/{postType}/{slug}）は保護中の投稿の本文（body）を返さない。本APIに正しい閲覧パスワードを送ると、本文入りの PostDetail（GET と同一形状）を返す。 - 多言語オプション：有効時は locale で言語別の公開版（本文・タイトル・メタ等）を返す（個別取得 GET と同一。対象言語の公開版が無い場合は原文を返し translation_available: false を含める・9.10.1）。locale を指定しないと本文が原文（日本語）のまま返るため、保護中の投稿では個別取得で得たタイトルと言語が食い違う点に注意する。 - 照合失敗：パスワードが一致しない場合は 401（E001006）。投稿の存在自体はタイトル等が一覧で既に公開されているため秘匿しない。 - 総当たり対策：site＋種別＋slug＋閲覧者IP単位で試行回数を制限し、超過時は 429（E001007・Retry-After を付与）。閲覧者IPの判定は公開API共通（CloudFront-Viewer-Address）に従う。 - 未公開・存在しないslug：存在秘匿のため 404。 - 保護なし投稿：本文が元々公開のため、パスワードに関わらず本文入りで返す。 - キャッシュしない：保護本文を共有キャッシュ（CloudFront／レスポンスキャッシュ）に載せないため、成功・エラーとも Cache-Control: no-store を付与する。

必須ヘッダー

パラメータ

レスポンス

スキーマ

種別一覧取得API

siteの投稿の種別一覧を返却するAPI。 - 公開サイトが種別ごとのページ（/api/v1/posts/{postType}）を出し分けるための discovery に用いる。 - 表示順（sort_order）の昇順でソートして返却する。 - 既定種別「お知らせ」（slug news）を含む。

必須ヘッダー

レスポンス

スキーマ

投稿プレビュー取得API

プレビュー用トークンを用いて、投稿の下書き版を1件返却するAPI。 テナント管理画面の投稿編集画面のプレビューボタンで発行したトークンを用い、公開前・編集中の内容を実際のサイト表示で確認するために用いる。 - 通常の公開投稿取得（GET /api/v1/posts/{postType}/{slug}）が常に公開済みのみを返すのに対し、本APIは下書き版を返す（未公開の新規／公開済み投稿の未公開変更／変更のない公開済み投稿、のいずれも下書き版を描画する）。 - 認証：プレビュー用トークンを必須とする。X-PREVIEW-TOKEN ヘッダ（推奨。ログへのトークン露出を避ける）または ?token= クエリで受け付ける。既存公開APIの認証（X-API-KEY＋X-SITE-CODE）とは別レイヤの認証で、両方を満たす必要がある。 - 404 に統一：トークンが不正・期限切れ（既定24時間）・失効済み（投稿／サイト削除・管理者による明示失効）・対象不一致（トークンのスコープと slug／サイトが一致しない）の場合は、いずれも 404 を返す（存在秘匿のため 401/403 とせず、公開APIの未公開＝404方針と一貫）。 - レスポンス形状は公開API（GET /api/v1/posts/{postType}/{slug}）と完全に同一（PostDetail）。公開／下書きの区別を外部に漏らさないため、status 等の内部状態フィールドは含めない。フロントエンドは公開ページと同一の表示ロジックを再利用できる。 - キャッシュしない：下書き変更後に即座に最新内容を確認できるよう、公開APIのレスポンスキャッシュ経路（CloudFront／共有キャッシュ）を経由せず、成功・エラーとも Cache-Control: no-store を付与する。 - プレビューページ側は検索エンジンにインデックスされないよう noindex,nofollow を設定する（フロントエンド責務）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

FAQ一覧取得API

公開済みのFAQ一覧を返却するAPI。 - 公開済み（status が公開、かつ published_at がリクエスト時刻以前）のもののみ返却する。 - 並び順（sort_order）の昇順でソートして返却する。 - category（カテゴリslug）による絞り込みが可能。 - FAQは件数が限定的なため、ページネーションは行わず全件返却する。 - 多言語オプション有効時は locale で質問・回答・カテゴリ名を言語別に返す（9.10.1）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

固定コンテンツ取得API

keyを指定して公開済みの固定コンテンツを1件返却するAPI。 - 公開済み（status が公開、かつ published_at がリクエスト時刻以前）のもののみ返却する。 - 非公開・未公開・存在しないkeyの場合は404を返却する。 - 本文はTiptap（ProseMirrorドキュメント）のJSONで返却する。 - 多言語オプション有効時は locale で本文を言語別に返す。対象言語の公開版が無い場合は原文を返し translation_available: false を含める（9.10.1）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

投稿カテゴリ一覧取得API

指定した種別（postType）に属するカテゴリ一覧を返却するAPI。 - 公開済み（is_public が true・未削除）のカテゴリのみ返却する。 - 表示順（sort_order）の昇順でソートして返却する。 - 多言語オプション有効時は locale でカテゴリ名を言語別に返す（slug は言語共通・9.10.1）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

FAQカテゴリ一覧取得API

FAQ用のカテゴリ一覧を返却するAPI。 - 公開済み（is_public が true・未削除）のカテゴリのみ返却する。 - 表示順（sort_order）の昇順でソートして返却する。 - 多言語オプション有効時は locale でカテゴリ名を言語別に返す（slug は言語共通・9.10.1）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

フォーム項目定義取得API

keyを指定して公開中フォームの項目定義（配信）を返却するAPI。 - 公開中のフォームのみ返却する。 - 非公開・存在しないkeyの場合は404を返却する。 - 多言語オプション有効時は locale でフォーム定義のテキスト（項目ラベル等）を言語別に返す。フォーム定義は常に自動翻訳（手動編集なし）で、対象言語の訳が無い場合は原文を返し translation_available: false を含める（9.10.1／9.10.4）。name（フォーム名）・選択肢ラベルも翻訳対象に含める。name（項目のキー）・type 等の識別子は言語共通（翻訳しない）。 - 本APIは送信速度チェック用の署名トークン（speed_check_token）をリクエストごとに発行するため、配信レスポンスはキャッシュ対象外（Cache-Control: no-store）とする。fields 自体は静的だが、トークンの発行時刻（＝ページ表示時刻）を各アクセスで正しく反映する必要があるため、レスポンス全体をキャッシュしない（キャッシュすると全利用者が同一トークンを共有し、送信速度チェックがキャッシュ経過時間を測る形になり機能しない）。 - フロントがスパム対策ウィジェットを描画・トークン付与できるよう、サイト側描画に必要な範囲のみ（turnstile・speed_check_token）を返却する。ハニーポット・レートリミット・重複送信チェックの内部詳細は返却しない。 - turnstile: Turnstile有効時のみ site_key を返す（secret_key は絶対に返却しない）。 - speed_check_token: 送信速度チェック有効時に発行する、発行日時＋nonceをサーバ署名した改ざん検知可能なトークン。送信（POST）時に経過秒判定・改ざん検知に用いる。トークンの発行時刻を各アクセスで正しく反映するため、上記のとおり配信レスポンスはキャッシュしない（Cache-Control: no-store）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

フォーム送信API

公開中フォームへの送信を受け付け、送信データをテナント管理画面へ蓄積するAPI。 - 送信（POST）はキャッシュ対象外。すべてのレスポンス（成功・エラーとも）に Cache-Control: no-store を付与する。 - リクエストボディは、各フォーム項目の name をキー・入力値を値とするマップに、スパム対策用の項目（_hp_name・_hp_website・speed_check_token・turnstile_token）を加えたもの。 - スパム対策（ハニーポット・Cloudflare Turnstile・送信速度チェック・重複送信チェック・レートリミット）を標準提供する。各対策はフォーム設定でON/OFF可能で、無効な対策の段階はスキップする。 処理順（上から順に評価し、いずれかで拒否した時点で以降は実行しない）： 1. フォーム存在確認：存在しないkeyは404（E000007）。 2. 公開状態確認：非公開のフォームは404（E000007）。 3. リクエストサイズ確認：ペイロードが上限を超過した場合は400（E000002）で拒否する。 4. 入力バリデーション：項目定義（fields）に基づく必須・型・メール形式・選択肢等の検証。失敗は422（E000001）。 5. レートリミット〔有効時〕：閲覧者IP 3回/分・フォーム 10回/10分。超過は429（E001003）を返し、Retry-After ヘッダで再試行までの待機秒数を返す。 6. Turnstile検証〔有効時〕：turnstile_token をCloudflare Siteverifyでサーバ検証する。検証失敗は400（E000002）。 7. ハニーポット検査〔有効時〕：_hp_name / _hp_website が空でない場合はボットとみなし422（E000001）。 8. 送信速度チェック〔有効時〕：speed_check_token（サーバ署名）の改ざん検知と発行からの経過秒を判定し、2秒未満はスパムとみなし422（E000001）。 9. 重複送信チェック〔有効時〕：formId＋email＋本文のハッシュで直近の重複送信を検出し、重複は422（E000001）。 10. DB保存：送信データをテナント管理画面へ蓄積する。 11. メール送信ジョブ登録：自動返信メール（送信者宛）・受信通知メール（管理者宛）を非同期ジョブで送信する（フォーム設定でON/OFF）。メール送信の失敗はAPIの成否に影響させない（APIは失敗させない）。 12. 正常レスポンス：201（受付結果を返却）。 - 上記に加え、閲覧者IP単位の共通レート上限（全プラン 300 req/min）を超過した場合は403（E001004）を返却する。

必須ヘッダー

パラメータ

レスポンス

スキーマ

メンテナンス状態取得API

siteのメンテナンス状態を返却するAPI。 - メンテナンス中の場合は maintenance: true と、見出し（title）・案内メッセージ（message）・再開予定日時（resumes_at）を返却する。 - メンテナンス中でない場合は maintenance: false のみを返却する。 - 公開サイトはこの値を見てメンテナンス画面の表示要否を判断する。 - 投稿・FAQ・固定コンテンツ等の他コンテンツAPIとは独立しており、site単位の uses_* 設定（利用するコンテンツ設定）による404ゲートの対象外として常に応答する。 - 多言語オプション有効時は locale で title／message を言語別に返す。メンテナンス状態は常に自動翻訳（手動編集なし）で、対象言語の訳が無い場合は原文を返し translation_available: false を含める（resumes_at は翻訳対象外・9.10.1／9.10.4）。 - 状態を即時反映するため、キャッシュTTLは短くする（またはキャッシュ対象外とする）。

必須ヘッダー

パラメータ

レスポンス

スキーマ

変更検知API（増分SSG向け差分配信）

サイト単位の最終ビルド日時（m_sites.last_built_at）以降に updated_at が更新された公開コンテンツの差分一覧を返すAPI。大量コンテンツサイトで、前回ビルド以降に変更があったページのみを再生成する増分SSGに用いる。 - last_built_at が未設定（NULL）の場合は初回ビルドとみなし、現在公開中の全コンテンツを upsert で列挙し full_resync: true を返す。 - カテゴリ・タグ名の変更、およびサイト設定画面（SCR-120）からの手動ビルドは全体ビルドとし full_resync: true を返す（カテゴリ名・タグ名は多数の投稿記事に波及するため、個別差分ではなく全体再生成とする）。サーバーは該当契機で m_sites.full_rebuild_requested_at を更新し、full_rebuild_requested_at > last_built_at の間 full_resync: true とする（完了通知で last_built_at が前進すると自然に解消）。 - フォーム定義の変更は局所的（特定ページに埋め込み・多くは実行時に GET /api/v1/forms/{key} で取得）なため全体ビルドにせず、type=form の差分エントリ（action=upsert）として返す。 - 各レコードの updated_at を last_built_at と比較して差分を判定する（論理削除分も含めて走査）。 - action は、対象レコードが現在公開中なら upsert（＝再生成。編集・公開・予約go-live・並べ替え・非公開解除を包含）、非公開・論理削除・未公開なら delete（＝SSGから該当ページを除去。元々無ければ無視）に二分する。 - 予約投稿の公開（go-live）は、行の内容が変わらず updated_at が据え置かれるため、BAT-001（公開日時反映処理）が go-live 到来時に該当投稿の updated_at を更新することで差分に乗せる。 - このAPIは watermark（last_built_at）を進めない（冪等）。レスポンスのサーバー時刻 as_of を、ビルド成功後に POST /api/v1/changes/complete の built_as_of として返すことで初めて前進する。これを呼ぶまでは同じ差分を何度でも返す。 - 認証は公開APIと同じ X-API-KEY＋X-SITE-CODE。多言語（locale）は取らない（言語別の差分は原文の updated_at に紐づく）。

必須ヘッダー

レスポンス

スキーマ

変更検知API・ビルド完了通知

増分ビルドが成功した後に呼び出し、サイトの最終ビルド日時（m_sites.last_built_at）を前進させるAPI。直前の GET /api/v1/changes が返した as_of を built_as_of として送る。 - last_built_at は built_as_of が現在値以上のときのみ前進させる（巻き戻さない）。 - 公開APIは閲覧専用（api_public ロールは m_sites への書き込み権限を持たない）ため、実際の m_sites.last_built_at 更新はowner接続のキュージョブ経由で行い、本APIは受理（202相当）のみ返す。 - このAPIを呼ぶまでは GET /api/v1/changes は同じ差分を何度でも返す（ビルド失敗時は呼ばずに再試行すれば差分を取りこぼさない）。 - full resync（全件再同期）をやり直したい場合は、運営側で last_built_at を NULL にリセットする（本APIでは行わない）。 - 認証は公開APIと同じ X-API-KEY＋X-SITE-CODE。

必須ヘッダー

パラメータ

レスポンス

スキーマ