Pahami endpoint rekomendasi AI.

Auth dan batas akses

• Wajib header X-API-Key.
• Jika API key tidak dikirim, endpoint mengembalikan API_KEY_REQUIRED dengan status 401.
• Jika API key tidak valid atau sudah kedaluwarsa, endpoint mengembalikan API_KEY_INVALID dengan status 401.
• Rate limit saat ini 30 request per menit untuk tier biasa dan 120 request per menit untuk tier enterprise.
• Jika kuota habis, endpoint mengembalikan RATE_LIMIT_EXCEEDED dengan status 429.

GET /api/ai/recommend?q=web%20development&city=Jakarta&limit=5
X-API-Key: qelar_live_xxx

Query parameter

• q: wajib, minimal 2 karakter, maksimal 200 karakter.
• city: opsional.
• limit: opsional, dibatasi 1 sampai 10.

Field respons yang penting

• data[] mengikuti hasil search publik, lalu ditambah field reason.
• meta.city bisa bernilai null jika query kota tidak dikirim.
• meta.rrf dan meta.tookMs membantu observasi kualitas dan performa hasil.
• Header rate limit seperti x-ratelimit-limit ikut dikirim di response.

Respons sukses

{
  "data": [
    {
      "slug": "acme-studio",
      "reason": "Ranked by hybrid retrieval (keyword + vector) with Reciprocal Rank Fusion (RRF)."
    }
  ],
  "meta": {
    "q": "web development",
    "city": "Jakarta",
    "total": 1,
    "limit": 5,
    "source": "hybrid",
    "rrf": {
      "k": 60,
      "keywordCandidates": 4,
      "vectorCandidates": 4,
      "mergedCandidates": 4
    },
    "tookMs": 12
  }
}

Respons error

Endpoint ini punya tiga kelompok error utama: autentikasi, rate limit, dan validasi query.

{
  "error": {
    "code": "API_KEY_REQUIRED",
    "message": "API Key diperlukan. Dapatkan di dashboard QELAR Pro."
  }
}

{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "API Key tidak valid atau sudah kedaluwarsa."
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Coba lagi nanti."
  }
}

{
  "error": {
    "code": "QUERY_REQUIRED",
    "message": "Query `q` wajib diisi.",
    "details": null
  }
}

{
  "error": {
    "code": "QUERY_TOO_SHORT",
    "message": "Query minimal 2 karakter.",
    "details": null
  }
}

{
  "error": {
    "code": "QUERY_TOO_LONG",
    "message": "Query maksimal 200 karakter.",
    "details": null
  }
}