POST/v1/chat

Nhận câu trả lời của trợ lý qua luồng (SSE)

chat

Khi có nhiều bản sao API phía sau bộ cân bằng tải (địa chỉ api.<domain>, 1.62.0), câu trả lời và bộ đệm sự kiện của nó nằm trong bộ nhớ của bản sao đang tạo ra câu trả lời đó. Tiếp tục luồng bằng Last-Event-ID chỉ hoạt động trên bản sao đó.

Yêu cầu lặp lại với cùng request_id và cùng cuộc trò chuyện, nếu đến một bản sao khác sau khi câu trả lời đã hoàn tất, sẽ nhận câu trả lời đã lưu (token và done, sự kiện đánh số từ 1) mà không đặt lại câu hỏi. Yêu cầu lặp lại đến một bản sao khác trong khi câu trả lời vẫn đang được tạo sẽ dừng lần tạo đó và tạo câu trả lời từ đầu; cũng không có câu hỏi thứ hai nào được tạo. Để tiếp tục luồng mà không tạo lại câu trả lời, hãy giữ kết nối tới cùng một bản sao hoặc lặp lại yêu cầu sau sự kiện done.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số header

X-View-Asstring
Chỉ dành cho khóa API có vai trò admin. Thực hiện yêu cầu với tư cách hồ sơ dữ liệu <profile>[:viewer|verifier|editor], ví dụ employee:viewer. Khóa cài đặt không thể dùng header này (403).

Tham số cookie

kb_view_asstring
Cookie của chế độ “View as” cho một phiên. POST /auth/view-as đặt cookie này, còn DELETE /auth/view-as xóa nó.

Phần thân yêu cầu

application/json

Đối tượng: ChatRequest

messagesarray of ChatMessagebắt buộc
items ≥ 1
collectionstring
Mặc định: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Mặc định: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Không lấy câu trả lời từ bộ nhớ đệm câu trả lời (nút “Get a fresh answer” (Nhận câu trả lời mới) bên dưới câu trả lời lấy từ bộ nhớ đệm). Câu trả lời mới thay thế mục trong bộ nhớ đệm.
Mặc định: false
languagestring | null
Ngôn ngữ trả lời: mã ISO 639-1 (de, en, ru, …) để trả lời bằng ngôn ngữ đó. Với auto hoặc khi không có trường này, ngôn ngữ được xác định theo câu hỏi. Giao diện truyền rõ ngôn ngữ của gợi ý viết bằng ngôn ngữ khác (Starter.language).
scopeChatScope | null
Phạm vi câu hỏi: nhiều bộ sưu tập, một nguồn, nhãn và một khoảng thời gian. Các bộ sưu tập của phạm vi thay thế collection. Nguồn thu hẹp câu trả lời trong bộ sưu tập của nguồn đó (và các thẻ của chính nguồn). Nhãn được thêm vào tags. Khoảng thời gian giới hạn câu trả lời tài chính trong khoảng đó. Bạn chỉ có thể chọn những gì người dùng nhìn thấy (bộ sưu tập: collections.no_access/collections.not_found; nguồn: sources.not_found). Với conversation_id, phạm vi được lưu trong cuộc trò chuyện. Khi không có trường này, phạm vi của cuộc trò chuyện được áp dụng; null hoặc phạm vi trống sẽ xóa phạm vi đó.
request_idstring
Khóa idempotency của câu hỏi. Gửi cùng một khóa trong mọi lần thử lại luồng cho một câu hỏi (thử lại sau khi mất kết nối; ở đây Last-Event-ID không tiếp tục luồng và chỉ được ghi vào nhật ký). Lần thử lại với khóa của câu trả lời đã được lưu không tạo câu hỏi thứ hai: kết quả đã lưu được gửi lại dưới dạng một sự kiện done (và một token chứa văn bản), ngay cả khi giới hạn câu hỏi hoặc tín dụng đã hết. Nếu câu trả lời trước vẫn đang được tạo cho một client đã mất kết nối, việc tạo đó dừng lại và câu trả lời được tạo lại từ đầu.
length ≤ 64
version_ofinteger (int64)
Tạo phiên bản mới cho lượt của câu hỏi này trong cuộc trò chuyện (question_id từ nguồn cấp): câu hỏi đã sửa (văn bản mới trong messages), câu trả lời được tạo lại (cùng văn bản, thường kèm bypass_cache), hoặc cùng câu hỏi với quality khác (ví dụ precise sau một câu trả lời fast). Cặp câu hỏi và câu trả lời trước được giữ lại. Các lượt sau nó ở lại trong nhánh của nó và bị ẩn khỏi nguồn cấp trong khi phiên bản mới được chọn (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Lịch sử dùng cho câu trả lời là nhánh đã chọn tính đến lượt này. quality của một phiên bản không thay đổi cài đặt của cuộc trò chuyện. Cần có conversation_id; câu hỏi từ cuộc trò chuyện khác trả về 404 questions.not_found.
qualitystring
Cân bằng giữa tốc độ và độ chính xác của việc tìm kiếm tạo nên kết quả: fast nhanh hơn, precise chính xác hơn. Mặc định: precise.
Giá trị cho phép: fastprecise

Phản hồi

200Với `stream=true`: `text/event-stream`. Mỗi sự kiện gồm các dòng `id: <number>` (số thứ tự của sự kiện trong luồng, bắt đầu từ 1) và `data: <JSON>`, tiếp theo là một dòng trống. Các trường `event:` và `retry:` không được dùng; loại sự kiện nằm trong trường `type` (`ChatEvent`).

Với stream=true: text/event-stream. Mỗi sự kiện gồm các dòng id: <number> (số thứ tự của sự kiện trong luồng, bắt đầu từ 1) và data: <JSON>, tiếp theo là một dòng trống. Các trường event: và retry: không được dùng; loại sự kiện nằm trong trường type (ChatEvent).

Câu hỏi có request_id được trả lời độc lập với kết nối. Mất kết nối không dừng câu trả lời: câu trả lời vẫn được hoàn tất và lưu vào cuộc trò chuyện (trong tối đa 10 phút). Lặp lại cùng yêu cầu (cùng request_id và cùng cuộc trò chuyện) sẽ gắn vào câu trả lời đang được tạo, và với header Last-Event-ID, yêu cầu nhận các sự kiện sau số đó, nên luồng tiếp tục với cùng số thứ tự sự kiện. Nếu luồng không thể tiếp tục từ số đó, yêu cầu lặp lại nhận luồng từ đầu: khi đó sự kiện đầu tiên có số không lớn hơn Last-Event-ID, và client bắt đầu lại câu trả lời. Nếu câu trả lời đã hoàn tất và bộ đệm sự kiện của nó đã được giải phóng (sau 3 phút), kết quả đã lưu được gửi lại (token và done, đánh số từ 1) mà không đặt lại câu hỏi; nếu không, câu trả lời được tạo lại từ đầu. Để dừng câu trả lời như vậy, hãy gọi POST /v1/chat/cancel. Khi không có request_id, việc client ngắt kết nối sẽ hủy câu trả lời.

Sau sự kiện đầu tiên, trong khi câu trả lời đang được tạo, máy chủ gửi chú thích : ping mỗi 15 giây; hãy bỏ qua nó. Thứ tự sự kiện: các sự kiện stage (tiến độ), meta, sources, data, sau đó là nội dung câu trả lời trong các sự kiện token, rồi done. Trước nội dung câu trả lời, sources và data có thể lặp lại và có thể xuất hiện sự kiện tool; nội dung có thể đến trong một token hoặc theo từng phần. Câu trả lời từ bộ nhớ đệm: meta (có cached), sources, data, token, done. Lỗi xảy ra sau khi luồng đã bắt đầu đến dưới dạng sự kiện error, và luồng đóng lại mà không có done; trạng thái HTTP của luồng luôn là 200. Sau done, có thể đến sự kiện followups với các câu hỏi tiếp theo được gợi ý. Hãy bỏ qua các loại sự kiện mà bạn không xử lý.

Với stream=false: application/json với phần thân AnswerResponse (kèm conversation_id).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

text/event-stream

Đối tượng: ChatEvent

Một trong các kiểu

application/json

Đối tượng: AnswerResponse

answerstringbắt buộc
question_idintegerbắt buộc
querystring
collectionstringbắt buộc
sourcesarray of Sourcebắt buộc
table_queriesarray of TableQuerybắt buộc
datasetsarray of Datasetbắt buộc
chartsarray of ChartSpecbắt buộc
warningsarray of AnswerWarningbắt buộc
timingsTimingsbắt buộc
provenancearray of NumberProvenance
emptystring
Giá trị cho phép: 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
Lý do dùng công cụ cho câu trả lời này: request (được yêu cầu rõ); compare, compute, action (dựa trên câu hỏi); needs_calc (cần tính toán trên bảng); summary (tổng quan về một bộ sưu tập hoặc tài liệu); mcp (tổ chức đã kết nối máy chủ MCP bên ngoài).
Giá trị cho phép: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntitybắt buộc
followupsarray of Followupbắt buộc
conversation_idstring
Chỉ với POST /v1/chat có cuộc trò chuyện.
answer_idstring
ID của đối tượng câu trả lời.

400Yêu cầu không hợp lệ: giá trị tham số hoặc trạng thái của đối tượng không cho phép thực hiện hành động (`detail` là thông báo).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

404Đối tượng không tồn tại hoặc bạn không có quyền truy cập. API không xác nhận sự tồn tại của đối tượng bị hạn chế quyền truy cập.

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

422Lỗi dữ liệu không hợp lệ: phần thân hoặc tham số không khớp với lược đồ (`detail` là danh sách lỗi dữ liệu không hợp lệ), hoặc giá trị tham số nằm ngoài phạm vi cho phép (`detail` là thông báo).

Header phản hồi

RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.

Header phản hồi

Retry-After
Số giây cần chờ trước khi thử lại yêu cầu.
RateLimit-Policy
Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.
RateLimit
Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).
X-RateLimit-Remaining
Số yêu cầu còn lại theo giới hạn chặt nhất.
X-RateLimit-Reset
Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

Mã lỗi

Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lại yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← answers · Tài liệu tham chiếu 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"

Dùng thử

Khóa API

Khóa chỉ được giữ trong bộ nhớ của tab này và chỉ được gửi tới https://api.sursa.com.

Yêu cầu tác động lên dữ liệu thật của tổ chức bạn.

X-View-As header

Idempotency-Key

Khi để trống, mỗi yêu cầu sẽ được tạo một khóa mới.

Phần thân yêu cầu (JSON)