Dokumentasi API RAG Chat

Endpoint lengkap, contoh request/response, dan panduan integrasi

Informasi Umum

API ini menyediakan layanan Retrieval-Augmented Generation (RAG) berbasis PHP + SQLite. Setiap percakapan memiliki memori sesi, retrieval dapat dilakukan secara lokal (cosine similarity di SQLite) atau via Pinecone.

Base URLhttps://api.syntaf.com/api
Format RequestJSON (Content-Type: application/json)
Format ResponseJSON
Autentikasi Endpoint ChatTidak memerlukan API key eksternal; API key provider (Fireworks/Sambanova/Upstage/Gemini) dikelola di halaman admin.
Autentikasi AdminPIN admin yang diatur saat setup pertama kali.

Setup Pertama Kali

  1. Upload seluruh isi folder apideploy/ ke root domain/subdomain Hostinger.
  2. Pastikan PHP 8.1+ aktif dengan ekstensi: pdo_sqlite, curl, json, mbstring.
  3. Buka https://api.syntaf.com/index.php di browser untuk menjalankan setup wizard.
  4. Atur PIN admin, API key provider, dan konfigurasi Pinecone (opsional).
  5. Setelah setup selesai, API siap digunakan.
Catatan: Jika setup belum selesai, endpoint /api/chat.php akan mengembalikan HTTP 503 dengan pesan setup not complete.

Endpoint

POST /api/chat.php

Mengirim pertanyaan ke chatbot RAG dan mendapatkan jawaban berdasarkan seluruh koleksi buku yang tersedia. Jika ingin membatasi ke satu buku, kirim book_id.

Request Body

FieldTipeWajibKeterangan
book_idintegerTidakID buku untuk membatasi pencarian. Jika tidak dikirim, sistem mencari di semua buku.
querystringYaPertanyaan atau pesan pengguna.
providerstringTidakLLM provider: fireworks, sambanova, upstage. Jika tidak dikirim, sistem memilih otomatis berdasarkan default admin atau provider pertama yang memiliki API key aktif.
retrievalstringTidakMetode retrieval: local (SQLite) atau pinecone. Jika tidak dikirim, menggunakan default yang diatur admin (saat ini: pinecone).
session_idstringTidakID sesi untuk mempertahankan memori percakapan. Jika dikosongkan, sistem membuat sesi baru.
top_kintegerTidakJumlah halaman top-K yang diambil. Default dari konfigurasi (biasanya 3).
context_windowintegerTidakJumlah halaman sebelum/sesudah halaman top-K yang disertakan. Default dari konfigurasi.

Contoh Request ke Semua Buku

Cukup kirim query; pencarian akan mencakup seluruh koleksi buku.

curl -X POST https://api.syntaf.com/api/chat.php \
  -H "Content-Type: application/json" \
  -d '{
    "query": "apa itu gizi?",
    "session_id": "sesi-001"
  }'

Contoh Request ke Buku Tertentu

Kirim book_id untuk membatasi pencarian ke satu buku.

curl -X POST https://api.syntaf.com/api/chat.php \
  -H "Content-Type: application/json" \
  -d '{
    "book_id": 1,
    "query": "apa itu gizi?",
    "session_id": "sesi-001"
  }'

Contoh Request dengan Override Provider/Retrieval

Kirim provider dan/atau retrieval untuk menimpa pengaturan admin.

curl -X POST https://api.syntaf.com/api/chat.php \
  -H "Content-Type: application/json" \
  -d '{
    "query": "apa itu gizi?",
    "provider": "sambanova",
    "retrieval": "pinecone",
    "session_id": "sesi-001"
  }'

Contoh Response Sukses (HTTP 200)

{
  "book_id": null,
  "query": "apa itu gizi?",
  "provider": "fireworks",
  "retrieval": "pinecone",
  "answer": "Gizi adalah proses tubuh menerima dan menggunakan zat makanan...",
  "matched_pages": [
    {"book_id": 1, "page_number": 76, "score": 0.7013},
    {"book_id": 1, "page_number": 32, "score": 0.6795},
    {"book_id": 2, "page_number": 5, "score": 0.6718}
  ],
  "session_id": "sesi-001"
}

Contoh Response Gagal (HTTP 400 / 503)

{
  "error": "query is required"
}
{
  "error": "setup not complete. run index.php first."
}

Pengaturan Default oleh Admin

Admin dapat mengatur nilai default melalui halaman https://api.syntaf.com/admin.php:

PengaturanNilai Saat IniDeskripsi
Default ProviderupstageProvider LLM yang digunakan ketika request tidak menyertakan provider. Jika kosong/tidak valid, sistem otomatis memilih provider pertama yang memiliki API key aktif.
Default RetrievalpineconeMetode retrieval yang digunakan ketika request tidak menyertakan retrieval.
Prioritas pemilihan provider:
  1. provider yang dikirim di request (jika valid).
  2. Default provider dari pengaturan admin.
  3. Provider pertama yang memiliki API key aktif di database.

Parameter Retrieval

NilaiDeskripsiKapan Digunakan
localMenghitung cosine similarity langsung dari vektor embedding yang tersimpan di SQLite.Cepat untuk buku kecil-menengah; tidak memerlukan Pinecone.
pineconeMengambil vektor terdekat dari index Pinecone via REST API.Untuk koleksi besar atau jika vektor sudah di-upload ke Pinecone.
Tips: Pastikan buku sudah memiliki embedding (dimensi 1024) sebelum menggunakan retrieval local. Untuk pinecone, pastikan vektor buku sudah di-upload ke index Pinecone yang dikonfigurasi.

Memori Sesi (Context Memory)

API menyimpan riwayat percakapan per session_id dalam file JSON di server. Jika session_id tidak dikirim, sistem akan membuat ID baru dan mengembalikannya di response.

Untuk melanjutkan percakapan, kirim kembali session_id yang sama pada request berikutnya. LLM akan menerima riwayat pesan sebelumnya sebagai konteks.

{
  "book_id": 1,
  "query": "jelaskan lebih detail",
  "session_id": "sesi-001"
}

Provider LLM

API mendukung rotasi API key untuk beberapa provider. Provider aktif diatur di halaman admin.

ProviderParameter providerKeterangan
Fireworks AIfireworksDefault provider.
Sambanova AIsambanovaAlternatif provider.
Upstage AIupstageAlternatif provider.

Embedding selalu menggunakan Gemini Embedding API dengan output 1024 dimensi.

Manajemen Buku & API Key

Fitur administratif tersedia di halaman terpisah yang dilindungi PIN:

Catatan keamanan: Halaman admin memerlukan PIN. Dokumentasi ini bersifat publik dan tidak menyertakan PIN.

Kode Status HTTP

StatusArti
200Request berhasil.
400Bad request, parameter tidak valid atau tidak lengkap.
405Method tidak diizinkan (hanya menerima POST).
503Setup belum selesai atau service tidak tersedia.

Contoh Integrasi (JavaScript/Fetch)

async function chat(bookId, query, sessionId = "") {
  const res = await fetch("https://api.syntaf.com/api/chat.php", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      book_id: bookId,
      query: query,
      session_id: sessionId
      // provider & retrieval opsional; akan dipilih otomatis oleh server
    })
  });
  const data = await res.json();
  console.log(data.answer);
  console.log("provider:", data.provider);
  console.log("retrieval:", data.retrieval);
  console.log("session_id:", data.session_id);
  return data;
}

Catatan Hostinger