API Pencarian Knowledge

API Pencarian Knowledge (Knowledge Search API) memungkinkan sistem Anda sendiri mencari knowledge sebuah agent dan menerima potongan (chunk) dokumen, website, dan video yang cocok. Tidak ada jawaban buatan AI dan tidak ada reranking: Anda mengirim query, Qlar mencari chunk yang paling dekat, lalu Anda yang menentukan apa yang dilakukan dengan chunk itu.

Gunakan API ini jika knowledge yang sudah dimiliki agent Anda juga dibutuhkan di tempat lain, misalnya:

• Pipeline RAG atau chatbot Anda sendiri. Aplikasi Anda meminta chunk yang relevan ke Qlar, lalu menulis jawabannya dengan model milik Anda.
• Kotak pencarian internal. Halaman intranet atau pusat bantuan menampilkan bagian dokumen yang cocok dengan kata kunci karyawan, lengkap dengan tautan ke dokumen sumbernya.
• Agent AI yang dibangun di luar Qlar. Agent di platform lain memanggil API ini sebagai tool retrieval, sehingga membaca dari knowledge base yang sama dengan agent Qlar Anda.

API ini mencari di knowledge yang sama dengan yang dipakai agent dalam percakapan. Semua yang Anda tambahkan, nonaktifkan, atau hapus di Knowledge (lewat CMS maupun lewat Integrasi Dokumen) langsung tercermin di hasil pencarian.

Dalam contoh Mengajari Agent Anda, Atlas menyimpan SOP Kirana Group. Intranet Kirana punya kotak pencarian untuk karyawan. Alih-alih membangun indeks kedua, server intranet mengirim setiap pencarian ke API Pencarian Knowledge milik Atlas dan menampilkan bagian dokumen yang dikembalikan, termasuk SOP-FIN-007 "Project and Capex Approval Policy".

Sebelum memulai

• Hanya untuk service agent. API Pencarian Knowledge tersedia untuk service agent. Personal agent tidak bisa menyalakannya. Lihat Personal Agent vs Service Agent jika Anda belum yakin jenis agent Anda.
• Siapa yang bisa menyalakannya. Contributor agent serta Owner dan Admin organisasi.
• Mati secara default. Setiap agent dimulai dengan API ini dalam keadaan mati. Tidak ada yang bisa memanggilnya sampai seseorang menyalakannya dan membuat key.
• Agent perlu punya knowledge. Tambahkan dokumen, website, atau video terlebih dahulu. Lihat Mengajari Agent Anda.
• Jika sebagian knowledge bersifat rahasia, baca Permission Knowledge terlebih dahulu. API ini memakai kode permission yang sama.

Menyalakan API dan membuat key

Di CMS, buka Channels → Search API di sidebar agent Anda. Halaman ini punya tiga tab: Access, Permissions, dan Log.

1. Di tab Access, nyalakan Allow search through the API. Halaman ini menampilkan endpoint untuk agent ini beserta contoh cURL yang siap dijalankan.

2. Agent punya dua slot key, Primary dan Secondary. Di salah satunya, buat key dan isi:

   Field	Yang diisi
   Name	Label yang menunjukkan sistem mana yang memakai key, misalnya Kirana intranet search. Maksimal 80 karakter.
   Expiry	7, 14, 30, 90, 180, atau 365 hari, atau tidak pernah. Setelah tanggal itu key berhenti bekerja.

3. Buat key lalu segera salin. Key lengkap (diawali qks_) hanya ditampilkan satu kali. Qlar hanya menyimpan sidik jarinya, sehingga baik Anda maupun tim support Qlar tidak bisa melihatnya lagi. Setelah itu halaman hanya menampilkan empat karakter terakhir dan tanggal kedaluwarsanya.

4. Simpan key di tempat penyimpanan rahasia server Anda (misalnya vault atau environment variable di server yang memanggil API).

Key untuk API ini tidak punya scope: setiap key bisa mencari, dan hanya itu yang bisa dilakukannya.

Mengganti atau mencabut key

• Key hilang? Key tidak bisa dilihat lagi. Buat key baru di slot yang sama. Key baru langsung menggantikan key lama, sehingga sistem yang masih memakai key lama akan mendapat error 401.
• Revoke (cabut) key untuk menghentikannya saat itu juga, misalnya jika key mungkin bocor atau sebuah sistem sudah tidak dipakai. Key yang sudah dicabut tidak bisa dinyalakan lagi; buat key baru jika Anda membutuhkan akses lagi.
• Matikan API untuk menghentikan semua key agent sekaligus. Saat dinyalakan lagi, key yang masih berlaku akan bekerja kembali.

Merotasi key tanpa downtime

Dua slot ini ada supaya Anda bisa mengganti key tanpa mengganggu sistem Anda:

1. Sistem Anda memakai key Primary.
2. Buat key di slot Secondary.
3. Pindahkan client Anda ke key Secondary, lalu pastikan pencariannya berhasil (log pencarian menunjukkan key mana yang dipakai setiap panggilan).
4. Revoke key Primary.

Rotasi berikutnya, lakukan hal yang sama ke arah sebaliknya. Dikombinasikan dengan expiry, cara ini membuat setiap key berumur pendek.

Key yang dipakai agent lain

Agent lain yang Anda kelola dapat mencari di knowledge agent ini melalui Knowledge Eksternal. Saat agent itu menambahkan agent ini sebagai provider, Qlar otomatis membuatkan key untuknya. Key ini tidak memakai slot Primary atau Secondary: key tercantum di Used by other agents pada tab Access, beserta nama agent yang memakai masing-masing key. Revoke salah satunya untuk menghentikan agent itu mencari di sini; contributor agent itu bisa membuat key baru nanti. Permission wajib, log, batas rate, dan 1 credit per pencarian berlaku untuk pencarian tersebut seperti pencarian lainnya.

Request

POST https://api.qlar.ai/dialog/api/knowledge-search/v1/agents/{agentId}/search
X-Api-Key: qks_...
Content-Type: application/json

Endpoint lengkap dengan agent ID Anda tampil, siap disalin, di tab Access. Contoh di halaman ini memakai dua variabel shell, sehingga key tidak pernah muncul di perintahnya:

export QLAR_SEARCH_URL="https://api.qlar.ai/dialog/api/knowledge-search/v1/agents/YOUR_AGENT_ID/search"
export QLAR_SEARCH_KEY="qks_..."   # ambil dari tempat penyimpanan rahasia Anda

Body:

Contoh request:

curl -X POST "$QLAR_SEARCH_URL" \
  -H "X-Api-Key: $QLAR_SEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Siapa yang menyetujui capex di atas USD 50.000?",
    "permissions": ["FINANCE"],
    "limit": 3
  }'

Key yang tidak dikirim, salah, kedaluwarsa, atau sudah dicabut, agent yang API-nya dimatikan, personal agent, dan agent yang tidak ada, semuanya mendapat jawaban 401 unauthorized yang sama. Ini disengaja: API tidak membocorkan agent mana yang ada atau mengapa sebuah key ditolak.

Response

{
  "results": [
    {
      "chunkCode": "SOP-FIN-007-0004",
      "contentId": "5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b",
      "title": "Project and Capex Approval Policy",
      "section": "3. Approval limits",
      "text": "Capital expenditure above USD 50,000 requires approval from the Finance Controller and the Head of Operations before a purchase order is raised.",
      "distance": 0.1842
    },
    {
      "chunkCode": "SOP-FIN-007-0005",
      "contentId": "5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b",
      "title": "Project and Capex Approval Policy",
      "section": "4. Emergency purchases",
      "text": "In an emergency, the Head of Operations may approve up to USD 75,000; the Finance Controller signs off within two working days.",
      "distance": 0.2617
    }
  ],
  "route": "platform",
  "creditsCharged": 1
}

Permission

Kode permission bekerja sama seperti dalam percakapan agent: konten tanpa kode bisa ditemukan oleh semua pencarian, sedangkan konten dengan kode hanya ditemukan jika pencarian membawa salah satu kodenya. Lihat Permission Knowledge.

Setiap pencarian membawa dua kelompok kode:

• Enforced permissions. Kode yang Anda pilih di tab Permissions, dari daftar permission milik agent. Kode ini ditambahkan ke setiap pencarian, baik pemanggil mengirim kode maupun tidak.
• Permission dari pemanggil. Kode di field permissions pada request.

Pencarian memakai keduanya sekaligus: pemanggil ∪ enforced. Pemanggil bisa membuka lebih banyak konten dengan mengirim lebih banyak kode, tetapi tidak pernah kurang dari yang dibuka oleh kode enforced.

Pemanggil bertanggung jawab atas kode yang dikirimnya. Qlar tidak tahu siapa orang di balik sebuah pencarian: Qlar memercayai kode yang dikirim pemegang key. Siapa pun yang memegang key bisa mengirim kode apa saja, termasuk kode untuk konten rahasia. Server Anda harus memastikan siapa penggunanya dan hanya mengirim kode yang memang menjadi haknya, misalnya dengan memetakan role atau grup di sistem Anda ke kode permission.

Contoh:

• Enforced permissions dibiarkan kosong dan pemanggil tidak mengirim kode: pencarian hanya menemukan konten tanpa kode.
• GENERAL di-enforce: setiap pencarian juga menemukan konten bertanda GENERAL, tanpa sistem Anda perlu mengirimnya.
• Intranet Kirana hanya mengirim FINANCE untuk karyawan di grup finance. Karyawan lain hanya mendapat hasil dari SOP yang tidak bertanda kode.

Jika agent belum punya kode permission, tab Permissions menautkan ke Users → Permissions, tempat Anda membuatnya.

Distance dan limit

Setiap hasil punya distance antara query dan chunk. Makin kecil, makin cocok. Distance berasal dari model embedding yang melayani pencarian, sehingga nilai dari model Qlar (route: platform) dan dari model milik organisasi Anda (route: own) tidak berada di skala yang sama. Bandingkan distance di dalam satu response, atau antar pencarian dengan route yang sama, bukan antar route.

Pencarian menemukan chunk dengan cara yang sama seperti agent dalam percakapannya. Pencarian dimulai dari Search tolerance milik agent dan, jika belum ada yang cukup dekat, melebar bertahap sebesar Tolerance increment sampai menemukan chunk atau mencapai batas maksimal. Keduanya diatur di Knowledge → Retrieval; lihat Retrieval. Mengubahnya juga mengubah hasil API.

limit membatasi jumlah chunk yang dikembalikan (1 sampai 20, default 5). Hasilnya bisa lebih sedikit jika chunk yang cukup dekat lebih sedikit. Jika chunk akan Anda berikan ke model, mulailah dengan 3 sampai 5: makin banyak chunk, makin banyak token di model Anda dan makin besar kemungkinan teks yang kurang relevan ikut masuk.

Query diubah menjadi embedding (oleh model embedding Qlar pada indeks platform, atau oleh model milik organisasi Anda). Tidak ada model bahasa dan tidak ada reranker yang dipakai, sehingga pencarian tetap cepat dan murah.

Biaya

creditsCharged di setiap response menunjukkan biaya pencarian tersebut. Kredit diambil dari saldo organisasi Anda, sama seperti aksi Qlar lainnya; lihat Cara Kerja Kredit. Jika kredit organisasi habis, pencarian dengan embedding Qlar ditolak dengan 402 credit_exhausted.

Batas request

Request yang melewati batas mendapat 429 rate_limited dengan header Retry-After berisi jumlah detik yang harus ditunggu. Tunggu setidaknya selama itu sebelum mencoba lagi; jangan mengulang dalam loop yang rapat. Sistem yang terus mengirim key lama bisa menghabiskan batas autentikasi gagal dan memblokir pemanggil lain di agent yang sama selama satu menit, jadi perbaiki 401 alih-alih terus mengulanginya.

Error

Error memakai kode status HTTP dan body JSON berisi code yang bisa dibaca mesin dan message yang bisa dibaca manusia:

{
  "code": "invalid_request",
  "message": "query must be between 1 and 1000 characters."
}

Bangun logika Anda berdasarkan code. Isi message bisa berubah dan ditujukan untuk manusia.

Log pencarian dan retensi

Setiap panggilan pencarian, berhasil maupun tidak, dicatat. Contributor bisa melihat log di tab Log pada Channels → Search API, yang terbaru lebih dulu, dan bisa memfilternya berdasarkan tanggal dan hasil.

Klik sebuah baris untuk melihat kode chunk dan permission-nya.

Di atas log, Anda menentukan:

• Keep entries for: berapa lama entri disimpan, dari pilihan periode yang tersedia di halaman (90 hari kecuali Anda mengubahnya). Memperpendek periode akan menghapus entri yang lebih tua dari periode baru saat Anda menyimpan, dan ini tidak bisa dibatalkan. Memperpanjang periode berlaku untuk entri baru; entri yang sudah terhapus tidak kembali.
• Store query text: apakah log menyimpan teks yang dicari. Pengaturan ini menyala secara default. Query bisa berisi informasi pribadi atau rahasia, jadi matikan jika Anda tidak membutuhkannya. Jika mati, log menampilkan Not stored di tempat query.

Log tidak pernah berisi API key maupun teks chunk yang dikembalikan.

Praktik keamanan terbaik

• Simpan key di server. Panggil API hanya dari kode back-end. Jangan pernah menaruh key di halaman browser, aplikasi mobile, aplikasi desktop yang Anda distribusikan, atau repository publik: siapa pun yang bisa membaca kodenya bisa memakai key tersebut, dan mengirim kode permission apa pun bersamanya.
• Tentukan permission di server Anda. Kirim hanya kode yang menjadi hak pengguna yang sedang login. Jangan pernah meneruskan kode dari browser pengguna apa adanya.
• Pakai enforced permissions sebagai batas bawah, bukan batas atas. Kode ini ditambahkan ke setiap pencarian; kode ini tidak bisa mencegah pemanggil mengirim kode lain.
• Simpan key sebagai rahasia. Pakai vault atau secret variable di platform Anda, bukan file konfigurasi yang masuk ke source control. Jangan mencetak key di log.
• Pasang expiry dan rotasi key memakai dua slot, seperti dijelaskan di Merotasi key tanpa downtime.
• Segera cabut jika bocor. Jika sebuah key mungkin terekspos, cabut di tab Access, buat key baru, dan periksa log pencarian untuk panggilan yang tidak Anda kenali.
• Matikan API jika tidak dipakai lagi.

Troubleshooting

Halaman Terkait

• Permission Knowledge: kode permission yang dibawa pencarian.
• Retrieval: search tolerance yang juga dipakai API ini.
• Chunks: memeriksa chunk yang dikembalikan pencarian.
• Integrasi Dokumen: menjaga knowledge-nya sendiri tetap sinkron dari sistem Anda.
• Mengizinkan Agent Lain Memanggil Agent Anda: mengizinkan agent lain meminta jawaban lengkap dari agent Anda, bukan chunk.
• Knowledge Search dengan Model Sendiri: menjalankan pencarian dengan model embedding milik organisasi Anda, tanpa memakai kredit Qlar.
• Cara Kerja Kredit
• Referensi per field: Search API