API Pencarian & Discovery

GET /api/v1/search

Endpoint ini dipakai untuk pencarian provider publik dengan pencarian gabungan dan filter yang paling lengkap.

Autentikasi: tidak perlu.
Query wajib: q.
Query opsional: page, limit, city, location, categorySlug, minTrustLevel, minRating, industry, projectBudget, businessSize, capabilityTag, hourlyRateMin, hourlyRateMax, sort.
Jika q kosong, error yang dikembalikan adalah QUERY_REQUIRED. Jika kurang dari 2 karakter, error-nya QUERY_TOO_SHORT.

GET /api/v1/search?q=web%20development&city=Jakarta&categorySlug=digital-infrastructure&limit=10

{
  "data": [
    {
      "id": "provider-1",
      "slug": "acme-studio",
      "companyName": "Acme Studio",
      "search": {
        "source": "hybrid",
        "rrfScore": 0.03125,
        "keywordRank": 1,
        "vectorRank": 2
      }
    }
  ],
  "meta": {
    "q": "web development",
    "page": 1,
    "limit": 20,
    "total": 1,
    "source": "hybrid"
  }
}

GET /api/v1/discovery/programmatic-params

Endpoint ini dipakai untuk membentuk kombinasi kategori dan kota yang layak dijadikan halaman discovery programatik.

Autentikasi: tidak perlu.
Query opsional: limit. Nilai default saat ini 500, maksimal 1000.
Backend hanya mengambil provider yang sudah tayang, punya kota, dan memenuhi ambang trustLevel >= 1.

GET /api/v1/discovery/programmatic-params?limit=100

{
  "data": [
    {
      "categorySlug": "digital-infrastructure",
      "city": "Jakarta",
      "citySlug": "jakarta",
      "path": "/digital-infrastructure-terbaik-jakarta"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 500,
    "trustThreshold": 1
  }
}

GET /api/v1/discovery/programmatic

Endpoint ini dipakai untuk membaca daftar provider pada satu kombinasi kategori dan kota.

Autentikasi: tidak perlu.
Query wajib: categorySlug dan citySlug.
Query opsional: city, page, limit.
Jika kategori tidak ditemukan, endpoint mengembalikan CATEGORY_NOT_FOUND.

GET /api/v1/discovery/programmatic?categorySlug=digital-infrastructure&citySlug=jakarta

GET /api/v1/discovery/compare

Endpoint ini dipakai untuk membandingkan dua provider yang sudah tayang dan memberi konteks apakah perbandingan itu memang relevan.

Autentikasi: tidak perlu.
Query wajib: slugA dan slugB.
Jika slug sama, endpoint mengembalikan SLUG_DUPLICATE.
Jika salah satu provider tidak ditemukan, endpoint mengembalikan PROVIDER_NOT_FOUND.
Respons meta.comparisonContext menjelaskan alasan mengapa dua provider bisa dibandingkan.

GET /api/v1/discovery/compare?slugA=acme-studio&slugB=beta-labs

{
  "data": [
    {
      "slug": "acme-studio",
      "proofSummary": {
        "totalPublicProofs": 8
      }
    }
  ],
  "meta": {
    "comparisonContext": {
      "comparable": true,
      "rule": "same_service_industry"
    }
  }
}