POST/v1/chat

以流式返回助手的回答（SSE）

chat

负载均衡器后面有多个 API 副本时（api.<domain> 地址，1.62.0），回答及其事件缓冲区保存在生成该回答的副本的内存中。使用 Last-Event-ID 恢复流只能在该副本上进行。

回答完成后，带有相同 request_id 和对话的重复请求如果到达另一个副本，会收到已保存的回答（token 和 done，事件从 1 开始编号），而不会再次提问。回答仍在生成时，到达另一个副本的重复请求会停止该次生成并重新生成回答；同样不会创建第二个问题。要在不重新生成的情况下恢复流，请保持与同一副本的连接，或在收到 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 设置该 Cookie，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 回答的同一问题（例如在 fast 回答之后改用 precise）。之前的问答对会保留。其后的轮次留在原分支中，选中新版本时不在对话记录中显示（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 事件；正文可能作为一个 token 到达，也可能分成多个部分到达。缓存的回答：meta（带 cached）、sources、data、token、done。流开始后发生的错误以 error 事件的形式到达，流在没有 done 的情况下关闭；流的 HTTP 状态始终为 200。done 之后可能到达带有建议后续问题的 followups 事件。忽略您不处理的事件类型。

stream=false 时：application/json，响应体为 AnswerResponse（另加 conversation_id）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
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

以下之一

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 计算的自然分钟、自然日和自然月的配额。
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 计算的自然分钟、自然日和自然月的配额。
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 计算的自然分钟、自然日和自然月的配额。
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 计算的自然分钟、自然日和自然月的配额。
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 计算的自然分钟、自然日和自然月的配额。
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`）、组织每分钟、每天或每月的配额已用完（`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 计算的自然分钟、自然日和自然月的配额。
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 参考

curl -X POST 'https://api.sursa.com/v1/chat' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"How do I request a refund?"}],"collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

在线调试

API 密钥

密钥只保存在此标签页的内存中，只会发送到 https://api.sursa.com。

请求会作用于您组织的真实数据。

X-View-As header

Idempotency-Key

留空时，每个请求都会生成一个新键。

请求体（JSON）