API ドキュメント

DebateCross API v1 クイックスタート

• 機械可読な仕様（OpenAPI 3.1）: openapi.json
• 稼働状況: https://status.debatecross.com

DebateCross は、複数の AI に同じお題を考えさせ（Round 1）、互いの回答を批評させ（Round 2）、 選んだ 1 つの AI が全体を統合した最終回答を書く（Round 3）サービスです。API でも画面と同じ経路で討論を実行し、 組織の残高から画面と同じ料金で精算します。

1. API キーを作る

1. 組織の owner か admin が https://app.debatecross.com/org を開き、「API キー」を選ぶ。
2. 名前・権限（スコープ）・上限（月の上限と 1 回の上限。円・「無制限」も可）を決めて発行する。
3. キーの全文は発行した直後に 1 回だけ表示されます。 あとから確認できないので、秘密情報の保管庫などに保存してください。 画面の一覧には先頭（dcx_live_ab12cd34…）だけが出ます。

• GET /api/v1/me はスコープなしでも呼べます（キーの状態を確かめる用）。
• キーは組織に属します（作った人が組織を抜けても使えます）。API は組織だけが使えます（個人のアカウントでは発行できません）。
• キーの入れ替え: 新しいキーを発行 → 自社のシステムを切り替え → 古いキーを画面で取り消し。同じ組織で複数のキーを同時に有効にできます。
• 有効なキーは 1 組織 10 本までです（取り消していないキー。期限切れのキーも取り消すまで数えます）。上限に達すると画面の発行ボタンが止まるので、 使っていないキーを取り消してから発行してください。10 本を超えて必要なときは運営にご相談ください（組織ごとに変更できます）。 現在の本数と上限は GET /me の limits.org_api_keys で確かめられます。 取り消しは即時に効きます（以後 401）。そのキーで実行中・待機中の討論もキャンセルします（完了したラウンドの分は請求されます）。キーの発行・取り消しは API からはできません（流出したキーで新しいキーを作らせないため）。
• サーバー間の呼び出し専用です。ブラウザの JavaScript から直接呼ばないでください（CORS ヘッダを返しません。キーが漏れます）。

以下の例では、キーを環境変数に入れておきます。

export DCX_API_KEY='dcx_live_…'   # 発行時に表示された全文
export DCX='https://app.debatecross.com/api/v1'

2. 最初の 4 回の呼び出し

2.1 キーの状態と制限値を見る（GET /me）

curl -s "$DCX/me" -H "Authorization: Bearer $DCX_API_KEY"

キーの名前・スコープ・所属組織、当月の使用額と上限（spend）、制限値と現在値（limits）が返ります。 403・402 のときは、有効なキーで /me を呼ぶとスコープと上限を確認できます。 401 のキーでは /me も 401 になります。保管したキーの全文を確認し、取り消し・有効期限は組織の管理画面で確認してください。

2.2 使えるモデルを見る（GET /models）

curl -s "$DCX/models" -H "Authorization: Bearer $DCX_API_KEY"

各モデルの id を、討論の models[]・synthesizer にそのまま渡します。 available: false のモデル（高価格帯）は、組織がまだ一度もチャージしていないと使えません。 一覧は日次で更新され、提供元で廃止されたモデルは翌日から消えます（消えた ID で開始すると 400 UNKNOWN_MODEL）。

2.3 見積もる（POST /estimates・課金されません）

curl -s "$DCX/estimates" \
  -H "Authorization: Bearer $DCX_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "prompt": "社内の問い合わせ対応に生成 AI を導入する際の主なリスクと対策は？",
    "models": ["anthropic/claude-3-haiku", "openai/gpt-4o-mini"],
    "synthesizer": "google/gemini-2.0-flash-001"
  }'

{ "currency": "JPY", "estimate": { "total_jpy": 18.4, "system_fee_jpy": 15, "ai_token_jpy": 3.4 }, "per_run_cap_jpy": 500 }

（金額は例です。）total_jpy が、開始したときに組織の残高から仮押さえされる額です。 本文の形は開始と同じで、開始と同じ検査（文字数・モデル・文脈長）を通ります。

2.4 討論を始めて結果を取る（POST /debates → GET /debates/{id}）

送信前に冪等キーを一度だけ作ります（新しい討論を始めるときだけ実行します）。

export DCX_IDEMPOTENCY_KEY=$(uuidgen)

続けて送信します。応答が届かず再送するときは、キーを作り直さずに次のコマンドだけをもう一度実行します。

curl -s -i "$DCX/debates" \
  -H "Authorization: Bearer $DCX_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $DCX_IDEMPOTENCY_KEY" \
  -d '{
    "prompt": "社内の問い合わせ対応に生成 AI を導入する際の主なリスクと対策は？",
    "models": ["anthropic/claude-3-haiku", "openai/gpt-4o-mini"],
    "synthesizer": "google/gemini-2.0-flash-001",
    "max_cost_jpy": 50,
    "client_reference_id": "ticket-20261029-001"
  }'

202 Accepted で、すぐに次が返ります（討論はサーバー側で非同期に進みます）。

{ "id": "…", "status": "queued", "created_at": "…", "reserved_jpy": 18.4,
  "estimate": { "total_jpy": 18.4, "system_fee_jpy": 15, "ai_token_jpy": 3.4 },
  "client_reference_id": "ticket-20261029-001", "poll_after_seconds": 30 }

結果は GET /debates/{id} で取ります。

curl -s "$DCX/debates/<id>?include=responses,summary" -H "Authorization: Bearer $DCX_API_KEY"

• 添付ファイル・続き討論・Solo Action・お題の事前整理（Idea Refiner）は API では使えません。
• 出力は Markdown のテキストです。討論のプロンプトは日本語を前提にしています（英語のお題で何語の回答が返るかは未確認です）。

3. ポーリングの作法

• 討論は数分（実測 4〜6 分）かかります。開始から 30 秒後に 1 回目、以後 15 秒ごとに GET /debates/{id} を呼んでください。 応答の poll_after_seconds（非終端のときだけ入る）が目安で、混雑時に延びることがあります。
• status は次の 5 つだけです（この 5 つから増やしません）。completed・failed・cancelled が終端です。

• 待つ上限の目安は 30 分です。動きの止まった討論はサーバー側で回収して終端にするので、待つのをやめても後で GET すれば終端の状態と請求額が分かります。 利用者側で待つのをやめても、サーバー側の実行と課金は止まりません。止めたいときは POST /debates/{id}/cancel を呼んでください （202 で受け付け、数秒で止まります。止まったかは GET の status で確かめます。終端済みは 409 NOT_CANCELLABLE）。
• include で返す範囲を選べます（カンマ区切り）。既定は final_answer・status・cost。

• 討論全体が completed でも、一部の AI が失敗していることがあります（その場合も final_answer は返ります）。

3.1 失敗した討論の再開（POST /debates/{id}/resume）

一部のモデルが失敗して failed になった討論は、成功したモデルの回答を引き継いだまま、失敗したモデルの分だけやり直せます （最初から出し直すより安く・速く済みます。システム利用料は元の討論と合わせて 1 回です）。 再開できるかと選べることは GET /debates/{id} の resume_options に入っています（再開できない討論は null）。

"resume_options": { "failed_round": 1, "failed_models": ["openai/gpt-4o-mini"], "synthesizer_failed": false,
  "can_retry_same": true, "can_replace": true, "can_drop": true, "retry_same_likely_fails": false }

export DCX_RESUME_KEY=$(uuidgen)
curl -s -i "$DCX/debates/<id>/resume" \
  -H "Authorization: Bearer $DCX_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $DCX_RESUME_KEY" \
  -d '{ "replacements": { "openai/gpt-4o-mini": "google/gemini-2.0-flash-001" } }'

• 202 Accepted で新しい討論の ID が返ります（形は POST /debates と同じ）。以後はその ID をポーリングしてください。元の討論は failed のまま残り、resume_options は null になります。
• Idempotency-Key は必須です（POST /debates と同じ扱い。同じ討論・同じキー・同じ本文の再送は同じ新しい討論を返します）。
• 入れ替えられるのは失敗したモデルだけです（成功したモデルを指定すると 400 REPLACEMENT_NOT_ALLOWED）。新しいモデルは GET /models に出るものだけ（無ければ 400 UNKNOWN_MODEL）。
• replacements・synthesizer_replacement と drop_failed は同時に指定できません（400 INVALID_REQUEST）。
• 元の討論の max_cost_jpy は新しい討論にも引き継がれます。max_cost_jpy とキーの 1 回の上限は元の討論からの請求済みと合わせて数え、「請求済み＋再開の見積もり」が超えるなら 400 BUDGET_EXCEEDED / KEY_PER_RUN_CAP（元の討論は再開できる状態のまま）。BUDGET_LIMIT で止まった討論は、同じモデルのままでは同じ上限に掛かるため retry_same_likely_fails: true になります。止めた原因がキーの 1 回の上限ならキーの上限を上げると再開できますが、max_cost_jpy は再開で変えられないので、max_cost_jpy が原因なら安いモデルへの入れ替えで見積もりが収まる場合を除き、POST /debates で新しい討論を始めてください。
• 再開できない状態（実行中・完了・すでに再開した等）は 409 NOT_RESUMABLE。直前のラウンドの精算中は 503 TEMPORARILY_UNAVAILABLE（Retry-After 秒後に同じキーで）。
• お題そのものを直したいときは、再開ではなく POST /debates で新しい討論を始めてください。

4. 冪等キー（Idempotency-Key）

• POST /debates・POST /debates/{id}/resume には Idempotency-Key ヘッダが必須です（無ければ 400 IDEMPOTENCY_KEY_REQUIRED）。空白を含まない ASCII で 255 文字まで。新しい討論ごとに UUID を作るのが簡単です。
• 同じキー・同じ本文で送り直すと、新しい討論を作らずに最初の討論を返します（24 時間有効）。同じキーで本文が違えば 409 IDEMPOTENCY_KEY_REUSED。
• 応答が受け取れなかった（タイムアウト・通信断・500・503）ときは、上の DCX_IDEMPOTENCY_KEY を変えずに同じリクエストを送り直してください。 これが二重に討論を作らず二重に課金しない唯一の方法です。
• status: failed を確認して新しく出し直すときは、新しい冪等キーを使ってください。同じキーでは 24 時間、失敗した討論が返ります。
• 24 時間を過ぎた同じキーの再送は新しい討論を作り、課金される場合があります。再送前に一覧で確認してください。
• 24 時間を過ぎた・キーをなくした場合は、GET /debates?client_reference_id=… で探せます。
• 討論を削除した後に同じ冪等キーで送り直すと、24 時間は 404 NOT_FOUND を返します（削除した討論の存在を認めないため）。作り直すときは新しい冪等キーで送ってください。

5. 料金の見方

• すべて円の請求額です（原価の USD は返しません）。 請求額 = システム利用料（討論 1 回 15 円）＋ AI トークン料。
• GET /models の pricing.input_jpy_per_1m / output_jpy_per_1m は 1M トークンあたりの請求単価（為替込みの目安）です。 正確な額は POST /estimates で確かめてください。
• 開始時に見積もり額を組織の残高から仮押さえし、各ラウンドの完了で実際の額を精算して残りを戻します（GET /balance の reserved_jpy）。
• 討論の cost: total_jpy（実際に組織の残高から引いた額）・system_fee_jpy（システム利用料）・ai_token_jpy（AI トークン料）・by_round[]・by_model[]・final（確定したか）。
• 期間の集計は GET /usage?from=YYYY-MM-DD&to=YYYY-MM-DD&group_by=api_key|day（JST の日付・両端を含む・最大 366 日。省略時は当月）。
• 日別集計では、回数は討論を開始した日、金額は課金された日（いずれも JST）に計上します。
• 残高は GET /balance（available_jpy が新しい討論に使える額。有効期限の切れた分は含みません）。チャージ・領収書は管理画面から。 自動チャージを有効にしておくと残高切れを防げます。

6. 制限値

固定値は GET /me の limits（と openapi.json の maxLength 等）、現在値も GET /me で取れます。

• 429・503 には Retry-After（秒）が付きます。その秒数だけ待ってから送り直してください。同時実行上限の場合は 15 秒が再確認の目安であり、その時点で枠が空く保証はありません。
• X-RateLimit-* ヘッダは返しません（正確な残りは GET /me）。

7. エラー

{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "組織の残高が不足しています。", "request_id": "req_…" } }

• code は機械向けの固定値、message は日本語（そのまま表示してよい）。
• すべての応答に X-Request-Id ヘッダが付きます（エラー本文の request_id と同じ）。問い合わせの際に添えてください。
• 「再試行」は、同じリクエストをそのまま送り直してよいかです。GET はいつでも送り直してかまいません。
• 一覧は openapi.json の x-error-codes にも同じものがあります（各エンドポイントが返しうるコードは各操作の x-error-codes）。

• 未知の code が返ってきたら HTTP ステータスで扱ってください（コードは追加されることがあります）。

8. 一覧・削除

• GET /debates?status=&created_after=&created_before=&api_key_id=&client_reference_id=&limit=&cursor=: その組織が API で作った討論だけを新しい順に返します（本文は入りません）。limit は既定 20・最大 100。 has_more: true なら next_cursor を cursor に渡して続きを取ります。メンバーが画面で始めた討論は出ません。
• 同じ組織の別のキーで作った API の討論も、必要なスコープを持つキーで取得・キャンセル・削除できます。
• DELETE /debates/{id}: 討論の本文を消します。実行中なら中止してから消します（完了したラウンドの課金は残ります）。 削除後は GET も一覧も 404／非表示になります。

9. データの扱い

• 入力・出力は画面の討論と同じく保存され、DELETE で本文を消せます。
• DebateCross が入力を AI の学習に使うことはありません。AI の提供元へはデータ収集を拒否する設定で送っています （提供元側の保持方針は各社のポリシーに従います。保持ゼロ（ZDR）はお約束していません）。

10. 時刻・月の区切り

• 時刻はすべて ISO 8601（オフセット付き）。
• キーの月の上限・利用量の「月」・打ち切りの「日」は JST（日本時間） で区切ります。

11. 互換の方針（v1）

• /api/v1 の中では、互換を壊さない変更だけを予告なく行います: フィールドの追加・include の値の追加・エラーの code の追加。 利用者側では、知らないフィールドは無視し、知らない code は HTTP ステータスで扱ってください。
• 討論の status の値は増やしません（終端の判定が壊れるため）。互換を壊す変更が必要になったら /api/v2 として出します。
• /api/v1 を廃止する場合は、告知から少なくとも 6 か月は維持します（セキュリティ・法令・提供元の都合による緊急の停止を除く）。予告期間中は全応答に Deprecation・Sunset ヘッダを付けます（現時点で廃止の予定はありません）。
• AI モデルの廃止は提供元の都合で起き、事前の予告はできません。廃止されたモデルは翌日から GET /models に出なくなり、 その ID での開始は 400 UNKNOWN_MODEL になります。既に作った討論の結果には、モデル ID がそのまま残ります。

12. 稼働状況

• 障害・メンテナンスの告知は稼働状況ページ https://status.debatecross.com で行います（アプリ・API・AI 提供元の 3 区分と直近 90 日の稼働率・お知らせ）。 機械向けには GET https://status.debatecross.com/status.json で同じ内容を取れます。

• 503 TEMPORARILY_UNAVAILABLE の本文にも、error.status_page_url として同じ URL が入ります。

• 機械的に確かめたいときは GET https://app.debatecross.com/api/status（認証不要）を使えます。 返すのは全体と区分ごとの状態だけです。

  コピー

  { "status": "ok", "components": { "app": "ok", "api": "ok", "ai_provider": "ok" }, "checked_at": "2026-10-29T00:00:00.000Z" }

  値は ok（正常）／degraded（一部に問題）／down（停止）。アプリが停止しているときは HTTP 503 です。 応答は 30 秒キャッシュされます。1 分間に 30 回までです（超えると 429）。数分に 1 回程度の確認で足ります。

• AI の提供元（OpenRouter・各モデルの提供元）の障害は DebateCross 側では制御できません。区分 ai_provider は DebateCross から OpenRouter へ届くかだけを見ており、個々のモデルの障害までは表しません。

13. 料金のかからない試し方

• 課金されない試験用の環境（sandbox キー）はありません。
• 形の確認は POST /estimates（課金されません）で足ります。実際に動かすときは、 1 回の上限 ¥100・月の上限 ¥1,000 などの小さな上限のキーを発行し、安いモデル 2 つで試してください。