POST/v1/chat

Terima jawaban asisten sebagai stream (SSE)

chat

Jika ada beberapa salinan API di belakang penyeimbang beban (alamat api.<domain>, 1.62.0), jawaban dan buffer peristiwanya berada di memori salinan yang menghasilkannya. Melanjutkan stream dengan Last-Event-ID hanya berfungsi pada salinan tersebut.

Permintaan berulang dengan request_id dan percakapan yang sama yang sampai ke salinan lain setelah jawaban selesai menerima jawaban yang tersimpan (token dan done, peristiwa bernomor mulai dari 1) tanpa mengajukan pertanyaan lagi. Permintaan berulang yang sampai ke salinan lain saat jawaban masih dibuat menghentikan pembuatan tersebut dan menyusun jawaban dari awal; pertanyaan kedua juga tidak dibuat. Untuk melanjutkan stream tanpa pembuatan baru, pertahankan koneksi ke salinan yang sama atau ulangi permintaan setelah peristiwa done.

Autentikasi

Kirim kunci API di header Authorization: Authorization: Bearer <kunci>.

Parameter header

X-View-Asstring
Hanya untuk kunci API dengan peran admin. Menjalankan permintaan sebagai profil data <profile>[:viewer|verifier|editor], misalnya employee:viewer. Kunci instalasi tidak dapat memakai header ini (403).

Parameter cookie

kb_view_asstring
Cookie mode “View as” (Lihat sebagai) untuk sesi. POST /auth/view-as menetapkannya dan DELETE /auth/view-as menghapusnya.

Isi permintaan

application/json

Objek: ChatRequest

messagesarray of ChatMessagewajib
items ≥ 1
collectionstring
Default: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Default: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Jangan mengambil jawaban dari cache jawaban (tombol “Get a fresh answer” (Dapatkan jawaban baru) di bawah jawaban dari cache). Jawaban baru menggantikan entri di cache.
Default: false
languagestring | null
Bahasa jawaban: kode ISO 639-1 (de, en, ru, …) untuk menjawab dalam bahasa itu. Dengan auto atau tanpa field ini, bahasa dideteksi dari pertanyaan. Antarmuka mengirim bahasa saran dalam bahasa lain secara eksplisit (Starter.language).
scopeChatScope | null
Cakupan pertanyaan: beberapa koleksi, satu sumber, tag, dan periode. Koleksi dalam cakupan menggantikan collection. Sumber mempersempit jawaban ke koleksinya (dan kartunya sendiri). Tag ditambahkan ke tags. Periode membatasi jawaban keuangan pada periode itu. Anda hanya dapat memilih yang terlihat oleh pengguna (koleksi: collections.no_access/collections.not_found; sumber: sources.not_found). Dengan conversation_id, cakupan disimpan di percakapan. Tanpa field ini, cakupan percakapan yang berlaku; null atau cakupan kosong menghapusnya.
request_idstring
Kunci idempotensi pertanyaan. Kirim kunci yang sama di setiap percobaan ulang stream untuk satu pertanyaan (percobaan ulang setelah koneksi terputus; di sini Last-Event-ID tidak melanjutkan stream dan hanya dicatat di log). Percobaan ulang dengan kunci jawaban yang sudah disimpan tidak membuat pertanyaan kedua: hasil yang tersimpan dikirim lagi sebagai satu peristiwa done (dan token berisi teksnya), meskipun batas pertanyaan atau kredit sudah habis. Jika jawaban sebelumnya masih dibuat untuk klien yang terputus, pembuatan itu dihentikan dan jawaban dibuat dari awal.
length ≤ 64
version_ofinteger (int64)
Membuat versi baru giliran pertanyaan ini dalam percakapan (question_id dari umpan): pertanyaan yang diedit (teks baru di messages), jawaban yang dibuat ulang (teks yang sama, biasanya dengan bypass_cache), atau pertanyaan yang sama dengan quality lain (misalnya, precise setelah jawaban fast). Pasangan pertanyaan dan jawaban sebelumnya tetap disimpan. Giliran sesudahnya tetap berada di cabangnya dan disembunyikan dari umpan selama versi baru dipilih (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Riwayat yang dipakai untuk jawaban adalah cabang yang dipilih sampai giliran ini. quality suatu versi tidak mengubah pengaturan percakapan. Memerlukan conversation_id; pertanyaan dari percakapan lain mengembalikan 404 questions.not_found.
qualitystring
Keseimbangan antara kecepatan dan akurasi pencarian di balik hasil: fast lebih cepat, precise lebih akurat. Default: precise.
Nilai yang diizinkan: fastprecise

Respons

200Dengan `stream=true`: `text/event-stream`. Setiap peristiwa terdiri atas baris `id: <number>` (nomor urut peristiwa di stream, mulai dari 1) dan `data: <JSON>`, diikuti baris kosong. Field `event:` dan `retry:` tidak dipakai; jenis peristiwa ada di field `type` (`ChatEvent`).

Dengan stream=true: text/event-stream. Setiap peristiwa terdiri atas baris id: <number> (nomor urut peristiwa di stream, mulai dari 1) dan data: <JSON>, diikuti baris kosong. Field event: dan retry: tidak dipakai; jenis peristiwa ada di field type (ChatEvent).

Pertanyaan dengan request_id dijawab terlepas dari koneksi. Koneksi yang terputus tidak menghentikan jawaban: jawaban diselesaikan dan disimpan di percakapan (hingga 10 menit). Mengulang permintaan yang sama (request_id dan percakapan yang sama) menyambung ke jawaban yang sedang berlangsung, dan dengan header Last-Event-ID menerima peristiwa setelah nomor tersebut, sehingga stream berlanjut dengan nomor peristiwa yang sama. Jika stream tidak dapat dilanjutkan dari nomor tersebut, permintaan berulang mendapatkan stream dari awal: peristiwa pertama lalu memiliki nomor yang tidak lebih besar dari Last-Event-ID, dan klien memulai jawaban dari awal. Jika jawaban sudah selesai dan buffer peristiwanya sudah dilepaskan (setelah 3 menit), hasil yang tersimpan dikirim lagi (token dan done, bernomor mulai dari 1) tanpa mengajukan pertanyaan lagi; jika tidak, jawaban dibuat dari awal. Untuk menghentikan jawaban seperti itu, panggil POST /v1/chat/cancel. Tanpa request_id, pemutusan koneksi oleh klien membatalkan jawaban.

Setelah peristiwa pertama, selama jawaban berlangsung, server mengirim komentar : ping setiap 15 detik; abaikan komentar ini. Urutan peristiwa: peristiwa stage (progres), meta, sources, data, lalu teks jawaban dalam peristiwa token, lalu done. Sebelum teks jawaban, sources dan data dapat berulang dan peristiwa tool dapat muncul; teks dapat datang sebagai satu token atau dalam beberapa bagian. Jawaban dari cache: meta (dengan cached), sources, data, token, done. Error setelah stream dimulai datang sebagai peristiwa error, dan stream ditutup tanpa done; status HTTP stream selalu 200. Setelah done, peristiwa followups dengan saran pertanyaan berikutnya dapat datang. Abaikan jenis peristiwa yang tidak Anda tangani.

Dengan stream=false: application/json dengan isi AnswerResponse (ditambah conversation_id).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

text/event-stream

Objek: ChatEvent

Salah satu dari

application/json

Objek: AnswerResponse

answerstringwajib
question_idintegerwajib
querystring
collectionstringwajib
sourcesarray of Sourcewajib
table_queriesarray of TableQuerywajib
datasetsarray of Datasetwajib
chartsarray of ChartSpecwajib
warningsarray of AnswerWarningwajib
timingsTimingswajib
provenancearray of NumberProvenance
emptystring
Nilai yang diizinkan: 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
Mengapa alat dipakai untuk jawaban ini: request (diminta secara eksplisit); compare, compute, action (berdasarkan pertanyaan); needs_calc (perlu perhitungan atas tabel); summary (ikhtisar koleksi atau dokumen); mcp (organisasi telah menghubungkan server MCP eksternal).
Nilai yang diizinkan: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntitywajib
followupsarray of Followupwajib
conversation_idstring
Hanya untuk POST /v1/chat dengan percakapan.
answer_idstring
ID objek jawaban.

400Permintaan tidak valid: nilai parameter atau status objek tidak memungkinkan tindakan ini (`detail` berisi pesan).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

401Kredensial tidak dikirim (baik cookie sesi maupun kunci API), atau kunci tidak ditemukan.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

403Tindakan tidak diizinkan: peran tidak memadai, tidak ada akses ke koleksi atau kartu, permintaan berjalan dalam mode “View as”, atau organisasi ditangguhkan atau dihapus (`detail` adalah objek dengan `code: org_suspended | org_deleted`).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

404Objek tidak ada atau tidak tersedia bagi Anda. API tidak mengonfirmasi keberadaan objek yang dibatasi.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

422Error validasi: isi atau parameter tidak sesuai dengan skema (`detail` berisi daftar error validasi), atau nilai parameter berada di luar rentang (`detail` berisi pesan).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

429Terlalu banyak permintaan (`api.rate_limited`), kuota organisasi untuk menit, hari, atau bulan sudah habis (`api.quota_exceeded`; `error.details` berisi `quota`, `limit`, dan `reset_at`), batas organisasi tercapai, atau layanan jawaban sedang sibuk (`answers.engine_busy`). Tunggu selama waktu di header `Retry-After`.

Header respons

Retry-After
Jumlah detik yang perlu ditunggu sebelum Anda mencoba ulang permintaan.
RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

Kode error

Kode yang dapat dikembalikan endpoint ini di error.code, selain kode umum yang berlaku untuk setiap permintaan.

Percobaan ulang yang aman

Kirim header Idempotency-Key (misalnya UUID) bersama setiap POST dan PATCH. Percobaan ulang dengan kunci yang sama dalam 24 jam mengembalikan respons yang tersimpan alih-alih menjalankan permintaan lagi.

Batas laju

Respons berisi header RateLimit dan RateLimit-Policy serta header lama X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Respons 429 berisi Retry-After dalam detik: tunggu, lalu coba lagi.

← answers · Referensi 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"

Coba

Kunci API

Kunci hanya disimpan di memori tab ini dan hanya dikirim ke https://api.sursa.com.

Permintaan bekerja pada data asli organisasi Anda.

X-View-As header

Idempotency-Key

Jika kosong, kunci baru dibuat untuk setiap permintaan.

Isi permintaan (JSON)