API リファレンス
この章では、公開ドキュメントとして扱うべき API（ブラウザクライアントと第三者検証で利用するエンドポイント）を、現行実装ベースで説明します。
この章の対象範囲
対象:
- 投票・集計フロー（
/api/session,/api/vote,/api/progress,/api/finalize,/api/finalize/cancel,/api/sessions/:sessionId/status） - 検証フロー（
/api/verify,/api/verification/run, バンドル取得） - 監査補助（
/api/bulletin/*,/api/bitmap-proof,/api/sth,/api/zkvm-input-hash,/api/botdata/:id）
対象外（内部運用 / デバッグ向け）:
GET /api/debug/enablePOST /api/finalize/callback
デュアルランタイム構成
API ハンドラはフレームワーク非依存の共通実装で、Next.js と Hono(Lambda) の両方から利用されます。
| ランタイム | 用途 | 主な入口 |
|---|---|---|
| Next.js Route Handler | ローカル開発 / SSR | src/app/api/**/route.ts |
| Hono on Lambda | AWS 本番 API | amplify/functions/hono-api/handler.ts |
リクエスト処理の実装上の注意
ミドルウェアは「全リクエスト共通の固定チェーン」ではなく、エンドポイント実装ごとに必要な検証を呼び出す方式です。
| 区分 | 代表エンドポイント | X-Session-ID | Turnstile | レート制限 |
|---|---|---|---|---|
| 投票 | POST /api/vote | 必須 | あり | 投票用 |
| 集計 | POST /api/finalize | 必須 | あり | zkVM 用 |
| 検証実行 | POST /api/verification/run | 必須 | なし | zkVM 用 |
| 読み取り（多く） | GET /api/verify, GET /api/bulletin など | 多くで必須 | なし | なし |
| 読み取り（例外） | GET /api/sessions/:sessionId/status, バンドル取得, GET /api/zkvm-input-hash | 不要 | なし | なし |
補足:
GET /api/bitmap-proofのX-Session-IDはストア実装依存です（Mock/File は省略可、Amplify は実質必須）。
エラーレスポンスの実装差分
多くのエンドポイントは errorResponse(...) を通して以下の形式を返します。
error（エラーコード）message（メッセージ）statusCode（HTTP ステータス）- 必要に応じて
detailsなど
ただし、いくつかのエンドポイント（例: GET /api/sessions/:sessionId/status, GET /api/verification/bundles/...）は、{ error: "..." } のような独自形式を返します。詳細は エンドポイント一覧 を参照してください。
この部に含まれる章
- エンドポイント一覧 — 公開対象 API のリクエスト/レスポンス仕様
- セッションライフサイクル — クライアントとサーバーのセッション管理実装