本文へスキップ
Sursa Developers

POST/v1/chat

アシスタントの回答をストリーミングする（SSE）

chat

ロードバランサーの背後に複数のAPIのコピーがある場合（api.<domain>のアドレス、1.62.0）、回答とそのイベントのバッファーは、回答を生成するコピーのメモリーにあります。Last-Event-IDによるストリームの再開は、そのコピーでしか機能しません。

同じrequest_idと会話による繰り返しのリクエストが、回答の完了後に別のコピーに届いた場合は、質問をもう一度行わずに保存済みの回答（tokenとdone、イベントの番号は1から）を受け取ります。回答の生成中に繰り返しのリクエストが別のコピーに届いた場合は、その生成が停止し、回答が新しく作成されます。この場合も2つ目の質問は作成されません。新たな生成なしでストリームを再開するには、同じコピーへの接続を維持するか、doneイベントの後にリクエストを繰り返してください。

認証

AuthorizationヘッダーでAPIキーを送信します：Authorization: Bearer <キー>。

ヘッダーパラメーター

  • X-View-Asstring

    adminロールのAPIキー専用です。データプロファイル<profile>[:viewer|verifier|editor]（例：employee:viewer）としてリクエストを実行します。インストールキーではこのヘッダーを使えません（403）。

Cookieパラメーター

  • kb_view_asstring

    セッションの「View as」モードのCookie。POST /auth/view-asで設定し、DELETE /auth/view-asで解除します。

リクエストボディ

application/json

オブジェクト：ChatRequest

  • messagesarray of ChatMessage必須

    items ≥ 1

  • collectionstring

    デフォルト："default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • streamboolean

    デフォルト：false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    回答キャッシュから回答を取得しません（キャッシュされた回答の下にある「Get a fresh answer」ボタン）。新しい回答がキャッシュのエントリを置き換えます。

    デフォルト：false

  • languagestring | null

    回答の言語：その言語で回答させるためのISO 639-1コード（de、en、ru、…）。autoの場合またはフィールドがない場合、言語は質問から判定されます。画面は、別の言語の提案の言語を明示的に渡します（Starter.language）。

  • scopeChatScope | null

    質問の範囲：複数のコレクション、ソース、タグ、期間。範囲のコレクションはcollectionに代わります。ソースを指定すると、回答はそのソースのコレクション（とソース自身のカード）に絞り込まれます。タグはtagsに追加されます。期間は、財務に関する回答をその期間に限定します。選択できるのは、ユーザーが参照できるものだけです（コレクション：collections.no_access/collections.not_found、ソース：sources.not_found）。conversation_idを指定すると、範囲は会話に保存されます。フィールドがない場合は会話の範囲が適用され、nullまたは空の範囲を渡すとクリアされます。

  • request_idstring

    質問の冪等キー。同じ質問に対するストリームの再試行（切断後の再試行。この場合、Last-Event-IDはストリームを継続せず、ログに記録されるだけです）では、毎回同じキーを送ってください。すでに保存された回答のキーで再試行しても、質問が重複して作成されることはありません：保存済みの結果が単一のdoneイベント（とテキストを含むtoken）として再送されます。質問数やクレジットの上限に達していても同じです。切断されたクライアントに向けて前の回答がまだ生成中の場合、その生成は停止し、回答があらためて生成されます。

    length ≤ 64

  • version_ofinteger (int64)

    会話内のこの質問のターンについて、新しいバージョンを作成します（会話の履歴のquestion_id）：編集した質問（messagesの新しいテキスト）、再生成した回答（同じテキスト。通常はbypass_cacheと併用）、または別のqualityでの同じ質問（たとえば、preciseでfastの回答をやり直す）。以前の質問と回答のペアは保持されます。その後のターンは元の分岐に残り、新しいバージョンが選択されている間は会話の履歴に表示されません（FeedItem.versions、POST /v1/conversations/{conv_id}/versions）。回答に使われる履歴は、選択中の分岐のこのターンまでの部分です。バージョンのqualityは、会話の設定を変更しません。conversation_idが必要です。ほかの会話の質問では404 questions.not_foundが返ります。

  • qualitystring

    結果の元になる検索の速さと正確さのバランス：fastはより速く、preciseはより正確です。デフォルト：precise。

    指定できる値: fastprecise

レスポンス

200`stream=true`の場合：`text/event-stream`。各イベントは`id: <number>`（ストリーム内のイベントの通し番号で、1から始まります）と`data: <JSON>`の行、その後の空行で構成されます。`event:`と`retry:`のフィールドは使いません。イベントタイプは`type`フィールドにあります（`ChatEvent`）。

stream=trueの場合：text/event-stream。各イベントはid: <number>（ストリーム内のイベントの通し番号で、1から始まります）とdata: <JSON>の行、その後の空行で構成されます。event:とretry:のフィールドは使いません。イベントタイプはtypeフィールドにあります（ChatEvent）。

request_id付きの質問は、接続とは独立して回答されます。接続が切れても回答は停止せず、完了して会話に保存されます（最大10分間）。同じリクエスト（同じrequest_idと会話）を繰り返すと進行中の回答に接続し、Last-Event-IDヘッダーがあればその番号より後のイベントを受け取るので、ストリームは同じイベント番号のまま続きます。その番号からストリームを続けられない場合、繰り返しのリクエストはストリームを最初から受け取ります：このとき最初のイベントの番号はLast-Event-ID以下になるので、クライアントは回答を最初からやり直します。回答がすでに完了し、イベントのバッファーが解放されている場合（3分後）は、質問をもう一度行わずに保存済みの結果が再送されます（tokenとdone、番号は1から）。それ以外の場合は、回答が新しく生成されます。このような回答を停止するには、POST /v1/chat/cancelを呼び出してください。request_idがない場合は、クライアントの接続が切れると回答がキャンセルされます。

最初のイベントの後、回答の進行中は、サーバーが15秒ごとに: pingコメントを送ります。これは読み飛ばしてください。イベントの順序：stageイベント（進捗）、meta、sources、data、次にtokenイベントで回答の本文、最後にdoneです。回答の本文の前に、sourcesとdataが繰り返されたり、toolイベントが現れたりすることがあります。本文は1つのtokenで届くことも、部分に分かれて届くこともあります。キャッシュされた回答：meta（cached付き）、sources、data、token、done。ストリームの開始後に発生したエラーはerrorイベントとして届き、ストリームはdoneなしで閉じます。ストリームのHTTPステータスは常に200です。doneの後に、次の質問の候補を含むfollowupsイベントが届くことがあります。処理しないイベントタイプは無視してください。

stream=falseの場合：AnswerResponseボディ（とconversation_id）を持つapplication/json。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

text/event-stream

オブジェクト：ChatEvent

いずれか1つ

application/json

オブジェクト：AnswerResponse

  • answerstring必須
  • question_idinteger必須
  • querystring
  • collectionstring必須
  • sourcesarray of Source必須
  • table_queriesarray of TableQuery必須
  • datasetsarray of Dataset必須
  • chartsarray of ChartSpec必須
  • warningsarray of AnswerWarning必須
  • timingsTimings必須
  • provenancearray of NumberProvenance
  • emptystring

    指定できる値: no_hitsrestrictedguardrailno_data_for_period

  • basisAnswerBasis
  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • guardrailGuardrailVerdict
  • verified_onlyboolean
  • cachedboolean
  • cache_hitAnswerCacheHit
  • out_of_scopeAnswerOutOfScope
  • attachmentsarray of Attachment
  • export_errorstring
  • toolsstring | null

    この回答でツールが使われた理由：request（明示的に求められた）、compare、compute、action（質問に基づく）、needs_calc（表に対する計算が必要）、summary（コレクションまたはドキュメントの概要）、mcp（組織が外部のMCPサーバーを接続している）。

    指定できる値: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntity必須
  • followupsarray of Followup必須
  • conversation_idstring

    会話を指定したPOST /v1/chatのみ。

  • answer_idstring

    回答オブジェクトのID。

400リクエストが無効です：パラメーターの値またはオブジェクトの状態により、この操作を実行できません（`detail`はメッセージ）。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

401認証情報が送信されていない（セッションCookieもAPIキーもない）か、キーが見つかりません。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

403この操作は許可されていません：ロールの権限が足りない、コレクションやカードへのアクセス権がない、リクエストが「View as」モードで実行されている、または組織が停止中か削除済みです（`detail`は`code: org_suspended | org_deleted`を持つオブジェクト）。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

404オブジェクトが存在しないか、アクセスできません。APIは、アクセスが制限されたオブジェクトの存在を明かしません。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

422バリデーションエラー：ボディまたはパラメーターがスキーマに一致しない（`detail`はバリデーションエラーのリスト）、またはパラメーターの値が範囲外です（`detail`はメッセージ）。

レスポンスヘッダー

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

429リクエストが多すぎる（`api.rate_limited`）、組織の1分・1日・1か月のクォータを使い切った（`api.quota_exceeded`。`error.details`には`quota`、`limit`、`reset_at`が含まれます）、組織の上限に達した、または回答サービスが混雑しています（`answers.engine_busy`）。`Retry-After`ヘッダーの時間だけ待ってください。

レスポンスヘッダー

  • Retry-After

    リクエストを再試行するまでに待つ秒数。

  • RateLimit-Policy

    適用中の制限。IETFのドラフトdraft-ietf-httpapi-ratelimit-headersの形式で、"<name>";q=<quota>;w=<window in seconds>の項目をカンマで区切って並べます。keyはAPIキーのリクエストレートです（クォータはバースト、ウィンドウはバーストが完全に回復するまでの時間。セッションではuser、認証情報がない場合はip）。minute、day、monthは、UTCの暦の上での1分・1日・1か月ごとの組織のクォータです。

  • RateLimit

    RateLimit-Policyの各制限の残り："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policyのうち最も厳しい項目（残りのリクエスト数が最も少ない項目）の上限。

  • X-RateLimit-Remaining

    最も厳しい制限での残りのリクエスト数。

  • X-RateLimit-Reset

    最も厳しい制限がリセットされるまでの秒数。

application/json

オブジェクト：Error

エラーコード

すべてのリクエストに共通のコードに加えて、このエンドポイントがerror.codeで返すことのあるコード。

安全な再試行

POSTとPATCHのたびにIdempotency-Keyヘッダー（UUIDなど）を送信してください。24時間以内に同じキーで再試行すると、リクエストをもう一度実行せずに、保存済みのレスポンスが返ります。

レート制限

レスポンスには、RateLimitヘッダーとRateLimit-Policyヘッダー、以前のX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが含まれます。429レスポンスにはRetry-After（秒）が含まれます。その時間だけ待ってから再試行してください。

← answers · APIリファレンス