Knowledge API

Knowledge API memungkinkan sistem Anda sendiri mengelola dokumen knowledge sebuah agent tanpa membuka CMS. Script, job terjadwal, atau aplikasi lain yang memegang salah satu API key agent dapat menampilkan daftar dokumen, meng-upload dokumen baru, memantau pemrosesannya, mengaktifkan atau menonaktifkannya, dan menghapusnya.

Gunakan fitur ini jika dokumen Anda sudah tersimpan di tempat lain dan Anda ingin agent selalu sinkron dengan sumber tersebut, misalnya:

• Sistem manajemen dokumen (DMS) yang mengirim setiap SOP yang baru disetujui ke agent.
• Job ekspor SharePoint setiap malam yang meng-upload kebijakan yang berubah dan memensiunkan versi lama.
• Pipeline CI yang menerbitkan manual produk atau release notes ke agent setiap kali di-merge.

API ini bekerja pada dokumen yang sama dengan yang Anda lihat di Knowledge → Documents: dokumen yang di-upload lewat API juga muncul di sana dan melalui pemrosesan yang sama. API ini hanya mencakup dokumen (PDF, Markdown, dan teks biasa), tidak termasuk website atau video.

Dalam contoh Mengajari Agent Anda, Kirana Group menyimpan SOP-nya di DMS sendiri. Alih-alih meng-upload SOP-FIN-007 "Project and Capex Approval Policy" ke Atlas secara manual, DMS mengirimkannya lewat Knowledge API begitu Finance menyetujui versi baru.

Sebelum memulai

• Hanya untuk service agent. Knowledge API tersedia untuk service agent. Personal agent tidak bisa menyalakannya, dan mengubah agent dari Service ke Personal akan mematikan API serta mencabut semua key-nya. 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 Knowledge API dalam keadaan mati. Tidak ada yang bisa memanggilnya sampai seseorang menyalakannya dan membuat key.
• Baca Dokumen terlebih dahulu. API mengikuti aturan yang sama untuk status, mode pemrosesan, author, dan permission.
• Periksa Knowledge → Retrieval: agent hanya menjawab dari dokumen jika Enable reference menyala. Lihat Retrieval.

Menyalakan API dan membuat key

Di CMS, buka Knowledge → Knowledge API di sidebar agent Anda.

1. Nyalakan Knowledge API. Halaman ini menampilkan base URL untuk agent ini; salin, karena Anda membutuhkannya di setiap request.

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 DMS sync. Maksimal 80 karakter.
   Scopes	Apa saja yang boleh dilakukan key ini (lihat di bawah).
   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 qk_) 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, scope, tanggal kedaluwarsa, dan kapan key terakhir dipakai.

4. Simpan key di tempat penyimpanan rahasia sistem Anda (misalnya vault, secret pipeline, atau environment variable di server yang menjalankan sinkronisasi).

Scope

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 sinkronisasi:

1. Sistem Anda memakai key Primary.
2. Buat key di slot Secondary.
3. Perbarui sistem Anda agar memakai key Secondary, lalu pastikan panggilannya berhasil (waktu terakhir dipakai pada key dan log aktivitas menunjukkannya).
4. Revoke key Primary.

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

Base URL dan autentikasi

Semua endpoint berada di bawah base URL agent. URL ini juga tampil, siap disalin, di halaman Knowledge → Knowledge API:

{base-url} = https://api.qlar.ai/cms/api/knowledge/v1/agents/{agentId}

Contoh di halaman ini memakai dua variabel shell, sehingga key tidak pernah tertulis langsung di perintah:

export QLAR_BASE_URL="https://api.qlar.ai/cms/api/knowledge/v1/agents/YOUR_AGENT_ID"
export QLAR_KNOWLEDGE_KEY="qk_..."   # ambil dari tempat penyimpanan rahasia Anda

Kirim key di header X-Api-Key pada setiap request:

X-Api-Key: qk_...

Key Primary dan Secondary bekerja dengan cara yang sama; pakai yang sedang aktif. Sebuah key hanya berlaku untuk agent tempat key itu dibuat.

Key yang tidak ada, salah, kedaluwarsa, atau sudah dicabut, agent yang tidak dikenal, dan agent yang Knowledge API-nya dimatikan, semuanya mendapat jawaban yang sama: 401 unauthorized. Ini disengaja: API tidak membocorkan agent mana yang ada atau bagian mana dari key yang salah.

Endpoint

Semua path relatif terhadap {base-url}. Respons berformat JSON. Waktu dalam UTC dengan format ISO 8601.

Objek dokumen

Sebagian besar endpoint mengembalikan sebuah dokumen:

{
  "id": "5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b",
  "code": "SOP-FIN-007",
  "title": "Project and Capex Approval Policy",
  "fileType": "PDF",
  "status": "Active",
  "inProgress": false,
  "statusMessage": "Done processing. Text Chunks: 12, Table Chunks: 2. Total: 14",
  "chunkingStrategy": "adaptive",
  "tag": "finance",
  "sourceUri": "https://dms.kirana.example/sop/SOP-FIN-007",
  "permissions": [],
  "totalChunks": 14,
  "activeChunks": 14,
  "updatedAt": "2026-11-06T03:15:42Z"
}

Daftar dokumen

Mengembalikan dokumen agent, yang terbaru lebih dulu.

GET {base-url}/documents

Query parameter:

Contoh request:

curl "$QLAR_BASE_URL/documents?code=SOP-FIN&limit=20" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Contoh respons:

{
  "items": [
    {
      "id": "5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b",
      "code": "SOP-FIN-007",
      "title": "Project and Capex Approval Policy",
      "fileType": "PDF",
      "status": "Active",
      "inProgress": false,
      "statusMessage": "Done processing. Text Chunks: 12, Table Chunks: 2. Total: 14",
      "chunkingStrategy": "adaptive",
      "tag": "finance",
      "sourceUri": "https://dms.kirana.example/sop/SOP-FIN-007",
      "permissions": [],
      "totalChunks": 14,
      "activeChunks": 14,
      "updatedAt": "2026-11-06T03:15:42Z"
    }
  ],
  "nextCursor": null
}

Jika nextCursor tidak null, kirim nilainya sebagai cursor untuk mengambil halaman berikutnya. Di halaman terakhir nilainya null.

Upload dokumen

Meng-upload file dan langsung memulai pemrosesannya. Setelah pemrosesan selesai, dokumen menjadi Active dengan sendirinya; Anda tidak perlu memanggil activate.

POST {base-url}/documents
Content-Type: multipart/form-data

Field form:

Contoh request:

curl -X POST "$QLAR_BASE_URL/documents" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY" \
  -F file=@sop-fin-007.pdf \
  -F code=SOP-FIN-007 \
  -F "title=Project and Capex Approval Policy" \
  -F authorCode=KG-FIN \
  -F tag=finance \
  -F sourceUri=https://dms.kirana.example/sop/SOP-FIN-007

Respons: 201 Created dengan dokumen baru, biasanya berstatus Processing:

{
  "id": "5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b",
  "code": "SOP-FIN-007",
  "title": "Project and Capex Approval Policy",
  "fileType": "PDF",
  "status": "Processing",
  "inProgress": true,
  "statusMessage": "",
  "chunkingStrategy": "adaptive",
  "tag": "finance",
  "sourceUri": "https://dms.kirana.example/sop/SOP-FIN-007",
  "permissions": [],
  "totalChunks": 0,
  "activeChunks": 0,
  "updatedAt": "2026-11-06T03:12:08Z"
}

Simpan id-nya: Anda membutuhkannya untuk memantau dokumen dan mengubahnya nanti.

Catatan: memproses dokumen memakai AI dan menggunakan credit, sama seperti upload di CMS. Jika credit organisasi Anda habis, upload ditolak dengan 402 insufficient_credit. Pemeriksaan ini tidak berlaku jika organisasi memproses knowledge dengan model AI miliknya sendiri. Lihat Cara Kerja Credit.

Mengambil dokumen

Mengembalikan satu dokumen beserta status terkininya. Pakai untuk polling setelah upload atau perubahan.

GET {base-url}/documents/{documentId}

Contoh request:

curl "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: objek dokumen.

Mengambil log pemrosesan

Mengembalikan log pemrosesan (chunking) sebuah dokumen, entri terlama lebih dulu. Ini log yang sama dengan View log di halaman detail dokumen di CMS, dan tempat pertama yang perlu diperiksa jika dokumen berakhir Failed.

GET {base-url}/documents/{documentId}/logs

Contoh request:

curl "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b/logs" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Contoh respons:

{
  "documentId": "5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b",
  "status": "Active",
  "entries": [
    { "timestamp": "2026-11-06T03:12:10Z", "message": "Routing to document processor" },
    { "timestamp": "2026-11-06T03:12:11Z", "message": "Detected file type: PDF" },
    { "timestamp": "2026-11-06T03:15:40Z", "message": "Done processing. Text Chunks: 12, Table Chunks: 2. Total: 14" }
  ]
}

Mengaktifkan dokumen

Memakai (kembali) dokumen yang berstatus Pending atau Inactive. Memanggilnya pada dokumen yang sudah Active (atau sedang diaktifkan) tidak mengubah apa pun dan bukan error.

POST {base-url}/documents/{documentId}/activate

Contoh request:

curl -X POST "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b/activate" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: dokumen, biasanya berstatus Activating atau Reactivating dengan inProgress: true. Lakukan polling sampai menjadi Active. Status lain ditolak dengan 409 invalid_state.

Menonaktifkan dokumen

Menghentikan agent memakai dokumen yang Active tanpa menghapusnya. Anda bisa mengaktifkannya lagi nanti. Memanggilnya pada dokumen yang sudah Inactive tidak mengubah apa pun.

POST {base-url}/documents/{documentId}/deactivate

Contoh request:

curl -X POST "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b/deactivate" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: dokumen, berstatus Deactivating lalu Inactive. Status lain ditolak dengan 409 invalid_state.

Memproses ulang dokumen

Memproses lagi dokumen yang Failed atau Cancelled, dengan file dan pengaturan yang sama.

POST {base-url}/documents/{documentId}/retry

Contoh request:

curl -X POST "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b/retry" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: dokumen, kembali berstatus Processing.

Membatalkan pemrosesan

Menghentikan dokumen yang masih Processing. Dokumen berakhir Cancelled; setelah itu Anda bisa memproses ulang atau mem-purge-nya.

POST {base-url}/documents/{documentId}/cancel

Contoh request:

curl -X POST "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b/cancel" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: dokumen, berstatus Cancelled.

Menghapus dokumen

Mengeluarkan dokumen dari pemakaian dan menandainya Deleted. Record-nya tetap ada di daftar (juga di CMS), sehingga Anda masih bisa melihatnya dan mem-purge-nya nanti.

DELETE {base-url}/documents/{documentId}

• Dokumen Active dinonaktifkan terlebih dahulu. Panggilan ini menunggu hingga 30 detik; jika setelah itu dokumen masih dalam proses dinonaktifkan, Anda mendapat 409 invalid_state dan cukup mencoba lagi.
• Dokumen Failed atau Cancelled tidak punya apa pun untuk dihapus dan ditolak dengan 409 invalid_state: purge saja.
• Dokumen yang masih berubah (misalnya Processing) ditolak dengan 409 invalid_state; tunggu sampai stabil, atau batalkan.
• Menghapus dokumen yang sudah Deleted tidak mengubah apa pun.

Contoh request:

curl -X DELETE "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: dokumen, berstatus Deleted.

Purge dokumen

Menghapus dokumen secara permanen: record-nya, chunk-nya, log pemrosesannya, cover-nya, dan file sumbernya. Ini tidak bisa dibatalkan. Membutuhkan key dengan scope purge.

POST {base-url}/documents/{documentId}/purge

• Dokumen Active, Inactive, atau Pending dinonaktifkan dan dihapus terlebih dahulu, lalu di-purge, dalam satu panggilan.
• Dokumen yang masih Processing ditolak dengan 409 invalid_state. Batalkan dulu, atau tunggu sampai selesai.

Contoh request:

curl -X POST "$QLAR_BASE_URL/documents/5b7f0e2a-1c3d-4e8f-9a6b-2d4c8e0f1a3b/purge" \
  -H "X-Api-Key: $QLAR_KNOWLEDGE_KEY"

Respons: 204 No Content.

Status dokumen

Field status memakai status yang sama dengan badge di halaman Documents.

Perjalanan umum sebuah dokumen:

1. Upload → Processing
2. Pemrosesan selesai → Pending → Activating → Active (semuanya otomatis)
3. Deactivate → Deactivating → Inactive; Activate → Reactivating → Active
4. Delete → Deleted
5. Purge → hilang

Jika pemrosesan gagal atau dibatalkan, dokumen berhenti di Failed atau Cancelled. Dari sana, retry kembali ke langkah 1, dan purge menghapusnya.

Polling

Webhook belum tersedia. Untuk mengetahui kapan dokumen siap, lakukan polling ke Mengambil dokumen setiap 5 sampai 10 detik selama inProgress bernilai true. Berhenti saat nilainya false, lalu periksa status: Active berarti agent bisa memakainya, Failed berarti Anda perlu membaca log. PDF besar yang diproses dengan mode adaptive bisa memakan waktu beberapa menit.

Polling yang jauh lebih sering tidak mempercepat pemrosesan; itu hanya menghabiskan batas request Anda.

Delete dan purge

Pola sinkronisasi yang umum: saat versi baru sebuah SOP disetujui, upload dengan kode baru (misalnya SOP-FIN-007-v4), tunggu sampai Active, lalu hapus (delete) versi sebelumnya. Purge versi lama belakangan, di job pembersihan terpisah yang punya key sendiri dengan scope purge.

Batas

Setiap jawaban 429 menyertakan header Retry-After berisi jumlah detik yang harus ditunggu. Tunggu setidaknya selama itu sebelum mencoba lagi; jangan mengulang dalam loop yang rapat.

Upload memakai credit; jika credit organisasi habis, upload ditolak dengan 402 insufficient_credit (lihat Upload dokumen).

Error

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

{
  "error": {
    "code": "invalid_state",
    "message": "Only an Active document can be deactivated; it is Processing."
  }
}

Bangun logika Anda berdasarkan code. Isi message bisa berubah dan ditujukan untuk manusia (dalam bahasa Inggris).

Log aktivitas

Setiap panggilan API, berhasil maupun gagal, dan setiap perubahan pengaturan dicatat di log aktivitas agent. Contributor melihatnya di halaman Knowledge → Knowledge API, dan bisa memfilternya berdasarkan jenis (panggilan API atau perubahan pengaturan), hasil (berhasil atau gagal), dokumen, dan tanggal.

Entri disimpan selama 90 hari. Log tidak pernah berisi API key maupun isi file Anda.

Pakai log ini untuk memastikan key baru bekerja setelah rotasi, melihat sistem mana yang meng-upload sebuah dokumen, dan mendeteksi panggilan dari alamat IP yang tidak terduga.

Praktik keamanan terbaik

• Simpan key di server. Panggil Knowledge API hanya dari kode back-end, job terjadwal, atau pipeline. 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.
• Simpan sebagai rahasia. Pakai vault atau secret variable pipeline Anda, bukan file konfigurasi yang masuk ke source control. Jangan mencetak key di log.
• Beri setiap sistem scope-nya sendiri. Job pemantauan cukup read. Job sinkronisasi butuh write. Berikan purge hanya pada job yang memang harus menghapus dokumen selamanya.
• Atur expiry. Key yang kedaluwarsa membatasi dampak kebocoran yang tidak Anda sadari. Rencanakan rotasi sebelum tanggal kedaluwarsa.
• Rotasi secara berkala dengan dua slot, seperti dijelaskan di Merotasi key tanpa downtime.
• Segera cabut jika bocor. Jika key mungkin terekspos, cabut di halaman Knowledge → Knowledge API, buat key baru, dan periksa log aktivitas untuk panggilan yang tidak Anda kenali.
• Matikan API jika sudah tidak dipakai.

Troubleshooting

Halaman Terkait

• Dokumen: meng-upload dan mengelola dokumen di CMS, serta mode pemrosesan.
• Sitasi: membuat author untuk dipakai sebagai authorCode dan menampilkan sumber di jawaban.
• Knowledge Permissions: kode permission untuk field permissions.
• Chunks: memeriksa chunk hasil pemecahan dokumen.
• Retrieval: memastikan agent menjawab dari dokumennya.
• Mengajari Agent Anda