{"openapi":"3.1.0","info":{"title":"DebateCross API","version":"1.2.0","description":"複数の AI による 3 ラウンドの討論（独立回答 → 相互批評 → 統合）を実行する API。組織の API キーだけが使える。\n\n金額はすべて円の請求額（システム利用料 1 回 15 円＋AI トークン料）。時刻は ISO 8601（オフセット付き）、月の区切りは JST の暦月。\n\n互換の方針: フィールド・include の値・エラーの code の追加は予告なく行う（未知のフィールドは無視し、未知の code は HTTP ステータスで扱うこと）。討論の status は 5 値から増やさない。互換を壊す変更は /api/v2 として出す。\n\nサーバー間の呼び出し専用（CORS ヘッダは返さない）。全応答に X-Request-Id、429・503 に Retry-After。"},"servers":[{"url":"https://app.debatecross.com"}],"paths":{"/api/v1/me":{"get":{"operationId":"getMe","summary":"API キーの情報・枠と当月の使用額・制限値と現在値","security":[{"bearerAuth":[]}],"x-scope":null,"parameters":[],"responses":{"200":{"description":"キー・組織・使用額・制限値","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time","description":"発行日時"},"expires_at":{"anyOf":[{"type":"string","format":"date-time","description":"有効期限"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time","description":"最後に使われた日時（1 分単位）"},{"type":"null"}]}}},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"spend":{"type":"object","properties":{"month":{"type":"string","description":"JST の暦月（YYYY-MM）"},"month_start":{"type":"string","format":"date-time","description":"月の始まり"},"monthly_cap_jpy":{"anyOf":[{"type":"number","description":"キーの月上限。開始時に「当月の請求額＋仮押さえ＋この討論の見込み」で判定する。見込みとの比較なので、実行したラウンドの実請求が見込みを上回った分だけ月上限を超えることはある（円）"},{"type":"null"}]},"per_run_cap_jpy":{"anyOf":[{"type":"number","description":"キーの 1 回上限（円）"},{"type":"null"}]},"month_to_date_jpy":{"type":"number","description":"当月の請求額＋実行中の仮押さえ（円）"},"monthly_remaining_jpy":{"anyOf":[{"type":"number","description":"月上限の残り（円）"},{"type":"null"}]}}},"limits":{"type":"object","properties":{"max_prompt_chars":{"type":"integer","const":10000},"min_models":{"type":"integer","const":2},"max_models":{"type":"integer","const":5},"rounds":{"type":"array","items":{"type":"integer"}},"requests_per_minute":{"type":"object","properties":{"limit":{"type":"integer"}}},"concurrent_debates":{"$ref":"#/components/schemas/LimitWithCurrent"},"debates_per_hour":{"$ref":"#/components/schemas/LimitWithCurrent"},"org_concurrent_debates":{"$ref":"#/components/schemas/LimitWithCurrent"},"daily_truncations":{"$ref":"#/components/schemas/LimitWithCurrent"},"org_daily_truncations":{"$ref":"#/components/schemas/LimitWithCurrent"},"org_api_keys":{"type":"object","description":"組織の有効な（取り消していない）API キーの本数と上限（D20）","properties":{"limit":{"type":"integer"},"current":{"type":"integer"}}}}}}}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]}},"/api/v1/balance":{"get":{"operationId":"getBalance","summary":"組織の残高・仮押さえ・有効期限・自動チャージ","security":[{"bearerAuth":[]}],"x-scope":"usage:read","parameters":[],"responses":{"200":{"description":"組織の財布の残高（円）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","const":"JPY"},"available_jpy":{"type":"number","description":"新しい討論に使える残高（失効分と仮押さえを除く）（円）"},"reserved_jpy":{"type":"number","description":"実行中の討論の仮押さえ（円）"},"expiries":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["paid","bonus"]},"amount_jpy":{"type":"number","description":"額（円）"},"expires_at":{"anyOf":[{"type":"string","format":"date-time","description":"有効期限（null は期限なし）"},{"type":"null"}]}}}},"auto_recharge":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_jpy":{"anyOf":[{"type":"number","description":"この額を下回ったらチャージ（円）"},{"type":"null"}]},"amount_jpy":{"anyOf":[{"type":"number","description":"1 回のチャージ額（円）"},{"type":"null"}]}}},"as_of":{"type":"string","format":"date-time","description":"算出日時"}}}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE"]}},"/api/v1/models":{"get":{"operationId":"listModels","summary":"討論に使えるモデルと請求単価（円）","description":"models[]・synthesizer に渡す ID を知る唯一の手段。単価の更新は日次（Cache-Control: private, max-age=300）","security":[{"bearerAuth":[]}],"x-scope":"debates:read","parameters":[],"responses":{"200":{"description":"モデルの一覧","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","const":"JPY"},"system_fee_jpy_per_debate":{"type":"number","description":"討論 1 回のシステム利用料（円）"},"pricing_note":{"type":"string"},"rate_as_of":{"anyOf":[{"type":"string","format":"date-time","description":"為替の基準日時"},{"type":"null"}]},"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"context_window":{"anyOf":[{"type":"integer"},{"type":"null"}]},"premium_tier":{"type":"boolean","description":"高価格帯か"},"available":{"type":"boolean","description":"この組織で開始に使えるか（開始と同じ判定）"},"pricing":{"type":"object","properties":{"input_jpy_per_1m":{"type":"number","description":"入力 1M トークンあたりの請求単価（円）"},"output_jpy_per_1m":{"type":"number","description":"出力 1M トークンあたりの請求単価（円）"},"rate_as_of":{"anyOf":[{"type":"string","format":"date-time","description":"為替の基準日時"},{"type":"null"}]}}}}}}}}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE"]}},"/api/v1/estimates":{"post":{"operationId":"createEstimate","summary":"見積もり（課金されない）","description":"開始の仮押さえ額と同じ式。開始と同じ入力検査を通す","security":[{"bearerAuth":[]}],"x-scope":"debates:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt","models","synthesizer"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"お題（日本語前提のプロンプト）。最大文字数を超えると 400 PROMPT_TOO_LONG"},"models":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"items":{"type":"string","maxLength":200},"description":"Round 1・2 に参加するモデルの ID（GET /api/v1/models の id をそのまま渡す）"},"synthesizer":{"type":"string","maxLength":200,"description":"Round 3 で統合回答を書くモデルの ID"},"mode":{"type":"string","enum":["converge","hybrid","diverge"],"default":"converge","description":"討論のモード（converge＝収束／hybrid／diverge＝発散）。省略時 converge"},"rounds":{"type":"integer","enum":[3],"default":3,"description":"ラウンド数。現在は 3 のみ"}}}}}},"responses":{"200":{"description":"見積もり（円）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","const":"JPY"},"estimate":{"$ref":"#/components/schemas/Estimate"},"per_run_cap_jpy":{"anyOf":[{"type":"number","description":"キーの 1 回上限（円）"},{"type":"null"}]}}}}}},"400":{"description":"INVALID_REQUEST: 本文の形・型・enum 外の値・クエリの形式不正 / PROMPT_TOO_LONG: お題（prompt）が最大文字数を超えた / UNKNOWN_MODEL: モデル一覧に無いモデル ID（日次の同期で消えた場合を含む。GET /api/v1/models を取り直す） / CONTEXT_BUDGET_EXCEEDED: お題と出力の合計が選んだモデルの文脈長に収まらない（モデルかお題を変える） / MODEL_NOT_AVAILABLE: モデル一覧で available:false のモデル（高価格帯のロック）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","INVALID_REQUEST","PROMPT_TOO_LONG","UNKNOWN_MODEL","CONTEXT_BUDGET_EXCEEDED","MODEL_NOT_AVAILABLE"]}},"/api/v1/debates":{"post":{"operationId":"createDebate","summary":"討論の開始（非同期）","description":"202 で受付。結果は GET /api/v1/debates/{id} をポーリングする。送り直すときは必ず同じ Idempotency-Key（24 時間有効）","security":[{"bearerAuth":[]}],"x-scope":"debates:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"冪等キー。同じキー・同じ本文の再送は同じ討論を返し、本文が違えば 409","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt","models","synthesizer"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"お題（日本語前提のプロンプト）。最大文字数を超えると 400 PROMPT_TOO_LONG"},"models":{"type":"array","minItems":2,"maxItems":5,"uniqueItems":true,"items":{"type":"string","maxLength":200},"description":"Round 1・2 に参加するモデルの ID（GET /api/v1/models の id をそのまま渡す）"},"synthesizer":{"type":"string","maxLength":200,"description":"Round 3 で統合回答を書くモデルの ID"},"mode":{"type":"string","enum":["converge","hybrid","diverge"],"default":"converge","description":"討論のモード（converge＝収束／hybrid／diverge＝発散）。省略時 converge"},"rounds":{"type":"integer","enum":[3],"default":3,"description":"ラウンド数。現在は 3 のみ"},"max_cost_jpy":{"type":"number","minimum":0.01,"description":"予算の上限（円・任意）。0.01 円未満は 400 INVALID_REQUEST（小数第 3 位以下は切り捨て）。開始時の見積もり（＝仮押さえ額）がこれを超えたら 400 BUDGET_EXCEEDED。実行中も Round 2・3 を始める前に「請求済み＋そのラウンドの見込み」と比べ、超える見込みならそのラウンドを始めずに止める（status=failed・failure.code=BUDGET_LIMIT・止めたラウンドは請求しない）。見込みとの比較なので、実行したラウンドの実請求が見込みを上回った分だけ上限を超えることはある"},"client_reference_id":{"type":"string","minLength":1,"maxLength":200,"description":"利用者側の識別子（任意）。GET /api/v1/debates で絞り込める"}}}}}},"responses":{"202":{"description":"受付済み","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Location":{"schema":{"type":"string"},"description":"/api/v1/debates/{id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebateAccepted"}}}},"400":{"description":"IDEMPOTENCY_KEY_REQUIRED: POST /api/v1/debates・POST /api/v1/debates/{id}/resume に Idempotency-Key ヘッダが無い / INVALID_REQUEST: 本文の形・型・enum 外の値・クエリの形式不正 / PROMPT_TOO_LONG: お題（prompt）が最大文字数を超えた / CONTEXT_BUDGET_EXCEEDED: お題と出力の合計が選んだモデルの文脈長に収まらない（モデルかお題を変える） / UNKNOWN_MODEL: モデル一覧に無いモデル ID（日次の同期で消えた場合を含む。GET /api/v1/models を取り直す） / MODEL_NOT_AVAILABLE: モデル一覧で available:false のモデル（高価格帯のロック） / BUDGET_EXCEEDED: 開始時の見積もりが max_cost_jpy を超えた（見積もり額を返す） / KEY_PER_RUN_CAP: 開始時の見積もりが API キーの 1 回あたりの上限を超えた","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"INSUFFICIENT_CREDITS: 組織の残高が見積もり（仮押さえ額）に足りない（チャージしてから） / KEY_MONTHLY_CAP: API キーの当月（JST の暦月）の上限に達した（翌月か上限の変更後）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND: 他組織の ID・画面から始めた討論・形式不正の ID・削除済み（すべて同じ 404）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED: 同じ Idempotency-Key で本文が違うリクエストを送った","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない） / DAILY_TRUNCATION_LIMIT_EXCEEDED: 回答の打ち切りの日次上限（Retry-After は JST の翌日 0 時まで）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","IDEMPOTENCY_KEY_REQUIRED","INVALID_REQUEST","PROMPT_TOO_LONG","CONTEXT_BUDGET_EXCEEDED","UNKNOWN_MODEL","MODEL_NOT_AVAILABLE","BUDGET_EXCEEDED","KEY_PER_RUN_CAP","INSUFFICIENT_CREDITS","KEY_MONTHLY_CAP","IDEMPOTENCY_KEY_REUSED","NOT_FOUND","DAILY_TRUNCATION_LIMIT_EXCEEDED"]},"get":{"operationId":"listDebates","summary":"討論の一覧（API で作った討論だけ・新しい順・カーソル）","description":"本文は含まない。削除済みは出ない。next_cursor を cursor に渡して続きを取る","security":[{"bearerAuth":[]}],"x-scope":"debates:read","parameters":[{"name":"status","in":"query","required":false,"description":"状態で絞る","schema":{"$ref":"#/components/schemas/DebateStatus"}},{"name":"created_after","in":"query","required":false,"description":"この日時以降（含む）。日付だけ（例 2026-10-01）は UTC の 0 時。時刻付きはオフセット（Z / ±hh:mm）が必須（/usage の from・to は JST の日付なので扱いが違う）","schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"created_before","in":"query","required":false,"description":"この日時より前。日付だけ（例 2026-10-01）は UTC の 0 時。時刻付きはオフセット（Z / ±hh:mm）が必須（/usage の from・to は JST の日付なので扱いが違う）","schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"api_key_id","in":"query","required":false,"description":"キーで絞る","schema":{"type":"string","format":"uuid"}},{"name":"client_reference_id","in":"query","required":false,"description":"利用者側の識別子で絞る（完全一致）","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"件数","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"前の応答の next_cursor","schema":{"type":"string"}}],"responses":{"200":{"description":"一覧","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DebateListItem"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"INVALID_REQUEST: 本文の形・型・enum 外の値・クエリの形式不正","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","INVALID_REQUEST"]}},"/api/v1/debates/{id}":{"get":{"operationId":"getDebate","summary":"討論の状態と結果","description":"include で返す範囲を選ぶ（既定は final_answer・status・cost）。非終端なら poll_after_seconds 秒後に取り直す","security":[{"bearerAuth":[]}],"x-scope":"debates:read","parameters":[{"name":"id","in":"path","required":true,"description":"討論の ID（UUID）。形式不正・他組織・削除済みはすべて 404","schema":{"type":"string","format":"uuid"}},{"name":"include","in":"query","required":false,"description":"カンマ区切り（responses / summary / judge / cost）。各要素の前後の空白と空要素は無視する","schema":{"type":"string","pattern":"^\\s*(responses|summary|judge|cost)?\\s*(,\\s*(responses|summary|judge|cost)?\\s*)*$"}}],"responses":{"200":{"description":"討論","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debate"}}}},"400":{"description":"INVALID_REQUEST: 本文の形・型・enum 外の値・クエリの形式不正","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND: 他組織の ID・画面から始めた討論・形式不正の ID・削除済み（すべて同じ 404）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","INVALID_REQUEST","NOT_FOUND"]},"delete":{"operationId":"deleteDebate","summary":"討論の本文の削除","description":"実行中なら中止してから本文を消す（完了済みラウンドの部分課金は残る）。削除後は GET も一覧も 404／非表示","security":[{"bearerAuth":[]}],"x-scope":"debates:write","parameters":[{"name":"id","in":"path","required":true,"description":"討論の ID（UUID）。形式不正・他組織・削除済みはすべて 404","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"削除済み","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["id","deleted","cancelled"],"properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"cancelled":{"type":"boolean"}}}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND: 他組織の ID・画面から始めた討論・形式不正の ID・削除済み（すべて同じ 404）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","NOT_FOUND"]}},"/api/v1/debates/{id}/cancel":{"post":{"operationId":"cancelDebate","summary":"討論のキャンセル","description":"202 で受付。実際に止まったかは GET の status で見る（数秒かかる）。実行中だった分の部分課金がありうる","security":[{"bearerAuth":[]}],"x-scope":"debates:write","parameters":[{"name":"id","in":"path","required":true,"description":"討論の ID（UUID）。形式不正・他組織・削除済みはすべて 404","schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"キャンセルを受け付けた","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/DebateStatus"},"cancel_requested":{"type":"boolean"},"poll_after_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}]}}}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND: 他組織の ID・画面から始めた討論・形式不正の ID・削除済み（すべて同じ 404）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"NOT_CANCELLABLE: 終端済み（completed / failed / cancelled）の討論のキャンセル","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","NOT_FOUND","NOT_CANCELLABLE"]}},"/api/v1/debates/{id}/resume":{"post":{"operationId":"resumeDebate","summary":"失敗した討論の再開（そのまま再実行・モデルの入れ替え・外して続ける）","description":"GET /api/v1/debates/{id} の resume_options が null でない討論だけ再開できる。成功したモデルの回答は引き継ぎ、失敗したモデルの分だけ実行・請求する（システム利用料は元の討論と合わせて 1 回）。元の討論の max_cost_jpy は再開した討論にも引き継ぐ。max_cost_jpy とキーの 1 回上限は元の討論からの請求済みと合わせて数え、「請求済み＋再開の見積もり」が超えるなら 400 BUDGET_EXCEEDED／KEY_PER_RUN_CAP（元の討論は再開できる状態のまま）。202 で新しい討論（子）の ID を返し、以後はその ID をポーリングする。送り直すときは必ず同じ Idempotency-Key（24 時間有効）","security":[{"bearerAuth":[]}],"x-scope":"debates:write","parameters":[{"name":"id","in":"path","required":true,"description":"討論の ID（UUID）。形式不正・他組織・削除済みはすべて 404","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"冪等キー。同じ討論・同じキー・同じ本文の再送は同じ子を返し、本文や討論が違えば 409","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"description":"すべて任意。{} なら失敗したモデルをそのまま再実行する","properties":{"replacements":{"type":"object","additionalProperties":{"type":"string","maxLength":200},"description":"{ 失敗したモデルの ID: 新しいモデルの ID }。resume_options.failed_models のモデルだけ入れ替えられる（成功したモデルは 400 REPLACEMENT_NOT_ALLOWED）。新しいモデルは GET /api/v1/models に出るもの"},"synthesizer_replacement":{"type":"string","maxLength":200,"description":"新しい統合役のモデルの ID。Round 3（統合役）で失敗したとき（synthesizer_failed）だけ"},"drop_failed":{"type":"boolean","description":"true なら失敗したモデルを外して残りで続ける（残りが 2 未満なら 400 TOO_FEW_MODELS_AFTER_DROP・統合役の失敗には使えない）。replacements・synthesizer_replacement と同時には指定できない"}}}}}},"responses":{"202":{"description":"受付済み（新しい討論）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Location":{"schema":{"type":"string"},"description":"/api/v1/debates/{新しい id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebateAccepted"}}}},"400":{"description":"IDEMPOTENCY_KEY_REQUIRED: POST /api/v1/debates・POST /api/v1/debates/{id}/resume に Idempotency-Key ヘッダが無い / INVALID_REQUEST: 本文の形・型・enum 外の値・クエリの形式不正 / REPLACEMENT_NOT_ALLOWED: 再開で、成功したモデル（または統合役が失敗していないのに synthesizer）を入れ替えようとした / DROP_NOT_ALLOWED: Round 3（統合役）の失敗で drop_failed を指定した（同じモデルで再実行するか synthesizer_replacement を使う） / TOO_FEW_MODELS_AFTER_DROP: drop_failed で外すと参加モデルが最小数未満になる（resume_options.can_drop が false） / UNKNOWN_MODEL: モデル一覧に無いモデル ID（日次の同期で消えた場合を含む。GET /api/v1/models を取り直す） / MODEL_NOT_AVAILABLE: モデル一覧で available:false のモデル（高価格帯のロック） / BUDGET_EXCEEDED: 開始時の見積もりが max_cost_jpy を超えた（見積もり額を返す） / KEY_PER_RUN_CAP: 開始時の見積もりが API キーの 1 回あたりの上限を超えた","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"INSUFFICIENT_CREDITS: 組織の残高が見積もり（仮押さえ額）に足りない（チャージしてから） / KEY_MONTHLY_CAP: API キーの当月（JST の暦月）の上限に達した（翌月か上限の変更後）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND: 他組織の ID・画面から始めた討論・形式不正の ID・削除済み（すべて同じ 404）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"NOT_RESUMABLE: 再開を待っていない討論の再開（実行中・完了・キャンセル済み・すでに再開した討論。resume_options が null の討論） / IDEMPOTENCY_KEY_REUSED: 同じ Idempotency-Key で本文が違うリクエストを送った","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない） / DAILY_TRUNCATION_LIMIT_EXCEEDED: 回答の打ち切りの日次上限（Retry-After は JST の翌日 0 時まで）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","IDEMPOTENCY_KEY_REQUIRED","INVALID_REQUEST","NOT_FOUND","NOT_RESUMABLE","REPLACEMENT_NOT_ALLOWED","DROP_NOT_ALLOWED","TOO_FEW_MODELS_AFTER_DROP","UNKNOWN_MODEL","MODEL_NOT_AVAILABLE","BUDGET_EXCEEDED","KEY_PER_RUN_CAP","INSUFFICIENT_CREDITS","KEY_MONTHLY_CAP","IDEMPOTENCY_KEY_REUSED","DAILY_TRUNCATION_LIMIT_EXCEEDED"]}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"期間の回数と請求額（キー別・日別）","description":"API で作った討論だけ。期間は JST の日付で両端を含む（最大 366 日）。省略時は当月","security":[{"bearerAuth":[]}],"x-scope":"usage:read","parameters":[{"name":"from","in":"query","required":false,"description":"開始日（JST・YYYY-MM-DD）。to と両方指定","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"終了日（JST・YYYY-MM-DD・含む）","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","required":false,"description":"束ね方","schema":{"type":"string","enum":["api_key","day"],"default":"api_key"}}],"responses":{"200":{"description":"利用量（円）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["currency","from","to","group_by","total","groups"],"properties":{"currency":{"type":"string","const":"JPY"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"group_by":{"type":"string","enum":["api_key","day"]},"total":{"$ref":"#/components/schemas/UsageBucket"},"groups":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/UsageGroupByKey"},{"$ref":"#/components/schemas/UsageGroupByDay"}]}}}}}}},"400":{"description":"INVALID_REQUEST: 本文の形・型・enum 外の値・クエリの形式不正","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: キーが無い・形式が違う・失効・期限切れ（理由は区別しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE: 有効なキーだがスコープが足りない","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: 認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR: 想定外のエラー（request_id を添えて問い合わせ）","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE: ジョブの受付・DB の一時的な障害","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-error-codes":["UNAUTHORIZED","RATE_LIMITED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR","INSUFFICIENT_SCOPE","INVALID_REQUEST"]}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"この仕様（認証不要）","security":[],"x-scope":null,"parameters":[],"responses":{"200":{"description":"OpenAPI 3.1 の JSON","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object"}}}}},"x-error-codes":[]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer dcx_live_…（組織の管理画面で発行）"}},"headers":{"X-Request-Id":{"description":"リクエストの ID（エラー本文の request_id と同じ）","schema":{"type":"string"}},"Retry-After":{"description":"再試行までの秒数。同時実行上限の場合は再確認の目安で、通過は保証されません。","schema":{"type":"integer","minimum":1}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"日本語の説明（表示してよい）"},"request_id":{"type":"string","description":"X-Request-Id ヘッダと同じ値。問い合わせ時に添える"},"status_page_url":{"type":"string","format":"uri","description":"503 のときだけ付く稼働状況ページの URL（公開前は付かない）"}},"additionalProperties":true,"description":"code によっては補足（models・estimate_jpy・max_cost_jpy・cap_jpy 等）が付く"}}},"ErrorCode":{"type":"string","enum":["INVALID_REQUEST","IDEMPOTENCY_KEY_REQUIRED","PROMPT_TOO_LONG","CONTEXT_BUDGET_EXCEEDED","UNKNOWN_MODEL","MODEL_NOT_AVAILABLE","BUDGET_EXCEEDED","KEY_PER_RUN_CAP","UNAUTHORIZED","INSUFFICIENT_SCOPE","INSUFFICIENT_CREDITS","KEY_MONTHLY_CAP","NOT_FOUND","IDEMPOTENCY_KEY_REUSED","NOT_CANCELLABLE","NOT_RESUMABLE","REPLACEMENT_NOT_ALLOWED","DROP_NOT_ALLOWED","TOO_FEW_MODELS_AFTER_DROP","NOT_DELETABLE","RATE_LIMITED","DAILY_TRUNCATION_LIMIT_EXCEEDED","INTERNAL_ERROR","TEMPORARILY_UNAVAILABLE"],"description":"機械向けの固定値。未知の code は HTTP ステータスで扱う（コードは追加されうる）"},"Estimate":{"type":"object","required":["total_jpy","system_fee_jpy","ai_token_jpy"],"properties":{"total_jpy":{"type":"number","description":"見積もりの合計＝仮押さえ額（円）"},"system_fee_jpy":{"type":"number","description":"システム利用料（1 回 15 円）（円）"},"ai_token_jpy":{"type":"number","description":"AI トークン料の見積もり（円）"}}},"DebateStatus":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"5 値で固定（増やさない）。completed / failed / cancelled が終端"},"Cost":{"type":"object","required":["currency","total_jpy","system_fee_jpy","ai_token_jpy","by_round","by_model","final"],"properties":{"currency":{"type":"string","const":"JPY"},"total_jpy":{"type":"number","description":"実際に組織の残高から引いた額（円）"},"system_fee_jpy":{"type":"number","description":"システム利用料（成功ラウンドが 0 なら 0）（円）"},"ai_token_jpy":{"type":"number","description":"AI トークン料（円）"},"by_round":{"type":"array","items":{"type":"object","properties":{"round":{"type":"integer"},"ai_token_jpy":{"type":"number","description":"そのラウンドの AI トークン料（円）"}}}},"by_model":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"ai_token_jpy":{"type":"number","description":"そのモデルの AI トークン料（円）"}}}},"final":{"type":"boolean","description":"確定したか（終端なら true）"}}},"DebateAccepted":{"type":"object","required":["id","status","created_at","reserved_jpy","estimate","poll_after_seconds"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/DebateStatus"},"created_at":{"type":"string","format":"date-time","description":"作成日時"},"reserved_jpy":{"type":"number","description":"仮押さえ額（円）"},"estimate":{"$ref":"#/components/schemas/Estimate"},"client_reference_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"poll_after_seconds":{"anyOf":[{"type":"integer","description":"最初のポーリングまでの目安の秒数（30 秒）。終端なら null"},{"type":"null"}]}}},"DebateResponse":{"type":"object","properties":{"round":{"type":"integer"},"model":{"type":"string"},"status":{"type":"string","enum":["completed","failed","timeout","truncated","cancelled","running"]},"content":{"anyOf":[{"type":"string","description":"本文（Markdown）。completed 以外は null"},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"charge_jpy":{"type":"number","description":"この行の請求額（失敗した行は 0）（円）"}}},"Debate":{"type":"object","required":["id","status","mode","models","synthesizer","api_key_id","client_reference_id","created_at","started_at","completed_at","reserved_jpy","progress","poll_after_seconds","final_answer","failure","resume_options","cost"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/DebateStatus"},"mode":{"type":"string","enum":["converge","hybrid","diverge"]},"models":{"type":"array","items":{"type":"string"}},"synthesizer":{"type":"string"},"api_key_id":{"type":"string","format":"uuid"},"client_reference_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","description":"作成日時"},"started_at":{"anyOf":[{"type":"string","format":"date-time","description":"実行開始日時"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time","description":"終端日時"},{"type":"null"}]},"reserved_jpy":{"type":"number","description":"仮押さえ額（円）"},"progress":{"anyOf":[{"type":"object","properties":{"current_round":{"type":"integer","minimum":1,"maximum":3}},"description":"running のときだけ"},{"type":"null"}]},"poll_after_seconds":{"anyOf":[{"type":"integer","description":"次のポーリングまでの目安の秒数（15 秒）。終端なら null"},{"type":"null"}]},"final_answer":{"anyOf":[{"type":"string","description":"統合回答（Markdown）。completed のときだけ"},{"type":"null"}]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["SYSTEM_ERROR","MODEL_FAILURE","BUDGET_LIMIT","INSUFFICIENT_CREDITS"],"description":"BUDGET_LIMIT: 次のラウンドを始めると請求済み＋その見込みが max_cost_jpy かキーの 1 回上限を超えるため、そのラウンドを始めずに止めた。INSUFFICIENT_CREDITS: 組織の残高が次のラウンドの見込みに足りないため止めた。どちらも止めたラウンドは請求しない"},"retryable":{"type":"boolean","description":"新しい討論として出し直してよいか"}},"description":"failed のときだけ"},{"type":"null"}]},"resume_options":{"anyOf":[{"$ref":"#/components/schemas/ResumeOptions"},{"type":"null"}]},"cost":{"$ref":"#/components/schemas/Cost"},"responses":{"type":"array","items":{"$ref":"#/components/schemas/DebateResponse"},"description":"include=responses のとき。実行された各ラウンド・各モデルの最後の試行を 1 行ずつ。未実行のモデルの行は返さない"},"summary":{"type":"object","description":"include=summary のとき。オブジェクトを返し、未生成のラウンドは round1 または round2 が null になる","properties":{"round1":{"anyOf":[{"type":"object"},{"type":"null"}]},"round2":{"anyOf":[{"type":"object"},{"type":"null"}]}}},"judge":{"type":"object","description":"include=judge のとき。完了後に別ジョブで入る。審査は保証しないため done にならないことがある。pending は完了から 10 分以内の待ちだけで、審査が失敗・スキップされたとき、または完了から 10 分たっても結果が無いときは skipped。ただし審査が遅れて届いた場合は、skipped の後で done に変わることがある（skipped を「スコアが無い」と確定させない）。完了していない討論は skipped（ポーリングの終了条件には status を使う）。scores は done のときだけ入る。scores のキーは axes で決まる（converge と diverge は同じキーで集計しない）","properties":{"judge_status":{"type":"string","enum":["pending","done","skipped"]},"executed_at":{"anyOf":[{"type":"string","format":"date-time","description":"審査日時"},{"type":"null"}]},"axes":{"type":"string","enum":["converge","diverge"],"description":"scores の軸の体系。mode が diverge なら diverge、それ以外は converge"},"scores":{"anyOf":[{"oneOf":[{"type":"object","title":"converge","description":"axes = converge のとき。各値は 0〜10（未採点の軸は null）","properties":{"domain_alignment":{"anyOf":[{"type":"number"},{"type":"null"}]},"perspective_diversity":{"anyOf":[{"type":"number"},{"type":"null"}]},"rationale_explicitness":{"anyOf":[{"type":"number"},{"type":"null"}]},"critique_independence":{"anyOf":[{"type":"number"},{"type":"null"}]},"r1_information_gain":{"anyOf":[{"type":"number"},{"type":"null"}]},"r3_true_integration":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["domain_alignment","perspective_diversity","rationale_explicitness","critique_independence","r1_information_gain","r3_true_integration"],"additionalProperties":false},{"type":"object","title":"diverge","description":"axes = diverge のとき。各値は 0〜10（未採点の軸は null）","properties":{"idea_concreteness":{"anyOf":[{"type":"number"},{"type":"null"}]},"idea_diversity":{"anyOf":[{"type":"number"},{"type":"null"}]},"precondition_explicitness":{"anyOf":[{"type":"number"},{"type":"null"}]},"idea_originality":{"anyOf":[{"type":"number"},{"type":"null"}]},"option_gain":{"anyOf":[{"type":"number"},{"type":"null"}]},"portfolio_usability":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["idea_concreteness","idea_diversity","precondition_explicitness","idea_originality","option_gain","portfolio_usability"],"additionalProperties":false}]},{"type":"null"}]}}}}},"ResumeOptions":{"type":"object","description":"失敗した討論を POST /api/v1/debates/{id}/resume で再開するときに選べること。再開を待っていない討論（実行中・完了・キャンセル済み・再開済み・再開できない失敗）は null","required":["failed_round","failed_models","synthesizer_failed","can_retry_same","can_replace","can_drop","retry_same_likely_fails"],"properties":{"failed_round":{"type":"integer","enum":[1,2,3],"description":"失敗したラウンド"},"failed_models":{"type":"array","items":{"type":"string"},"description":"失敗した参加モデル（Round 1・2）。統合役の失敗（Round 3）では空"},"synthesizer_failed":{"type":"boolean","description":"Round 3（統合役）の失敗か"},"can_retry_same":{"type":"boolean","description":"失敗したモデルをそのまま再実行できるか（本文 {}）"},"can_replace":{"type":"boolean","description":"失敗したモデルを別のモデルに替えて再実行できるか（replacements・synthesizer_replacement）"},"can_drop":{"type":"boolean","description":"失敗したモデルを外して残りで続けられるか（drop_failed。残りが 2 以上のときだけ）"},"retry_same_likely_fails":{"type":"boolean","description":"同じモデルの再実行はまた失敗しやすいか（回答の打ち切り等）。true なら入れ替えを勧める。failure.code=BUDGET_LIMIT の討論は常に true（max_cost_jpy とキーの 1 回上限は元の討論からの請求済みと合わせて数えるため、同じモデルの再開は同じ上限で 400 BUDGET_EXCEEDED / KEY_PER_RUN_CAP になる。max_cost_jpy は再開で変えられない）"}}},"DebateListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/DebateStatus"},"mode":{"type":"string","enum":["converge","hybrid","diverge"]},"models":{"type":"array","items":{"type":"string"}},"synthesizer":{"type":"string"},"api_key_id":{"type":"string","format":"uuid"},"client_reference_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","description":"作成日時"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","description":"終端日時"},{"type":"null"}]},"cost":{"type":"object","properties":{"currency":{"type":"string","const":"JPY"},"total_jpy":{"type":"number","description":"請求額（円）"},"final":{"type":"boolean"}}}}},"LimitWithCurrent":{"type":"object","properties":{"limit":{"type":"integer"},"current":{"type":"integer"},"resets_at":{"type":"string","format":"date-time","description":"JST の翌日 0 時"}}},"UsageBucket":{"type":"object","required":["debates","system_fee_jpy","ai_token_jpy","total_jpy"],"properties":{"debates":{"type":"integer","description":"期間内に開始した討論の本数"},"system_fee_jpy":{"type":"number","description":"システム利用料（円）"},"ai_token_jpy":{"type":"number","description":"AI トークン料（円）"},"total_jpy":{"type":"number","description":"請求額の合計（円）"}}},"UsageGroupByKey":{"allOf":[{"$ref":"#/components/schemas/UsageBucket"},{"type":"object","required":["api_key"],"properties":{"api_key":{"type":"object","required":["id","name","prefix","revoked"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"revoked":{"type":"boolean"}}}}}]},"UsageGroupByDay":{"allOf":[{"$ref":"#/components/schemas/UsageBucket"},{"type":"object","required":["day"],"properties":{"day":{"type":"string","format":"date"}}}]}}},"x-error-codes":[{"code":"INVALID_REQUEST","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"リクエストの内容が不正です。","when":"本文の形・型・enum 外の値・クエリの形式不正"},{"code":"IDEMPOTENCY_KEY_REQUIRED","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"Idempotency-Key ヘッダを指定してください。","when":"POST /api/v1/debates・POST /api/v1/debates/{id}/resume に Idempotency-Key ヘッダが無い"},{"code":"PROMPT_TOO_LONG","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"お題が長すぎます。","when":"お題（prompt）が最大文字数を超えた"},{"code":"CONTEXT_BUDGET_EXCEEDED","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"お題が選んだモデルの扱える長さに収まりません。モデルかお題を変えてください。","when":"お題と出力の合計が選んだモデルの文脈長に収まらない（モデルかお題を変える）"},{"code":"UNKNOWN_MODEL","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"指定されたモデルは利用できません。モデルの一覧を取り直してください。","when":"モデル一覧に無いモデル ID（日次の同期で消えた場合を含む。GET /api/v1/models を取り直す）"},{"code":"MODEL_NOT_AVAILABLE","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"指定されたモデルはこの組織では利用できません。","when":"モデル一覧で available:false のモデル（高価格帯のロック）"},{"code":"BUDGET_EXCEEDED","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"見積もりが指定された予算を超えています。","when":"開始時の見積もりが max_cost_jpy を超えた（見積もり額を返す）"},{"code":"KEY_PER_RUN_CAP","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"見積もりがこの API キーの 1 回の上限を超えています。","when":"開始時の見積もりが API キーの 1 回あたりの上限を超えた"},{"code":"UNAUTHORIZED","status":401,"retry":"no","retry_description":"再試行しない（直してから）","message":"API キーが無効です。正しいキーを Authorization: Bearer で指定してください。","when":"キーが無い・形式が違う・失効・期限切れ（理由は区別しない）"},{"code":"INSUFFICIENT_SCOPE","status":403,"retry":"no","retry_description":"再試行しない（直してから）","message":"この API キーにはこの操作の権限（スコープ）がありません。","when":"有効なキーだがスコープが足りない"},{"code":"INSUFFICIENT_CREDITS","status":402,"retry":"no","retry_description":"再試行しない（直してから）","message":"組織の残高が不足しています。","when":"組織の残高が見積もり（仮押さえ額）に足りない（チャージしてから）"},{"code":"KEY_MONTHLY_CAP","status":402,"retry":"no","retry_description":"再試行しない（直してから）","message":"この API キーの今月の利用上限に達しました。","when":"API キーの当月（JST の暦月）の上限に達した（翌月か上限の変更後）"},{"code":"NOT_FOUND","status":404,"retry":"no","retry_description":"再試行しない（直してから）","message":"見つかりません。","when":"他組織の ID・画面から始めた討論・形式不正の ID・削除済み（すべて同じ 404）"},{"code":"IDEMPOTENCY_KEY_REUSED","status":409,"retry":"no","retry_description":"再試行しない（直してから）","message":"同じ Idempotency-Key が別の内容のリクエストで使われています。","when":"同じ Idempotency-Key で本文が違うリクエストを送った"},{"code":"NOT_CANCELLABLE","status":409,"retry":"no","retry_description":"再試行しない（直してから）","message":"この討論は終了しているためキャンセルできません。","when":"終端済み（completed / failed / cancelled）の討論のキャンセル"},{"code":"NOT_RESUMABLE","status":409,"retry":"no","retry_description":"再試行しない（直してから）","message":"この討論は再開できる状態ではありません。","when":"再開を待っていない討論の再開（実行中・完了・キャンセル済み・すでに再開した討論。resume_options が null の討論）"},{"code":"REPLACEMENT_NOT_ALLOWED","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"入れ替えられるのは失敗したモデルだけです。","when":"再開で、成功したモデル（または統合役が失敗していないのに synthesizer）を入れ替えようとした"},{"code":"DROP_NOT_ALLOWED","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"統合役（Round 3）の失敗では、失敗したモデルを外して続けることはできません。","when":"Round 3（統合役）の失敗で drop_failed を指定した（同じモデルで再実行するか synthesizer_replacement を使う）"},{"code":"TOO_FEW_MODELS_AFTER_DROP","status":400,"retry":"no","retry_description":"再試行しない（直してから）","message":"失敗したモデルを外すと参加モデルが足りなくなるため、続けられません。","when":"drop_failed で外すと参加モデルが最小数未満になる（resume_options.can_drop が false）"},{"code":"NOT_DELETABLE","status":409,"retry":"no","retry_description":"再試行しない（直してから）","message":"実行中の討論は削除できません。先にキャンセルしてください。","when":"予約（現在は返さない）。実行中の討論の DELETE は、画面の削除と同じく中止してから本文を消す","reserved":true},{"code":"RATE_LIMITED","status":429,"retry":"after_retry_after","retry_description":"Retry-After 秒後に再試行してよい（POST /debates・POST /debates/{id}/resume は同じ Idempotency-Key で）","message":"リクエストが多すぎます。しばらく待ってから再度お試しください。","when":"認証失敗・リクエスト数・作成数・同時実行数の上限（同時実行の Retry-After は再確認の目安であり通過を保証しない）"},{"code":"DAILY_TRUNCATION_LIMIT_EXCEEDED","status":429,"retry":"after_retry_after","retry_description":"Retry-After 秒後に再試行してよい（POST /debates・POST /debates/{id}/resume は同じ Idempotency-Key で）","message":"回答の打ち切りが本日の上限に達しました。日本時間の翌日 0 時以降に再度お試しください。","when":"回答の打ち切りの日次上限（Retry-After は JST の翌日 0 時まで）"},{"code":"INTERNAL_ERROR","status":500,"retry":"same_idempotency_key","retry_description":"GET はいつでも、POST /debates・POST /debates/{id}/resume は同じ Idempotency-Key でのみ再試行してよい","message":"サーバーでエラーが発生しました。","when":"想定外のエラー（request_id を添えて問い合わせ）"},{"code":"TEMPORARILY_UNAVAILABLE","status":503,"retry":"after_retry_after","retry_description":"Retry-After 秒後に再試行してよい（POST /debates・POST /debates/{id}/resume は同じ Idempotency-Key で）","message":"一時的に利用できません。しばらく待ってから再度お試しください。","when":"ジョブの受付・DB の一時的な障害"}],"x-polling":{"first_poll_after_seconds":30,"poll_interval_seconds":15,"suggested_max_wait_minutes":30}}