Skip to main content
Decisions (Beta)

Decision の作成

カスタムコンテキスト（state）または Session の直近のコンテキストに基づき、構造化された判定を同期的に実行します。

Decision API は現在 Beta 機能です。インターフェイス定義、レスポンス構造、動作は今後のバージョンで変更される可能性があります。ドキュメントの更新を確認し、本番環境で使用する前に互換性を検証してください。
POST /api/v1/forward/decisions

リクエストヘッダー

Header必須説明
AuthorizationはいBearer <PAT or SAT>。管理者および Identity レベルの SAT をサポートします。
Content-Typeはいapplication/json。
Idempotency-Keyいいえ同じ論理操作を再試行する際は元の値を再利用します。先頭・末尾の空白を除去した後で 1～256 バイト、制御文字なしとし、重複して指定することはできません。
現在、追加の Beta リクエストヘッダーは不要です。この API はクエリパラメーターを受け付けません。

リクエストボディパラメーター

パラメーター型必須説明
stateobjectsession_id といずれか一方判定用のカスタムコンテキスト。テキストや構造化データなどを含む空でない JSON オブジェクトを渡します。トップレベルの state.session_context は予約フィールドであり、指定できません。
session_idstringstate といずれか一方現在の認証スコープ内でアクセス可能かつ未アーカイブの Session ID。1～256 バイトで、先頭・末尾の空白、制御文字、/、\\、?、# を含めることはできません。
questionsarrayはい判定する質問のリスト。
state と session_id は必ずいずれか一方のみを指定します。null の指定は省略と同じではありません。フィールド名は大文字と小文字を区別します。model、identity_id などの追加プロトコルフィールドはサポートしません。

質問の構造

パラメーター型必須説明
typestringはいchoice または score。
namestringいいえ質問名。指定する場合は空でなく、リクエスト内で一意であり、最大 128 バイトで制御文字を含まない必要があります。
instructionsstringはい判定の目的とルールを記述する、空でない判定指示。
choicesarraychoice では必須2～32 個の選択肢。score の質問にはこのフィールドを含めることはできません。
choices[].valuestring または booleanはい候補値。文字列は空にできず、同じ質問内で候補値を重複させることはできません。数値や null はサポートしません。
choices[].descriptionstringいいえ選択肢の意味または選択条件。
levelsarrayscore では必須2～32 個の採点レベル。choice の質問にはこのフィールドを含めることはできません。
levels[].labelstringはい空でないレベル名。
levels[].scorenumberはいレベルに対応する有限の数値。整数または小数を指定できます。
levels[].descriptionstringいいえこのレベルの判定基準。

入力制限

  • リクエストボディは単一の UTF-8 JSON オブジェクトとし、1 MiB 以下にします。
  • JSON のネストは 16 階層以下、各オブジェクトまたは配列は 1,000 項目以下とします。JSON キーの重複は許可されません。
  • 数値は有限の倍精度浮動小数点数の範囲内とします。文字列に NUL などの制御文字は含められませんが、テキスト内容には改行、復帰、タブを使用できます。
  • state 内では業務独自のフィールドを使用できます。リクエスト、質問、選択肢、採点レベルのプロトコル構造は、上表に記載されたフィールドのみを受け付けます。
  • コンテキスト処理と予算のルールは入力方式を参照してください。

リクエスト例

カスタムコンテキストの判定

同じ操作に対して key を一度生成し、その後の再試行では key と元のリクエストボディを変更しないでください。 
IDEMPOTENCY_KEY="$(uuidgen)"

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/decisions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "state": {"message": "My issue is resolved."},
    "questions": [{
      "type": "choice",
      "name": "resolved",
      "instructions": "Has the user confirmed resolution?",
      "choices": [{"value": true}, {"value": false}]
    }]
  }'

Session コンテキストの採点

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/decisions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_xxx",
    "questions": [{
      "type": "score",
      "name": "completion",
      "instructions": "Evaluate how completely the user request has been fulfilled.",
      "levels": [
        {"label": "Incomplete", "score": 0, "description": "The requested result is missing."},
        {"label": "Partial", "score": 0.5, "description": "Only part of the request is fulfilled."},
        {"label": "Complete", "score": 1, "description": "All requested results are provided."}
      ]
    }]
  }'

レスポンス例

HTTP 200 OK（カスタムコンテキストの例） 
{
  "id": "dec_xxx",
  "session_id": null,
  "source": "api",
  "status": "completed",
  "questions": [{
    "type": "choice",
    "name": "resolved",
    "instructions": "Has the user confirmed resolution?",
    "choices": [{"value": true}, {"value": false}]
  }],
  "answers": [{"type": "choice", "name": "resolved", "value": true}],
  "context": {
    "mode": "state"
  },
  "error": null,
  "created_at": "2026-10-26T10:00:00Z",
  "completed_at": "2026-10-26T10:00:02Z"
}
全フィールドは Decision オブジェクトを参照してください。選択式では type: choice と value、採点式では type: score と score を返します。status: completed は判定の完了を示します。業務上の目標を達成したかどうかは回答に基づいて判断してください。

冪等な再試行

  • 冪等 key は現在の認証スコープ内で有効です。再試行では同じ認証スコープ、key、リクエストボディの元のバイト列を維持してください。JSON の意味が同じでも、フィールドの順序や空白を変更すると異なるリクエストボディと見なされます。
  • 同じ key と同じリクエストボディの場合、成功済みなら元の Decision、失敗済みなら元のエラーを返します。いずれも判定を再実行しません。
  • 元のリクエストが実行中の場合は 409 decision_in_progress を返します。エラーに decision_id が含まれるため、後で詳細を照会できます。
  • 同じ key に異なるリクエストボディを指定すると、409 idempotency_key_reused を返します。
  • 新しい判定を行う場合は新しい key を使用します。Session の最新コンテキストに基づく再判定も同様です。key を再利用しても履歴の再読み取りや元の結果の更新は行いません。
レコードには保持期限があります。冪等な再送を永続的な重複排除ストレージとして使用することはできません。結果を長期保存する必要がある場合は、Decision ID と必要な結果を自身で保存してください。

エラー

HTTPCode発生条件
400invalid_decision_input入力モード、質問、選択肢、採点レベル、冪等 key が無効、JSON キーの重複、構造制限の超過、または未知のプロトコルフィールド。
400—クエリパラメーター、重複した冪等ヘッダー、または空の冪等ヘッダーを指定しています。
401—認証情報が未指定、無効、または期限切れです。
403—現在の認証情報に必要なアクセス権限がない、または Workspace 設定が要件を満たしていません。
404—Session が存在しない、アクセス不可、アーカイブ済み、またはその Identity が無効化・削除されています。
409idempotency_key_reused同じ key に異なるリクエストボディが対応しています。
409decision_in_progress同じ key に対応する判定がまだ実行中です。
413—リクエストボディが 1 MiB を超えています。
422decision_context_too_large判定入力が予算を超えた、またはモデルサービスが入力サイズを拒否しました。
422decision_context_unavailableSession に利用可能な判定コンテキストがありません。
402decision_quota_exhausted判定のクォータを使い切った、または制限されています。
429decision_rate_limited判定サービスのレート制限です。Retry-After がある場合はその値に従って待機してください。
499decision_cancelled判定リクエストがキャンセルされました。切断したクライアントはこのレスポンスを受信できない場合があります。
500decision_internal_error または Code なしサービス内部エラー。
502decision_context_read_failedSession 履歴の読み取りに失敗した、または返された構造が無効です。
502decision_invalid_upstream_response、decision_upstream_error判定サービスが無効な結果を返した、またはほかの上流エラーが発生しました。
503decision_upstream_unavailable または Code なし現在の呼び出し元または環境では判定機能を一時的に利用できません。
504decision_timeout判定が実行時間の制限を超えました。

HTTP エラーレスポンス

リクエストが受け付けられ、レコードが生成された後の実行失敗レスポンスには、通常 error.decision_id が含まれます。パラメーター検証や認証など、受け付け前のエラーでは Decision は生成されません。 
{
  "type": "error",
  "request_id": "req_xxx",
  "error": {
    "type": "api_error",
    "code": "decision_timeout",
    "message": "Decision deadline exceeded.",
    "decision_id": "dec_xxx"
  }
}
request_id は利用可能な場合に返され、リクエストの調査に使用します。error.type はエラーの大分類、error.code は任意の業務エラーコードです。入口での認証エラーは異なるレスポンス構造を使用する場合があります。 error.decision_id でレコードを照会できます。詳細 API で失敗レコードを照会した場合は HTTP 200 を返し、レコードの status は failed です。一方、作成 API の失敗は対応する非 2xx HTTP ステータスを返します。

関連