# intent-search API

> รุ่นของเอกสาร: `dbab9fa (2026-11-16)`

เอกสาร `/docs` ทั้งหมดในไฟล์เดียว สำหรับโปรแกรมที่ได้ API key มาจากลูกค้า สร้างจากข้อมูลชุดเดียวกับหน้าเว็บ และตัวอย่างทุกตัวถูกรันกับระบบจริงทุกครั้งที่ตรวจ

- **Base URL:** `https://api.intent-search.dev`
- **TypeScript:** `https://intent-search.dev/docs/types.ts` คือ type ของทุกคำขอและคำตอบ ในไฟล์เดียวที่ไม่มี import — `V1.<ชื่อ>Ask` กับ `V1.<ชื่อ>Reply` ของทุกเส้น และ `V1.Routes` ที่จับคู่ method กับ path ให้ · ตัวอย่างทุกตัวในไฟล์นี้ถูกตรวจกับ type เหล่านั้นทุกครั้งที่ build
- **ยืนยันตัวตน:** ทุกคำขอใส่ `Authorization: Bearer <key>` — key บอกเองว่าเป็นชุดข้อมูลไหน ไม่มี id ของชุดข้อมูลใน URL
- **service key** ใช้ได้ทุกเส้น เก็บไว้ฝั่งเซิร์ฟเวอร์ · **client key** ค้นได้อย่างเดียว ใส่ในหน้าเว็บได้ · service key ที่ส่งจากหน้าเว็บ (มี `Origin`) ยังได้คำตอบ แต่มีคำเตือน `service_key_in_browser` — ในหน้าเว็บใช้ client key และเพิ่มโดเมนด้วย `PUT /v1/origins` · ระหว่างพัฒนาใส่ `http://localhost:*` ให้ dev server ใช้ได้ทุกพอร์ต
- **เนื้อคำขอ** เป็น JSON และต้องมี `Content-Type: application/json`
- **ข้อผิดพลาด** ทุกตัวมีรูปเดียว `{"error": "…"}` เป็นประโยคภาษาอังกฤษ รหัสทั้งหมดอยู่ท้ายไฟล์
- **พารามิเตอร์ใน URL:** มีแค่ `POST /v1/search` (`broaden`) และ `GET /v1/suggest` (`q` `n` `from` `field` `products`) ที่อ่าน เส้นอื่นได้ `400` ก่อนทำอะไร · ตัวเลือกทุกตัวอยู่ในเนื้อคำขอ
- **`429`:** รอตาม `Retry-After` แล้วส่งซ้ำ · `402` ลองซ้ำแล้วได้คำตอบเดิม อย่าวน · หน้าที่เรนเดอร์บนเซิร์ฟเวอร์ส่ง `X-End-User` ให้ผู้เข้าชมแต่ละคนได้ส่วนแบ่งของตัวเอง

## สิ่งที่เปลี่ยน

คำตอบที่เปลี่ยนรูปจนโค้ดที่เขียนไว้ก่อนต้องแก้ตาม ใหม่สุดก่อน · การเปลี่ยนที่ลงวันที่ไม่เกินวันท้ายบรรทัด “รุ่นของเอกสาร” อยู่ในไฟล์นี้แล้ว

- **2026-10-24** `GET /v1/pins` — ปิดแล้วทั้ง `GET` และ `PUT` ปักหมุดยังไม่เปิดใน phase นี้ และหมุดที่ตั้งไว้ถูกลบทั้งหมด · `POST /v1/search` ที่ส่ง `pinned` มาได้ `400` · **ที่ต้องแก้:** เลิกเรียก `/v1/pins` และเอา `pinned` ออกจากคำค้น
- **2026-10-21** `POST /v1/search` — ผลแต่ละชิ้นไม่มี `"reached": true` แล้ว ใช้ `words` แทน: `typed` คำที่พิมพ์เจอตรง ๆ · `compound` เจอเพราะคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำที่พิมพ์เท่านั้น (คือที่เคยเป็น `reached: true`) · `widened` คำที่พิมพ์ไม่เจออะไร ผลนี้มาจากคำถามที่กว้างกว่า · ไม่มี `words` เมื่อความหมายอย่างเดียวเจอ · **ที่ต้องแก้:** เปลี่ยน `hit.reached` เป็น `hit.words === "compound"`
- **2026-10-21** `POST /v1/filters/:field` — บนหน้าที่ไล่ด้วย `after` คีย์ `other` นับเฉพาะสิ่งที่อยู่หลังหน้านี้ เดิมรวมหน้าก่อน ๆ ไปด้วย · คีย์ใหม่ `other_values` คือจำนวนค่าที่ยังเหลือ และ `note` นับจากตัวนี้ · หน้าสุดท้ายไม่มี `next` แล้ว เดิมได้ `next` แล้วหน้าถัดไปว่าง · `missing` มาด้วยแล้ว · เรียงแบบ `value` พร้อม `size` ได้ค่าแรกตามลำดับไทยจริง · **ที่ต้องแก้:** หยุดไล่เมื่อไม่มี `next` ไม่ต้องรอหน้าว่าง และอ่านจำนวนค่าที่เหลือจาก `other_values` ไม่ใช่ `other`
- **2026-10-21** `POST /v1/search` — ตัวกรองวันที่ที่ร้านบันทึกไว้ส่งเฉพาะช่องที่มีสินค้า เดิมส่งช่องว่างระหว่างช่องแรกถึงช่องสุดท้ายด้วย · เลือกขั้นได้ครบ minute hour day week month quarter year แต่ต้องไม่เกิน 200 ช่อง และเมื่อสินค้าใหม่ดันให้เกินจะได้ 200 ช่องล่าสุดพร้อม `degraded.reason: "facet_buckets_capped"` · **ที่ต้องแก้:** ถ้าวาดกราฟจาก `aggregations` ของตัวกรองวันที่ ให้เติมช่องที่ว่างเอง
- **2026-10-21** `GET /v1/categories` — สินค้าที่ห่างทุกหมวดเกิน `min_score` (ค่าเริ่มต้น 0.6) ไม่ถูกจัดเข้าหมวดไหน เดิมได้หมวดที่ใกล้ที่สุดเสมอ · ระเบียนนั้นไม่มีคอลัมน์หมวด ตัวกรองหมวดนับไว้ใน `missing` และ `progress.unfit` บอกจำนวน · ตั้ง `min_score` ได้ใน `PUT /v1/categories` และเปลี่ยนแค่ค่านี้ไม่ทำให้จัดหมวดใหม่ · **ที่ต้องแก้:** อย่าถือว่าทุกระเบียนมีหมวด
- **2026-10-21** `GET /v1/documents/:id` — id ใน path ถูกถอดรหัสครั้งเดียวตามมาตรฐาน เดิมถอดสองครั้ง id ที่มี `%` อ่านหรือลบไม่ได้ และ `DELETE /v1/documents/sku%2541` ลบ `skuA` ผิดชิ้น · ใช้กับ `DELETE /v1/documents/:id` และ `POST /v1/filters/:field` ด้วย · **ที่ต้องแก้:** encode id ครั้งเดียวด้วย `encodeURIComponent` ถ้าเคย encode สองครั้งเพื่อเลี่ยงปัญหานี้ ให้เอาครั้งที่สองออก
- **2026-10-18** `POST /v1/search` — `counted_from` มาคู่กับ `counted_over` และบอกว่าตัวเลขใน `aggregations` นับจากอะไร: `matches` ระเบียนที่คำค้นเจอ · `words` ระเบียนที่ฝั่งคำของ `hybrid` เจอ ผลที่ตรงความหมายอย่างเดียวไม่ถูกนับ · `all` ทุกระเบียนในชุดข้อมูล สำหรับ `vector` ไม่ใช่เฉพาะผล · การค้นด้วยความหมายที่ไม่ได้นับอะไรไม่มี `counted_over` แล้ว เดิมได้ค่าเท่ากับ `total` · **ที่ต้องแก้:** อ่าน `counted_over` เฉพาะเมื่อมี และดู `counted_from` ก่อนขึ้นข้อความว่าตัวเลขนับจากอะไร
- **2026-10-04** `POST /v1/search` — `reached` ออกจาก `broadened` มาเป็นคีย์ของคำตอบเอง — เดิม `{"query":"รองเท้า"}` ที่เจอตรง ๆ สี่รายการก็ได้ `broadened: {"reached": [...]}` มาด้วย ตอนนี้ `broadened` มีเฉพาะเมื่อคำที่พิมพ์ไม่เจออะไรเลย · **ที่ต้องแก้:** อ่าน `reached` แทน `broadened.reached` · ข้อความ “ไม่พบผลที่ตรง” ที่ขึ้นเมื่อมี `broadened` ถูกแล้วโดยไม่ต้องแก้
- **2026-10-04** `POST /v1/search` — `answered` มากับทุกคำตอบ ทุก `mode` — เดิมมีเฉพาะ `mode: "auto"` · `reason` เพิ่ม `mode_asked` และ `no_mode` · **ที่ต้องแก้:** ถ้าเคยถือว่ามี `answered` แปลว่าใช้ `auto` ให้ดู `mode` ที่ส่งไปเอง และอ่าน `answered.by` ว่าตอบด้วยคำหรือความหมาย

## ลำดับงานตั้งแต่ไม่มีอะไร

รันตามลำดับนี้ได้เลย เปลี่ยนแค่ข้อมูลเป็นของร้าน · หลังเปิดการค้นด้วยความหมาย ให้รอตามหมายเหตุของ `GET /v1/vectors` ในส่วนอ้างอิง

### 1. ตัวช่วยเรียก API ที่ล้มดัง ๆ เมื่อได้คำตอบที่ไม่ใช่ 2xx

```ts
const NS = process.env.NS_URL ?? "https://api.intent-search.dev"

async function ns(method: string, path: string, body?: unknown) {
  const r = await fetch(NS + path, {
    method,
    headers: {
      authorization: `Bearer ${process.env.NS_KEY}`,
      ...(body === undefined ? {} : { "content-type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  const reply = await r.json()
  // ข้อผิดพลาดทุกตัวมีรูปเดียว: { "error": "ข้อความให้คนอ่าน" }
  if (!r.ok) throw new Error(`${method} ${path}: ${r.status} ${reply.error}`)
  return reply
}
```

### 2. ระเบียนตามที่ฐานข้อมูลของร้านเก็บ

```ts
const products = [
  { id: "sku-1042", product_name: "เซรั่มวิตามินซี ลดริ้วรอย", brand: "Aurora",
    price: 890, in_stock: true, raw: { supplier: "S-12", rank: 4 } },
  { id: "sku-1043", product_name: "ครีมกันแดดเนื้อบางเบา SPF50", brand: "Aurora",
    price: 450, in_stock: false },
  { id: "sku-2001", product_name: "กระถางต้นไม้ดินเผา ขนาดกลาง", brand: "Terra",
    price: 120, in_stock: true },
]
```

### 3. ส่งระเบียน แล้ว sync ให้ขึ้นดัชนี

```ts
// ครั้งละไม่เกิน 5,000 ระเบียน ส่งหลายครั้งได้ แล้ว sync ครั้งเดียว
const written = await ns("POST", "/v1/documents", { documents: products })

// ครั้งแรก ระบบอ่านทั้ง batch แล้วบอกว่าตัดสินโครงไว้อย่างไร
console.log(written.schema?.fields)
// และทุกฟิลด์ว่าค่าที่ส่งมาเป็นชนิดอะไร กี่ค่าที่ไม่ได้ลงดัชนี
console.log(written.report)

// ทุกอย่างที่พักไว้ ขึ้นดัชนีพร้อมกันตรงนี้
const run = await ns("POST", "/v1/sync")
console.log(`ส่งเข้าดัชนี ${run.sent} ระเบียน`)
```

### 4. ค้นด้วยข้อความที่คนพิมพ์

```ts
const results = await ns("POST", "/v1/search", {
  query: "เซรั่ม", // ข้อความจากกล่องค้นหา ส่งตรง ๆ ได้เลย
  size: 20,
})

for (const hit of results.hits) {
  // hit.document คือระเบียนเต็มของคุณ ทุกฟิลด์ รวม raw ที่ไม่ได้ลงดัชนี
  console.log(hit.document.product_name, hit.matched)
}
```

### 5. ปรับโครง — ลองด้วย dry_run ในเนื้อคำขอก่อน

```ts
// ไม่ถูกใจโครงที่อนุมาน? เปลี่ยนได้โดยไม่ต้องส่งข้อมูลใหม่
const plan = await ns("PUT", "/v1/schema", {
  fields: [
    { name: "product_name", type: "text", search: { weight: 3 } },
    { name: "brand", type: "text", search: true, filter: { kind: "terms", label: "ยี่ห้อ" } },
    { name: "price", type: "number", sort: true },
    { name: "in_stock", type: "boolean", filter: true },
  ],
  dry_run: true, // ดูก่อนว่าจะเปลี่ยนอะไร เอาออกเมื่อพร้อม
})
console.log(plan.changes, plan.reindex)
```

### 6. เปิดการค้นด้วยความหมาย

```ts
// เปิดการค้นด้วยความหมาย ครั้งเดียวแล้วปล่อยไว้ — โมเดลอ่านทุกระเบียนให้เอง
await ns("PUT", "/v1/vectors", { enabled: true })

// ระหว่างที่ยังสร้างไม่เสร็จ hybrid ได้ผลด้วยคำพร้อม degraded บอกว่ารออยู่
const meant = await ns("POST", "/v1/search", { query: "อยากดูเด็กลง", mode: "hybrid" })
console.log(meant.degraded?.reason ?? "ใช้ความหมายแล้ว")
```

### 7. หน้าร้าน: คำค้น ตัวกรองที่ติ๊ก และหน้าถัดไป

```ts
// หน้าร้านหนึ่งหน้า: คำที่ลูกค้าพิมพ์ ตัวกรองที่ติ๊กไว้ และแถบเลขหน้า
// ทุกอย่างอยู่ในเนื้อคำขอ — key บอกเองว่าเป็นชุดข้อมูลไหน
// auto: ชื่อ ยี่ห้อ รหัส ตอบด้วยคำ ส่วนความต้องการตอบด้วยความหมาย นับโควตาเฉพาะครั้งนั้น
const asked = { query: "Aurora", mode: "auto", filters: { brand: ["Aurora"] }, size: 1 }
// pages คือเลขหน้าสุดท้ายที่แถบเลขหน้าจะชี้ไป (ตอบด้วยความหมายไม่มีเคอร์เซอร์ ใช้ from แทน)
const page = await ns("POST", "/v1/search", { ...asked, pages: 5 })
console.log(page.answered.by, page.answered.reason) // words looks_like_a_name

// จำนวนของแต่ละค่า นับจากคำค้นเดียวกับผล — วาดเป็นช่องติ๊กได้เลย
for (const [field, counted] of Object.entries(page.aggregations ?? {})) {
  const values = (counted as { buckets: { key: string; count: number }[] }).buckets
  console.log(field, values.map((b) => `${b.key} (${b.count})`).join(", "))
}

// แถบเลขหน้า: pages[k] คือ search_after ที่เริ่มหน้า k — เก็บไว้กับหน้าที่วาด แล้วส่งเมื่อถูกคลิก
const pageCount = Math.ceil(page.total / asked.size)
console.log(`มี ${pageCount} หน้า เคอร์เซอร์ถึงหน้า ${Object.keys(page.pages ?? {}).at(-1) ?? 1}`)
if (page.pages?.["2"]) {
  const second = await ns("POST", "/v1/search", { ...asked, search_after: page.pages["2"] })
  console.log(second.hits.map((hit: { id: string }) => hit.id))
}
// ไปทีละหน้าก็ได้แบบเดิม: search_after จาก next · ไม่มี next คือหน้าสุดท้าย
```

### 8. หน้าร้านที่เรนเดอร์บนเซิร์ฟเวอร์: แคชสั้น ๆ และ X-End-User

```ts
// หน้าร้านที่เรนเดอร์บนเซิร์ฟเวอร์: ทุกคนที่เปิดหน้ามาถึงด้วย key เดียวกันของเซิร์ฟเวอร์
// แคชสั้น ๆ ตามคำขอ — คำค้น ตัวกรอง และหน้า — หน้าที่ถูกเปิดซ้ำจึงไม่ต้องถามใหม่
const cache = new Map<string, { at: number; reply: any }>()
const FRESH_MS = 30_000

async function searchFor(visitor: string, wanted: object) {
  const key = JSON.stringify(wanted)
  const kept = cache.get(key)
  if (kept && Date.now() - kept.at < FRESH_MS) return kept.reply

  const r = await fetch(NS + "/v1/search", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.NS_KEY}`,
      "content-type": "application/json",
      // ใครเป็นคนขอ: id ทึบของผู้เข้าชม หรือ IP ของเขา (ไม่ใช่อีเมล)
      // แต่ละคนได้หนึ่งในสี่ของอัตราของ key คนเดียวที่เปิดหลายแท็บจึงไม่ทำให้คนอื่นได้ 429
      "x-end-user": visitor,
    },
    body: JSON.stringify(wanted),
  })
  const reply = await r.json()
  // ถูกบอกให้รอ แต่มีคำตอบเก่าอยู่ ส่งของเก่าไปก่อนดีกว่าหน้าว่าง
  if (r.status === 429 && kept) return kept.reply
  if (!r.ok) throw new Error(`POST /v1/search: ${r.status} ${reply.error}`)

  if (cache.size >= 500) cache.delete(cache.keys().next().value!)
  cache.set(key, { at: Date.now(), reply })
  return reply
}

// ในตัวจัดการคำขอของเว็บ: IP ของผู้เข้าชม หรือ id ที่เก็บไว้ใน cookie
// IP คือค่าแรกของ x-forwarded-for เมื่อเว็บอยู่หลัง proxy ที่คุณไว้ใจ ไม่อย่างนั้นคือ address
// ของ socket ที่ต่อเข้ามา · ผู้เข้าชมปลอมค่านี้ได้ แต่คนที่ปลอมก็ได้แค่ส่วนแบ่งของตัวเอง
// ตัวกรองที่ติ๊กและ search_after ของหน้าถัดไปอยู่ในคำขอเดียวกัน จึงเป็นส่วนหนึ่งของคีย์แคชด้วย
const first = await searchFor("203.0.113.7", { query: "เซรั่ม", size: 20 })
const again = await searchFor("198.51.100.4", { query: "เซรั่ม", size: 20 })
console.log(first.total, again === first ? "จากแคช" : "ถามใหม่")
```

# อ้างอิง

## ข้อมูล

### `POST /v1/documents` — ส่งระเบียนเข้ามา

เพิ่มหรือเขียนทับระเบียนในชุดข้อมูลที่คีย์นี้ผูกอยู่ แล้วพักไว้จนกว่าจะเรียก sync

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `documents` (array, ต้องมี) — 1 ถึง 5,000 ระเบียนต่อคำขอ และเนื้อคำขอไม่เกิน 32 MB · ไฟล์ที่ใหญ่กว่านั้นแบ่งส่งหลายรอบ แล้วค่อย sync ครั้งเดียว
- `documents[].id` (string | number, ต้องมี) — id ของระเบียน · ชื่อคอลัมน์เปลี่ยนได้ด้วย `id_field` ของ `PUT /v1/schema` ก่อนเขียนครั้งแรก เช่นข้อมูลที่ใช้ `itemId` · ส่ง id เดิมซ้ำคือเขียนทับ · ตัวเลขใช้ได้ถึง 2^53 เกินกว่านั้นให้ส่งเป็นสตริง
- `documents[].*` (any) — ฟิลด์อื่นเป็นของคุณทั้งหมด เก็บไว้ครบและส่งกลับมาทั้งระเบียนพร้อมผลค้นหา รวมถึงฟิลด์ที่ซ้อนกันและฟิลด์ที่ไม่ได้ลงดัชนี · ชื่อที่ขึ้นต้นด้วย `ns_` สงวนไว้ให้ระบบ

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/documents" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "documents": [
    {
      "id": "sku-1042",
      "product_name": "เซรั่มวิตามินซี ลดริ้วรอย",
      "brand": "Aurora",
      "price": 890,
      "in_stock": true,
      "raw": {
        "supplier": "S-12",
        "rank": 4
      }
    },
    {
      "id": "sku-1043",
      "product_name": "ครีมกันแดดเนื้อบางเบา SPF50",
      "brand": "Aurora",
      "price": 450,
      "in_stock": false
    },
    {
      "id": "sku-2001",
      "product_name": "กระถางต้นไม้ดินเผา ขนาดกลาง",
      "brand": "Terra",
      "price": 120,
      "in_stock": true
    }
  ]
}'
```

**คำตอบ**

```json
{
  "received": 3,
  "stored": 3,
  "changed": 3,
  "schema": {
    "inferred": true,
    "id_field": "id",
    "fields": [
      {
        "name": "product_name",
        "type": "text",
        "search": {
          "weight": 2
        },
        "filter": false,
        "sort": false
      },
      {
        "name": "brand",
        "type": "text",
        "search": {
          "weight": 1
        },
        "filter": {
          "kind": "terms"
        },
        "sort": false
      },
      {
        "name": "price",
        "type": "number",
        "search": false,
        "filter": false,
        "sort": true
      },
      {
        "name": "in_stock",
        "type": "boolean",
        "search": false,
        "filter": {
          "kind": "terms"
        },
        "sort": true
      }
    ],
    "stored_only": [
      {
        "name": "raw",
        "reason": "its values are objects, which no field type holds"
      }
    ],
    "note": "read from this batch; change any of it with PUT /v1/schema without sending the documents again"
  },
  "report": {
    "product_name": {
      "types": {
        "string": 3,
        "number": 0,
        "boolean": 0,
        "object": 0,
        "empty": 0
      },
      "indexed_as": "text",
      "not_indexed": 0
    },
    "price": {
      "types": {
        "string": 0,
        "number": 3,
        "boolean": 0,
        "object": 0,
        "empty": 0
      },
      "indexed_as": "number",
      "not_indexed": 0
    }
  },
  "note": "staged — call POST /v1/sync to publish"
}
```

คีย์ที่มีบางครั้ง: `schema` `duplicates` `duplicates_note`

**หมายเหตุ**

- **ส่งแล้วยังค้นไม่เจอ** — ระเบียนถูกพักไว้ก่อน แล้ว `POST /v1/sync` เป็นตัวส่งเข้าดัชนีทีเดียว แยกกันเพราะไฟล์หนึ่งไฟล์คือหลายคำขอ และคุณไม่อยากให้ร้านเห็นสินค้าครึ่งไฟล์ **ของที่ส่งผ่านเส้นนี้ขึ้นดัชนีเมื่อคุณเรียก sync เท่านั้น** ตัวส่งอัตโนมัติไม่แตะ
- **ครั้งแรกไม่ต้องตั้งอะไรก่อน** — ถ้าชุดข้อมูลยังไม่มีโครง ระบบอ่านทั้ง batch แรกแล้วตัดสินให้ว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้ (คอลัมน์ที่ค่าซ้ำกันอย่างยี่ห้อเป็นทั้งตัวกรองและค้นด้วยคำได้ น้ำหนักรองจากชื่อสินค้า) แล้วตอบโครงนั้นกลับมาในคีย์ `schema` พร้อมเหตุผลของฟิลด์ที่เก็บไว้เฉย ๆ ไม่ลงดัชนี (ลิงก์ ออบเจกต์) · ไม่ถูกใจแก้ได้ด้วย `PUT /v1/schema` โดยไม่ต้องส่งข้อมูลใหม่
- `report` บอกทุกฟิลด์ว่าค่าที่มาเป็นชนิดอะไรบ้างกี่ค่า ลงดัชนีเป็นอะไร และกี่ค่าที่เก็บไว้ในระเบียนแต่ไม่ได้ลงดัชนีเพราะไม่เข้ากับชนิดของฟิลด์ — เช่น `brand` ที่เป็นสตริงเกือบทุกแถวแต่เป็นออบเจกต์อยู่ 21 แถว · ค่าที่ไม่เข้าชนิดไม่ทำให้ทั้ง batch ถูกปฏิเสธ
- `stored` คือจำนวน id ที่ไม่ซ้ำ `changed` คือที่ใหม่หรือเปลี่ยนจากที่เก็บไว้ ซึ่งเป็นสิ่งที่ sync ครั้งถัดไปจะส่ง · id ที่มาซ้ำในคำขอเดียวเก็บตัวสุดท้าย และบอกจำนวนใน `duplicates`
- เพดานจำนวนระเบียนเป็นของแพ็กเกจ ถ้าคำขอนี้จะทำให้เกิน ทั้งก้อนถูกปฏิเสธก่อนเขียนอะไรลงไป

**ข้อผิดพลาด**

- `400` — เนื้อคำขอผิดรูป · ระเบียนไม่มี id (ข้อความบอกชื่อคอลัมน์ที่น่าจะเป็น id) · มีฟิลด์ที่ขึ้นต้นด้วย `ns_` · มีอักขระ NUL
- `402` — จำนวนระเบียนจะเกินเพดานของแพ็กเกจ
- `403` — ใช้ client key — เส้นนี้ต้องใช้ service key
- `413` — เนื้อคำขอเกิน 32 MB

### `POST /v1/documents/remove` — ลบหลายระเบียน

เอาระเบียนออกตาม id ทีละหลายตัว แล้วพักไว้จนกว่าจะเรียก sync

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `ids` (array, ต้องมี) — id ที่จะลบ 1 ถึง 5,000 ตัว

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/documents/remove" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "sku-2001",
    "sku-9999"
  ]
}'
```

**คำตอบ**

```json
{
  "removed": 1,
  "missing": [
    "sku-9999"
  ],
  "missing_count": 1,
  "note": "staged — call POST /v1/sync to publish"
}
```

คีย์ที่มีบางครั้ง: `missing` `missing_count`

**หมายเหตุ**

- เหมือนการเขียน: ลบแล้วผลค้นหายังเห็นอยู่จนกว่าจะ `POST /v1/sync` — `deleted` ในคำตอบของ sync คือจำนวนที่ถูกเอาออกจากดัชนีจริง
- id ที่ไม่มีอยู่ไม่ใช่ข้อผิดพลาด ถูกบอกไว้ใน `missing` (ยี่สิบตัวแรก) และ `missing_count`

**ข้อผิดพลาด**

- `403` — ใช้ client key

### `GET /v1/documents/:id` — ระเบียนหนึ่งตัว

อ่านระเบียนเต็มตาม id และดูว่าฉบับนี้ขึ้นดัชนีแล้วหรือยัง

- **คีย์:** client key หรือ service key

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/documents/sku-1042" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "id": "sku-1042",
  "document": {
    "product_name": "เซรั่มวิตามินซี ลดริ้วรอย",
    "brand": "Aurora",
    "price": 890,
    "in_stock": true,
    "raw": {
      "supplier": "S-12",
      "rank": 4
    }
  },
  "published": true,
  "updated_at": "2026-09-25T09:30:00.000Z"
}
```

**หมายเหตุ**

- สำหรับหน้าสินค้าหนึ่งชิ้น — ไม่ต้องค้นด้วยชื่อแล้วหวังว่าตัวแรกจะใช่ · ใช้ client key ได้ เพราะระเบียนเดียวกันนี้หน้าเว็บก็ค้นเจออยู่แล้ว
- `published` เป็น `false` เมื่อฉบับที่เก็บไว้ยังไม่ถูก sync ผลค้นหาจึงยังเห็นฉบับก่อนหน้า

**ข้อผิดพลาด**

- `404` — ไม่มีระเบียน id นี้ หรือถูกลบไปแล้ว

### `DELETE /v1/documents/:id` — ลบระเบียนหนึ่งตัว

เอาระเบียนออกตาม id แล้วพักไว้จนกว่าจะเรียก sync

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl -X DELETE "https://api.intent-search.dev/v1/documents/sku-1043" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "removed": 1,
  "note": "staged — call POST /v1/sync to publish"
}
```

คีย์ที่มีบางครั้ง: `missing` `missing_count`

**หมายเหตุ**

- ตัวเดียวกับ `POST /v1/documents/remove` ที่มี id เดียว

**ข้อผิดพลาด**

- `403` — ใช้ client key

### `POST /v1/sync` — ส่งที่พักไว้เข้าดัชนี

ส่งทุกอย่างที่เขียนหรือลบไว้และยังไม่ถึงดัชนี ในครั้งเดียว

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/sync" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**คำตอบ**

```json
{
  "sent": 3,
  "deleted": 0,
  "reregistered": false
}
```

คีย์ที่มีบางครั้ง: `reregistered`

**หมายเหตุ**

- `sent` นับเฉพาะระเบียนที่ใหม่หรือเปลี่ยนตั้งแต่ sync ครั้งก่อน — ส่งไฟล์เดิม 1,451 แถวซ้ำโดยแก้ไป 114 แถว sync จะได้ `sent: 114` ไม่ใช่ข้อมูลหาย
- รอบที่ล้มเหลวตอบ **502** พร้อมเหตุผล ไม่ใช่ 200 · ของที่พักไว้ไม่หายไปไหน เรียกซ้ำได้ทันที
- `reregistered` เป็น `true` เฉพาะเมื่อเอนจินลืมชุดข้อมูลนี้ไป (ดิสก์ถูกสร้างใหม่ สแนปช็อตเก่า) แล้วระบบประกาศมันใหม่และส่งทุกระเบียนให้เอง — เป็นการกู้คืน ไม่ใช่ข้อผิดพลาด
- ของที่แก้จาก**คอนโซล** (ลบ กู้คืน อัปโหลดไฟล์) ถูกส่งให้เองภายในราวหนึ่งนาทีหลังหยุดแก้ แต่ของที่ส่งผ่าน `/v1` รอให้คุณเรียกเส้นนี้เสมอ — ระบบไม่มีวันเอาไฟล์ที่ backend ของคุณส่งยังไม่จบขึ้นร้าน

**ข้อผิดพลาด**

- `402` — แพ็กเกจนี้ใช้พื้นที่เกินเพดานแล้ว
- `502` — เอนจินรับไม่สำเร็จ — ไม่มีอะไรหาย เรียกซ้ำได้

## ค้นหา

### `POST /v1/search` — ค้นหา

ค้นระเบียนด้วยคำ ด้วยความหมาย หรือทั้งสองอย่าง พร้อมตัวกรองและจำนวนของแต่ละค่า

- **คีย์:** client key หรือ service key

**อ่านจาก URL**

- `broaden` (boolean) — ให้คำที่พิมพ์เจอคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำนั้นด้วย และถามใหม่ให้กว้างขึ้นเมื่อไม่เจออะไรเลย · ค่าเริ่มต้นคือเปิด · `false`, `0`, `no`, `off` คือปิด ตัวพิมพ์ไม่สำคัญ · ใส่ในเนื้อคำขอก็ได้

**เนื้อคำขอ**

- `query` (string | object) — **สตริงคือคำที่คนพิมพ์ ตามตัวอักษร** — ทุกคำต้องเจอ (AND) ไม่มีไวยากรณ์ อักขระอย่าง `:` `(` `-` `"` เป็นแค่อักขระ จึงไม่มีวันได้ 400 · วัตถุคือ DSL เต็ม (`bool`, `match`, `term`, `range`, `match_phrase_prefix`, `query_string` …) · ไม่ใส่เลยคือทั้งชุดข้อมูล
- `mode` ("auto" | "keyword" | "vector" | "hybrid") — **`auto` เลือกให้ทีละคำค้น** — ชื่อสินค้า ยี่ห้อ และรหัส (มีตัวเลข หรือไม่เกิน 3 คำ) ตอบด้วยคำ ส่วนคำค้นที่อ่านเหมือนความต้องการ (มีคำอย่าง “สำหรับ” “อยาก” “for” หรือตั้งแต่ 4 คำ เช่น “รองเท้าใส่วิ่งสำหรับคนเท้าแบน”) ตอบด้วยความหมาย และบอกใน `answered` ว่าตอบด้วยอะไรเพราะอะไร · `keyword` `vector` `hybrid` บังคับแบบเดียว · ไม่ใส่คือค้นด้วยคำ · ความหมายใช้ได้เมื่อเปิดด้วย `PUT /v1/vectors` แล้ว ก่อนหน้านั้นได้ผลด้วยคำ · **นับโควตาค้นด้วยความหมายเฉพาะครั้งที่ตอบด้วยความหมายจริง** (Free 1,000 ครั้งต่อเดือน) ไม่ว่าจะมาจาก `auto` `vector` หรือ `hybrid` · เมื่อโควตาหมด ผลยังมาด้วยคำพร้อม `degraded`
- `filters` (object) — ค่าที่ผู้ใช้ติ๊ก `{"brand": ["Aurora"]}` — ค่าของแต่ละตัวกรองเป็นรายการเสมอ หลายค่าในตัวเดียวคือ OR หลายตัวคือ AND · ชื่อที่ไม่ใช่ตัวกรองได้ 400 พร้อมรายชื่อที่มี · ตัวกรองวันที่เลือกด้วย `key` ของช่องตามที่ได้มา เช่น `{"released": ["2026-03-02T00:00:00Z"]}` ได้ทั้งช่องตั้งแต่ต้นจนก่อนช่องถัดไป (สัปดาห์เริ่มวันจันทร์ เวลาเป็น UTC) · ค่าที่ไม่ใช่จุดเริ่มของช่องได้ 400 ที่บอกจุดเริ่มของช่องที่มีเวลานั้น
- `size` (number) — จำนวนผลต่อหน้า 0 ถึง 200 · ค่าเริ่มต้น 10 · เจ้าของชุดข้อมูลตั้งเพดานต่ำกว่านี้ได้
- `from` (number) — ข้ามไปกี่รายการ สำหรับเลขหน้า · `from + size` ไปได้ไกลสุดตำแหน่งที่ 10,000 เมื่อค้นด้วยคำ และ 1,000 เมื่อค้นด้วยความหมาย · ลึกกว่านั้น หรือให้แต่ละหน้าถูกกว่า ใช้เคอร์เซอร์
- `search_after` (array) — ค่า `next` ของหน้าก่อน หรือค่าใน `pages` ของหน้าที่ต้องการ ส่งกลับมาตามที่ได้ · ใช้คู่กับ `from` ไม่ได้
- `pages` (number) — เลขหน้าสุดท้ายที่แถบเลขหน้าจะชี้ไป · คำตอบมี `pages` เป็นเคอร์เซอร์ของหน้า 2 ถึงหน้านั้น คีย์คือเลขหน้า ค่าคือ `search_after` ที่เริ่มหน้านั้น · ไปได้ไกลสุดหน้าที่ตำแหน่งแรกไม่เกิน 10,000 (250 หน้า ที่ 40 ต่อหน้า) ไกลกว่านั้นได้ `degraded` `pages_capped` · ค้นด้วยความหมายไม่มีเคอร์เซอร์ ได้ `degraded` `no_page_cursors`
- `sort` (string | array) — `"price"`, `"-price"`, `"price:desc"`, `{"price":"desc"}` หรือรายการของสิ่งเหล่านี้ · เรียงได้ด้วย `_score` (มากไปน้อยเป็นค่าเริ่มต้น) และฟิลด์ตัวเลข วันที่ true/false ที่โครงบอกว่า `sort: true` · **การค้นด้วยความหมายเรียงตามความใกล้อย่างเดียว** จึงรับ `sort` ได้แค่ `{"_score":"desc"}` · `mode` `vector` หรือ `hybrid` หรือ `knn` ที่ส่งมาเอง คู่กับ `sort` อื่นได้ 400 ที่บอกทางออก ก่อนเรียกโมเดลและไม่นับโควตา · `auto` ที่มี `sort` อื่นตอบด้วยคำเสมอ (`answered.reason` เป็น `sort_asked`)
- `_source` (boolean | array) — `["product_name","price"]` เลือกฟิลด์ของระเบียนที่จะส่งกลับ · `false` ได้แค่ id และคะแนน · ไม่ใส่คือทั้งระเบียน
- `aggs` (object) — นับเองแบบ `terms`, `range`, `stats`, `histogram`, `cardinality`, `filter`, `filters` (ซ้อนกันได้) · `terms` บนฟิลด์ข้อความที่เป็นตัวกรองใช้ได้
- `post_filter` (object) — กรองผลโดยไม่กระทบตัวเลขที่นับ — สิ่งที่ `filters` ทำให้อยู่แล้ว
- `highlight` (object) — ทำไฮไลต์คำที่ตรง `{"fields":{"product_name":{}}}` · มาในคีย์ `highlight` ของแต่ละผล
- `track_total_hits` (boolean) — นับ `total` ให้ตรงทุกหน้า · ค่าเริ่มต้นคือเปิด
- `rerank` ("candidates" | "inline") — จัดลำดับใหม่ด้วยโมเดล — `candidates` ส่งข้อความของผลกลับไปให้คุณจัดเอง · `inline` ให้ระบบจัดให้ (ตามแพ็กเกจ)
- `explain` (boolean) — อธิบายว่าแต่ละผลได้คะแนนเท่าไหร่เพราะอะไร · **ใช้ได้กับ service key เท่านั้น**

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/search" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "เซรั่ม",
  "filters": {
    "brand": [
      "Aurora"
    ]
  },
  "size": 20
}'
```

**คำตอบ**

```json
{
  "total": 1,
  "total_is_exact": true,
  "took_us": 412,
  "hits": [
    {
      "id": "sku-1042",
      "score": 3.18,
      "matched": "words",
      "words": "typed",
      "sort": [
        3.18,
        "sku-1042"
      ],
      "document": {
        "product_name": "เซรั่มวิตามินซี ลดริ้วรอย",
        "brand": "Aurora",
        "price": 890,
        "in_stock": true,
        "raw": {
          "supplier": "S-12",
          "rank": 4
        }
      }
    }
  ],
  "counted_over": 1,
  "counted_from": "matches",
  "aggregations": {
    "brand": {
      "buckets": [
        {
          "key": "Aurora",
          "count": 1
        }
      ],
      "other": 0,
      "missing": 0,
      "other_values": 0
    },
    "in_stock": {
      "buckets": [
        {
          "key": "true",
          "count": 1
        }
      ],
      "other": 0,
      "missing": 0,
      "other_values": 0
    }
  },
  "filters": [
    {
      "field": "brand",
      "kind": "terms"
    },
    {
      "field": "in_stock",
      "kind": "terms"
    }
  ],
  "answered": {
    "by": "words",
    "reason": "no_mode",
    "message": "no \"mode\" was sent, so the words answered; send mode \"auto\" to let each query choose"
  }
}
```

คีย์ที่มีบางครั้ง: `next` `pages` `reached` `broadened` `degraded` `rerank` `plan` `aggregations` `counted_over` `counted_from`

**หมายเหตุ**

- **สตริงคือคำที่คนพิมพ์** ส่งข้อความจากกล่องค้นหาตรง ๆ ได้เลย ไม่ต้องกรองอักขระ `iphone 15:9` `ครีม 50ml)` `AND` ได้ 200 ทั้งหมด หลายคำคือทุกคำต้องเจอ ถ้าต้องการไวยากรณ์ (`field:คำ`, `OR`, `"วลี"`, `-ไม่เอา`) ให้ขอชัด ๆ ด้วย `{"query": {"query_string": {"query": "…"}}}`
- **ภาษาไทยไม่ต้องเว้นวรรค** `บิกินี่ลายดอก` เจอชื่อที่มีข้อความนี้ติดกันก่อน แล้วค่อยเป็นชื่อที่เขียนแยกด้วยช่องว่าง · คำที่พิมพ์ยังไม่จบอย่าง `กระถา` เจอ `กระถาง` · `ำ` กับ `ํ + า` และ `เเ` กับ `แ` ถือเป็นตัวเดียวกัน
- **broaden** ทำงานเฉพาะกับคำค้นที่เป็นสตริง และทำสองอย่าง · **ทุกครั้ง:** คำที่พิมพ์เจอคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำนั้นในชุดข้อมูลนี้ด้วย — `รองเท้า` เจอ `รองเท้าแตะ` และ `รองเท้าผ้าใบ` โดยผลที่มีคำที่พิมพ์ตรง ๆ ขึ้นก่อน · บอกไว้ในคีย์ `reached` ของคำตอบ (`word`, `compounds` และ `left_out` เมื่อเกิน 32 คำต่อคำที่พิมพ์) · **ทุกผลบอกว่าคำเจอมันอย่างไร** ในคีย์ `words` ของผลนั้น: `typed` คำที่พิมพ์เจอตรง ๆ · `compound` เจอเพราะคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำที่พิมพ์เท่านั้น · `widened` คำที่พิมพ์ไม่เจออะไรเลย ผลนี้มาจากคำถามที่กว้างกว่า · ไม่มี `words` เมื่อความหมายอย่างเดียวเจอผลนั้น (`matched: "meaning"`) · คำไทยที่สั้นกว่า 4 ตัวอักษรขยายเฉพาะเมื่อชุดข้อมูลเขียนคำนั้นแยกไว้ (`ผ้า` เจอ `ผ้าห่ม` แต่ `กก` ไม่เจอ `กกธูป`) · **เมื่อไม่เจออะไรเลย:** ลองให้เจอเกือบทุกคำก่อน แล้วค่อยคำใดคำหนึ่ง แล้วค่อยคำขึ้นต้น และบอกว่าทำอะไรไปในคีย์ `broadened` (`required` คือ `most` หรือ `any`) · เงื่อนไขใน DSL อย่าง `term` ไม่ถูกขยายเด็ดขาด · ผลที่ broaden แล้วไล่หน้าต่อด้วย `next` ได้ และ `aggregations` นับจากคำถามเดียวกับผล
- **ไม่เจอ หรือเจอแล้วได้เพิ่ม:** มีคีย์ `broadened` แปลว่าคำที่พิมพ์ไม่เจออะไรเลย ผลที่เห็นตอบคำถามที่กว้างกว่า ขึ้นข้อความอย่าง “ไม่พบผลที่ตรงกับคำค้น แสดงผลที่ใกล้เคียง” ได้ · มีแค่ `reached` แปลว่าคำที่พิมพ์เจอแล้ว และได้คำที่ยาวกว่ามาเพิ่ม ผลที่ตรงยังอยู่ครบและขึ้นก่อน อย่าขึ้นข้อความว่าไม่พบ · ทั้งสองมาด้วยกันได้ เมื่อคำที่พิมพ์ไม่เจอแต่คำหนึ่งในนั้นเจอคำที่ยาวกว่า · ดูจากว่ามีคีย์ `broadened` หรือไม่ ไม่ใช่จากคีย์ข้างใน เพราะ `split` `prefixed` `required` มาไม่ครบทุกตัวก็ได้ (`Down` ได้แค่ `prefixed`)
- `next` มีเมื่อ**ยังมีผลต่อ**เท่านั้น — ไม่มีคีย์นี้แปลว่าหน้านี้คือหน้าสุดท้าย · ค่าตัวสุดท้ายของ `next` คือ id ของผลสุดท้ายในหน้า จึงไม่หมดอายุเพราะดัชนีถูกจัดใหม่ · เคอร์เซอร์ที่ใช้ไม่ได้ได้ 400 ไม่ใช่หน้าว่าง
- **แถบเลขหน้า**: หน้าแรกส่ง `pages` เท่าเลขหน้าสุดท้ายของแถบ แล้วเก็บ `pages` ที่ได้ไว้กับหน้าที่วาด · คลิกหน้า k ส่ง `search_after: pages[k]` · เคอร์เซอร์คือตำแหน่งในลำดับ ไม่ใช่เลขที่นับ — ระเบียนที่เพิ่มหรือลบก่อนหน้านั้นเลื่อนเลขหน้า ไม่เลื่อนเคอร์เซอร์ · ส่ง `size` เหมือนกันทุกหน้าของแถบเดียวกัน เพราะมันกำหนดว่าหน้าเริ่มตรงไหน
- ค้นด้วยคำ `total` คือจำนวนที่คำค้นเจอ นับตรงทุกหน้า (`total_is_exact: true`) และเท่าเดิมไม่ว่าจะไล่ด้วย `from` หรือ `search_after` · `vector` ได้ `total` เป็นจำนวนระเบียนที่มีเวกเตอร์และผ่านตัวกรอง ซึ่งคือทุกระเบียนที่จัดลำดับได้ นับตรงและเท่าเดิมทุกหน้าเช่นกัน จึงใช้นับเลขหน้าได้ตั้งแต่หน้าแรก · `hybrid` เป็นค่าขั้นต่ำ ได้ `total_is_exact: false` เมื่อฝั่งความหมายพาระเบียนที่ฝั่งคำไม่เจอมาด้วย และอาจเพิ่มเมื่อไล่ลึกขึ้น · `total` คือจำนวนหลังตัวกรองที่ผู้ใช้ติ๊ก ส่วน `counted_over` คือฐานที่ตัวเลขใน `aggregations` ถูกนับมา ติ๊กแบรนด์หนึ่งแล้วแบรนด์อื่นในแถบยังมีตัวเลขให้เลือก
- `counted_from` มาคู่กับ `counted_over` และบอกว่าฐานนั้นคืออะไร · `matches` ค้นด้วยคำ นับจากระเบียนที่คำค้นเจอ · `words` ค้นแบบ `hybrid` นับเฉพาะระเบียนที่ฝั่งคำเจอ ผลที่ตรงความหมายอย่างเดียวไม่อยู่ในตัวเลข และ `counted_over: 0` แปลว่าฝั่งคำไม่เจออะไร ทุกผลตรงความหมาย · `all` ค้นแบบ `vector` ไม่มีชุดระเบียนที่ตรงให้นับ จึงนับทุกระเบียนในชุดข้อมูล ไม่ใช่เฉพาะผลที่ได้ · การค้นด้วยความหมายที่ไม่ได้นับอะไร (ชุดข้อมูลไม่มีตัวกรองและไม่ได้ส่ง `aggs`) ไม่มีทั้งสองคีย์ · ก่อนขึ้นข้อความว่าตัวเลขนับจากอะไร ให้ดู `counted_from`
- `filters` มาทุกครั้ง: ตัวกรองที่ชุดข้อมูลนี้มี (ว่างเมื่อไม่มี) ตัวเลขของแต่ละค่าอยู่ใน `aggregations` ภายใต้ชื่อฟิลด์เดียวกัน
- ตัวกรองวันที่ใน `aggregations` มี**เฉพาะช่องที่มีสินค้า** เรียงจากเก่าไปใหม่ แต่ละช่องมี `key` (จุดเริ่ม) `from` และ `to` (มิลลิวินาที) · มีได้ไม่เกิน 200 ช่อง ถ้าสินค้าเพิ่มจนเกินหลังบันทึกขั้นไว้ ได้ 200 ช่องล่าสุด สินค้าในช่องที่เก่ากว่านับรวมใน `other` ของตัวกรองนั้น และ `degraded` มี `facet_buckets_capped`
- `matched` มากับทุกผล — `words` ตรงคำ `meaning` ตรงความหมาย `both` ทั้งสอง เอาไปขึ้นป้ายบนหน้าร้านได้ · `sort` คือตำแหน่งของผลนั้นในลำดับ (คะแนนหรือค่าที่เรียง แล้วตามด้วย id) ส่งเป็น `search_after` เพื่อไล่ต่อจากผลใดก็ได้
- `degraded` มา**พร้อม**ผลเมื่อคำตอบเล็กกว่าที่ขอ ไม่ใช่แทนที่ผล · `reason` เป็นค่าคงที่ให้แตกสาขาได้ และถ้าเสียหลายอย่าง ตัวที่เหลืออยู่ใน `degraded.also` — รายการทั้งหมดอยู่ที่หน้า **ข้อผิดพลาดและเพดาน**
- `answered` มากับ**ทุกคำตอบ ทุก `mode`** เป็น `{ by, reason, message }` — `by` คือ `words` หรือ `meaning` และนับโควตาค้นด้วยความหมายเฉพาะครั้งที่ได้ `meaning` · `reason` เป็นค่าคงที่: `mode_asked` (`mode` ที่ส่งมาเลือกเอง — `keyword` ได้ `words` ส่วน `vector` และ `hybrid` ได้ `meaning`) `no_mode` (ไม่ได้ส่ง `mode` จึงตอบด้วยคำ) `vector_supplied` (ส่ง `knn` มาเอง) `meaning_withheld` (ขอความหมายแต่ครั้งนี้ตอบด้วยคำ — `degraded` บอกเหตุ) และที่ `auto` เลือก: `looks_like_a_code` (มีตัวเลข) `looks_like_a_name` (ไม่เกิน 3 คำและไม่มีคำบอกความต้องการ) `reads_like_a_need` `meaning_not_enabled` (ชุดข้อมูลยังไม่เปิดความหมาย ไม่มี `degraded`) `no_query_text` (ไม่มีข้อความที่พิมพ์) `sort_asked` (ส่ง `sort` ที่ไม่ใช่ `{"_score":"desc"}` ซึ่งการค้นด้วยความหมายทำไม่ได้ จึงตอบด้วยคำโดยไม่อ่านคำค้น) · **ชุดข้อมูลที่ยังไม่เปิดความหมายบอกได้สองแบบตาม `mode`**: `vector` และ `hybrid` ขอความหมายแล้วไม่ได้ จึงได้ `meaning_withheld` คู่กับ `degraded.reason` เป็น `not_enabled` ส่วน `auto` ไม่ได้ขอตั้งแต่แรก จึงได้ `meaning_not_enabled` และไม่มี `degraded` — หน้าที่จะบอกว่า "ยังไม่ได้เปิดความหมาย" ให้ดูทั้ง `answered.reason` และ `degraded.reason` · ถ้าได้ `looks_like_a_name` กับ `total` เป็น 0 และอยากลองด้วยความหมาย ส่งคำเดิมด้วย `mode: "hybrid"`

**ข้อผิดพลาด**

- `400` — เนื้อคำขอผิดรูป, DSL ผิด, ค่า `size`/`from` ไม่ใช่จำนวนเต็มตั้งแต่ 0, `filters` ที่ไม่ใช่รายการหรือไม่ใช่ตัวกรอง, เรียงด้วยฟิลด์ที่เรียงไม่ได้, `sort` อื่นนอกจาก `{"_score":"desc"}` คู่กับ `mode` `vector` หรือ `hybrid` หรือกับ `knn` ที่ส่งมาเอง (ก่อนเรียกโมเดล ไม่นับโควตา), เคอร์เซอร์ที่ใช้ไม่ได้
- `403` — `explain` ด้วย client key หรือ client key จากหน้าเว็บที่ไม่อยู่ในรายการ
- `429` — ยิงถี่เกินอัตราของแพ็กเกจ · ดู `Retry-After`

### `POST /v1/similar` — สินค้าใกล้เคียง

ระเบียนที่คล้ายระเบียนหนึ่ง — ด้วยความหมายเมื่อเปิดเวกเตอร์ ด้วยคำเด่นของมันเมื่อไม่ได้เปิด

- **คีย์:** client key หรือ service key

**เนื้อคำขอ**

- `id` (string | number, ต้องมี) — ระเบียนที่จะหาของคล้าย
- `size` (number) — 1 ถึง 50 · ค่าเริ่มต้น 10
- `filters` (object) — กรองแบบเดียวกับ `/v1/search`
- `_source` (boolean | array) — แบบเดียวกับ `/v1/search`
- `fields` (array) — ฟิลด์ข้อความที่ใช้วัดความคล้ายเมื่อใช้คำ · ค่าเริ่มต้นคือฟิลด์ที่น้ำหนักค้นหาสูงสุด (ชื่อสินค้า)

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/similar" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "sku-1042",
  "size": 5
}'
```

**คำตอบ**

```json
{
  "similar_to": "sku-1042",
  "by": "words",
  "hits": [
    {
      "id": "sku-1043",
      "score": 1.27,
      "matched": "words",
      "sort": [
        1.27,
        "sku-1043"
      ],
      "document": {
        "product_name": "ครีมกันแดดเนื้อบางเบา SPF50",
        "brand": "Aurora",
        "price": 450,
        "in_stock": false
      }
    }
  ]
}
```

คีย์ที่มีบางครั้ง: `degraded`

**หมายเหตุ**

- ตัวระเบียนเองไม่อยู่ในผล · ไม่มี `total` และ `next` เพราะของคล้ายเป็นแถบสินค้า ไม่ใช่ผลค้นหาให้ไล่หน้า
- `by` บอกว่าวัดด้วยอะไร — `meaning` ใช้เวกเตอร์ของระเบียนนั้นเอง `words` ใช้คำที่ทำให้ระเบียนนี้ต่างจากที่เหลือในชุดข้อมูล · ถ้าเปิดเวกเตอร์แล้วแต่ยังใช้ไม่ได้ (ยังสร้างไม่เสร็จ โควตาหมด) ได้ `words` พร้อม `degraded` บอกเหตุผล
- วัดกับแคตตาล็อก Shopee ของลูกค้าจริง 1,451 ชิ้น: ห้าอันดับแรกอยู่หมวดเดียวกับสินค้าต้นทางเฉลี่ย 4.3 ชิ้นด้วยคำ และ 4.5 ชิ้นด้วยความหมาย

**ข้อผิดพลาด**

- `400` — ไม่มี `id` หรือ `size` นอกช่วง
- `404` — ไม่มีระเบียน id นี้

### `GET /v1/suggest` — คำแนะนำระหว่างพิมพ์

เติมคำให้กล่องค้นหา ตั้งแต่ตัวอักษรแรก และสินค้าอันดับต้นในคำขอเดียวกัน

- **คีย์:** client key หรือ service key

**อ่านจาก URL**

- `q` (string, ต้องมี) — สิ่งที่พิมพ์ไปแล้ว · ว่างได้ (ได้รายการว่าง)
- `n` (number) — จำนวนคำแนะนำ 1 ถึง 50 · ค่าเริ่มต้น 10
- `from` (string) — **แหล่ง**ของคำแนะนำ ไม่ใช่เคอร์เซอร์ — `titles` (ข้อความจากระเบียนของคุณ ค่าเริ่มต้น) `queries` (คำที่คนค้นในชุดข้อมูลนี้) `dictionary` (พจนานุกรม) คั่นด้วยจุลภาคได้ ตามลำดับที่ต้องการ
- `field` (string) — ฟิลด์ข้อความที่ใช้เติมคำ · ค่าเริ่มต้นคือฟิลด์ข้อความที่น้ำหนักสูงสุดในโครง (มักเป็นชื่อสินค้า)
- `products` (number) — ขอสินค้าอันดับต้นที่ตรงกับสิ่งที่พิมพ์มาด้วย 0 ถึง 20 · ค่าเริ่มต้น 0 · นับเป็นการค้นหนึ่งครั้ง

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/suggest?q=เซรั่&n=5&products=3" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "suggestions": [
    {
      "text": "เซรั่มวิตามินซี",
      "from": "titles"
    }
  ],
  "sources": [
    "titles"
  ],
  "products": [
    {
      "id": "sku-1042",
      "score": 3.18,
      "matched": "words",
      "words": "typed",
      "sort": [
        3.18,
        "sku-1042"
      ],
      "document": {
        "product_name": "เซรั่มวิตามินซี ลดริ้วรอย",
        "brand": "Aurora",
        "price": 890,
        "in_stock": true,
        "raw": {
          "supplier": "S-12",
          "rank": 4
        }
      }
    }
  ]
}
```

คีย์ที่มีบางครั้ง: `products` `degraded`

**หมายเหตุ**

- คำแนะนำอ่านจากข้อความในระเบียนของคุณ ตั้งแต่ตรงที่พิมพ์ไปจนถึงช่องว่างถัดไป เรียงตามจำนวนระเบียนที่มี — `กระถา` ได้ `กระถางต้นไม้` ไม่ใช่ชื่อสินค้าทั้งชื่อ · พิมพ์จบคำแล้ว (`ระบบ`) ได้คำถัดไปมาด้วย (`ระบบ ค้นหา`) · อ่านจาก `n` ระเบียนที่ตรงที่สุด ระเบียนที่ให้คำเดียวกันจึงทำให้รายการสั้นกว่า `n` ได้
- `products` คือผลของ `/v1/search` สำหรับสิ่งที่พิมพ์อยู่ รูปเดียวกันทุกอย่าง — แถบสินค้าใต้คำแนะนำได้ในคำขอเดียว ไม่ต้องยิงสองเส้นแข่งกันทุกการกดแป้น
- ใช้ได้ตามแพ็กเกจโดยไม่ต้องขอเปิด · เมื่อโควตาหมดเส้นนี้ถูก **ปฏิเสธ** ด้วย 402 ไม่ใช่ลดทอน (degraded) เพราะรายการว่างหน้าตาเหมือนดรอปดาวน์ปกติ การบอกตรง ๆ ทำให้ฝั่งคุณหยุดยิงได้
- เป็น GET จึงแคชได้ และ preflight ของเบราว์เซอร์ถูกจำไว้สองชั่วโมง การกดแป้นหลังหยุดพิมพ์นาน ๆ จึงไม่ต้องรอ preflight ใหม่

**ข้อผิดพลาด**

- `400` — ไม่มี `q` · `n` หรือ `products` ไม่ใช่จำนวนเต็มในช่วง · `from` ไม่ใช่แหล่งที่มี · `field` ไม่ใช่ฟิลด์ข้อความ · มีพารามิเตอร์ที่เส้นนี้ไม่อ่าน
- `402` — แพ็กเกจไม่มีคำแนะนำ หรือโควตาของเดือนนี้หมด
- `429` — ยิงถี่เกินอัตราของแพ็กเกจ

### `POST /v1/filters` — ตัวกรองทั้งแถบ

ทุกตัวกรองที่ชุดข้อมูลนี้มี พร้อมทุกค่าและจำนวน ในคำขอเดียว

- **คีย์:** client key หรือ service key

**เนื้อคำขอ**

- `query` (string) — นับภายใต้คำค้นนี้ · ไม่ใส่คือนับทั้งชุดข้อมูล
- `filters` (object) — สิ่งที่ผู้ใช้ติ๊กไว้แล้ว รูปเดียวกับ `/v1/search`
- `size` (number) — ค่าต่อตัวกรองสูงสุดกี่ค่า 1 ถึง 10,000 · ค่าเริ่มต้นคือทุกค่า · ลำดับ `value` ตัดหลังเรียงตามพจนานุกรมไทย
- `order` ("value" | "count" | "key") — `value` ตามพจนานุกรมไทย (ค่าเริ่มต้น) · `count` มากไปน้อย · `key` ลำดับที่ไล่หน้าด้วย `after` ได้

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/filters" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "ครีม",
  "order": "count"
}'
```

**คำตอบ**

```json
{
  "counted_over": 1,
  "filters": [
    {
      "field": "brand",
      "kind": "terms",
      "order": "count",
      "values": [
        {
          "value": "Aurora",
          "count": 1
        }
      ],
      "other": 0,
      "other_values": 0,
      "missing": 0
    },
    {
      "field": "in_stock",
      "kind": "terms",
      "order": "count",
      "values": [
        {
          "value": "false",
          "count": 1
        }
      ],
      "other": 0,
      "other_values": 0,
      "missing": 0
    }
  ]
}
```

**หมายเหตุ**

- ใช้ตอนวาดแถบตัวกรองครั้งแรก หรือทำหน้ารวมยี่ห้อทั้งหมด · ผลค้นหาปกติพกตัวกรองมาใน `filters` + `aggregations` อยู่แล้ว (ยี่สิบค่าแรกของแต่ละตัว)
- ชุดข้อมูลที่ยังไม่มีตัวกรองตอบ `{"counted_over": 0, "filters": []}` · ประกาศตัวกรองด้วย `filter` ของ `PUT /v1/schema`
- `label` มาเมื่อเจ้าของตั้งชื่อที่แสดงไว้ · `other_values` คือจำนวนค่าที่ไม่ได้อยู่ในรายการ ถ้ามากกว่า 0 จะมี `note` บอกว่าไล่ต่อทีละหน้าที่ `/v1/filters/:field` · เส้นนี้ไม่มี `next` เพราะถามหลายฟิลด์พร้อมกัน จึงไม่มีลำดับเดียวให้ไล่
- `other` คือจำนวนระเบียนที่ถือค่าที่ไม่ได้อยู่ในรายการ นับหนึ่งครั้งต่อหนึ่งค่า ระเบียนที่มีสองยี่ห้อจึงนับสอง ใช้แทนจำนวนค่าไม่ได้ · `missing` คือจำนวนระเบียนที่ไม่มีค่าในตัวกรองนั้นเลย

**ข้อผิดพลาด**

- `400` — `query` ไม่ใช่สตริง · `filters` ผิดรูปหรือไม่ใช่ตัวกรอง · `size`/`order` นอกช่วง · มีคีย์ที่เส้นนี้ไม่รับ · ส่ง `after` (ใช้ได้กับ `/v1/filters/:field` เท่านั้น)

### `POST /v1/filters/:field` — ค่าทั้งหมดของตัวกรองหนึ่งตัว

ไล่ทุกค่าของตัวกรองแบบรายการทีละหน้า

- **คีย์:** client key หรือ service key

**เนื้อคำขอ**

- `query` (string) — นับภายใต้คำค้นนี้
- `filters` (object) — สิ่งที่ผู้ใช้ติ๊กไว้แล้ว
- `size` (number) — จำนวนค่าต่อหน้า 1 ถึง 10,000
- `after` (string) — ค่า `next` ของหน้าก่อน
- `order` ("value" | "count" | "key") — `value` ตามพจนานุกรมไทย · `count` มากไปน้อย · `key` ลำดับที่ไล่หน้าได้ (ค่าเริ่มต้นเมื่อส่ง `size` หรือ `after`)

**ตัวอย่าง**

```bash
curl -X POST "https://api.intent-search.dev/v1/filters/brand" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order": "key",
  "size": 50
}'
```

**คำตอบ**

```json
{
  "field": "brand",
  "kind": "terms",
  "order": "key",
  "counted_over": 3,
  "values": [
    {
      "value": "Aurora",
      "count": 2
    },
    {
      "value": "Terra",
      "count": 1
    }
  ],
  "other": 0,
  "other_values": 0,
  "missing": 0
}
```

คีย์ที่มีบางครั้ง: `label` `next` `note`

**หมายเหตุ**

- ใช้ได้กับตัวกรองแบบรายการ (`terms`) · ตัวกรองแบบช่วงตัวเลข ค่าของมันคือช่วงที่เจ้าของกำหนด ส่วนแบบวันที่คือช่วงเวลาทีละขั้นตาม `interval` ของตัวกรอง · ทั้งสองแบบผลค้นหานับมาให้อยู่แล้ว และ `POST /v1/filters` นับให้พร้อมตัวกรองอื่น
- `next` มีเฉพาะลำดับ `key` และเฉพาะเมื่อยังเหลือค่าหลังหน้านี้ · ไล่จนหน้าที่ไม่มี `next` แล้วหยุด หน้านั้นคือหน้าสุดท้าย ไม่ต้องขออีกหน้าเพื่อเจอหน้าว่าง
- `other_values` คือจำนวนค่าที่ยังเหลือหลังหน้านี้ · `other` คือจำนวนระเบียนที่ถือค่าเหล่านั้น นับหนึ่งครั้งต่อหนึ่งค่า ระเบียนที่มีสองยี่ห้อจึงนับสอง ใช้แทนจำนวนค่าไม่ได้ · ทั้งสองไม่นับค่าของหน้าก่อน ๆ และเป็น 0 ในหน้าสุดท้าย · `missing` คือจำนวนระเบียนที่ไม่มีค่าในตัวกรองนี้เลย
- `value` ใช้ลำดับพจนานุกรมไทย คำที่ขึ้นต้นด้วยสระหน้าอย่าง เ ไ จึงไม่ตกไปอยู่ท้ายรายการ · ส่ง `size` มากับ `value` ได้ค่าแรกตามพจนานุกรมไทยจริง เพราะตัดหลังเรียง ค่าที่ถูกตัดนับใน `other_values` และ `note` บอกวิธีไล่ต่อ

**ข้อผิดพลาด**

- `400` — ตัวกรองนี้เป็นแบบช่วงตัวเลขหรือวันที่ ไม่ใช่แบบรายการ · เรียง `count` แล้วส่ง `after`
- `404` — ฟิลด์นี้ไม่ใช่ตัวกรองของชุดข้อมูลนี้ — ข้อความบอกว่ามีอะไรบ้าง

## ตั้งค่า

### `GET /v1/schema` — โครงของชุดข้อมูล

ฟิลด์ไหนค้นได้ กรองได้ เรียงได้ ฟิลด์ไหนเก็บไว้เฉย ๆ และมีระเบียนค้างอยู่เท่าไหร่

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/schema" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "id_field": "id",
  "fields": [
    {
      "name": "product_name",
      "type": "text",
      "search": {
        "weight": 2
      },
      "filter": false,
      "sort": false
    },
    {
      "name": "brand",
      "type": "text",
      "search": {
        "weight": 1
      },
      "filter": {
        "kind": "terms"
      },
      "sort": false
    },
    {
      "name": "price",
      "type": "number",
      "search": false,
      "filter": false,
      "sort": true
    },
    {
      "name": "in_stock",
      "type": "boolean",
      "search": false,
      "filter": {
        "kind": "terms"
      },
      "sort": true
    }
  ],
  "stored_only": [
    "raw"
  ],
  "documents": {
    "stored": 3,
    "pending": 0
  }
}
```

คีย์ที่มีบางครั้ง: `generated`

**หมายเหตุ**

- `fields` เขียนเป็นความสามารถ ไม่ใช่ชนิดของเอนจิน: `search` (พร้อมน้ำหนัก) `filter` และ `sort` ของแต่ละฟิลด์ · `type` คือชนิดของค่า `text` `number` `date` `boolean`
- `stored_only` คือคอลัมน์ที่ระเบียนมีแต่ไม่ได้ลงดัชนี ยังเก็บครบและส่งกลับมาพร้อมผล · `generated` คือคอลัมน์ที่ระบบเขียนให้ เช่นหมวดจาก `PUT /v1/categories`

### `PUT /v1/schema` — เปลี่ยนโครง

บอกว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้ — ลองดูผลก่อนด้วย dry_run

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `fields` (array) — รายการฟิลด์**ทั้งหมด** ฟิลด์ที่ไม่อยู่ในรายการเลิกลงดัชนี (ยังเก็บและส่งกลับตามเดิม)
- `fields[].type` ("text" | "number" | "date" | "boolean", ต้องมี) — ชนิดของค่า
- `fields[].search` (boolean | object) — `true` หรือ `{"weight": 2}` ค้นด้วยคำได้ และคำในฟิลด์นี้มีน้ำหนักเท่าไหร่ · ข้อความเท่านั้น
- `fields[].filter` (boolean | object) — `true` เป็นตัวกรองแบบรายการ (ข้อความ true/false) หรือรายเดือน (วันที่) · ตัวเลขต้องบอกช่วง `{"kind":"range","ranges":[{"to":100},{"from":100}]}` · ใส่ `label` เพื่อตั้งชื่อที่แสดงได้ · วันที่เลือกขั้นได้ `{"kind":"date","interval":"week"}` — `minute` `hour` `day` `week` `month` `quarter` `year` · ขั้นที่ทั้งชุดข้อมูลมีช่องที่มีสินค้าเกิน 200 ช่องได้ 400 ที่บอกจำนวนช่องและขั้นที่ใกล้ที่สุดที่พอ และโครงไม่ถูกเปลี่ยน
- `fields[].sort` (boolean) — เรียงได้ · ตัวเลข วันที่ true/false เท่านั้น ข้อความไม่มีลำดับให้เรียง
- `id_field` (string) — คอลัมน์ที่เป็น id ของแต่ละระเบียน · เปลี่ยนได้เมื่อชุดข้อมูลยังไม่มีระเบียน
- `dry_run` (boolean) — ตอบว่าจะเปลี่ยนอะไรทีละฟิลด์ และต้องเขียนระเบียนทุกตัวใหม่หรือไม่ โดยยังไม่เปลี่ยนอะไร · อยู่ในเนื้อคำขอเท่านั้น `?dry_run=true` ใน URL ได้ `400` และไม่มีอะไรเปลี่ยน

**ตัวอย่าง**

```bash
curl -X PUT "https://api.intent-search.dev/v1/schema" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": [
    {
      "name": "product_name",
      "type": "text",
      "search": {
        "weight": 3
      }
    },
    {
      "name": "brand",
      "type": "text",
      "search": true,
      "filter": {
        "kind": "terms",
        "label": "ยี่ห้อ"
      }
    },
    {
      "name": "price",
      "type": "number",
      "sort": true,
      "filter": {
        "kind": "range",
        "ranges": [
          {
            "to": 500
          },
          {
            "from": 500
          }
        ]
      }
    },
    {
      "name": "in_stock",
      "type": "boolean",
      "filter": true,
      "sort": true
    }
  ],
  "dry_run": true
}'
```

**คำตอบ**

```json
{
  "dry_run": true,
  "changes": [
    {
      "field": "product_name",
      "from": {
        "name": "product_name",
        "type": "text",
        "search": {
          "weight": 2
        },
        "filter": false,
        "sort": false
      },
      "to": {
        "name": "product_name",
        "type": "text",
        "search": {
          "weight": 3
        },
        "filter": false,
        "sort": false
      }
    },
    {
      "field": "brand",
      "from": {
        "name": "brand",
        "type": "text",
        "search": {
          "weight": 1
        },
        "filter": {
          "kind": "terms"
        },
        "sort": false
      },
      "to": {
        "name": "brand",
        "type": "text",
        "search": {
          "weight": 1
        },
        "filter": {
          "kind": "terms",
          "label": "ยี่ห้อ"
        },
        "sort": false
      }
    },
    {
      "field": "price",
      "from": {
        "name": "price",
        "type": "number",
        "search": false,
        "filter": false,
        "sort": true
      },
      "to": {
        "name": "price",
        "type": "number",
        "search": false,
        "filter": {
          "kind": "range",
          "ranges": [
            {
              "to": 500
            },
            {
              "from": 500
            }
          ]
        },
        "sort": true
      }
    }
  ],
  "reindex": true,
  "documents": 3
}
```

คีย์ที่มีบางครั้ง: `id_field` `reindexed` `fields` `stored_only` `documents` `generated` `changes` `reindex` `dry_run`

**หมายเหตุ**

- ไม่ต้องส่งข้อมูลใหม่ — การเปลี่ยนที่กระทบดัชนีจะเขียนระเบียนทุกตัวลงสำเนาใหม่ ระหว่างนั้นการค้นยังตอบจากของเดิม แล้วสลับทีเดียวเมื่อเสร็จ ถ้าล้มเหลวของเดิมยังอยู่ครบและโครงไม่ถูกเปลี่ยน · การเปลี่ยนแค่ `label` ไม่ต้องเขียนใหม่
- ไม่ใส่ `dry_run` คือเปลี่ยนจริง คำตอบคือโครงใหม่แบบเดียวกับ `GET /v1/schema` พร้อม `reindexed` จำนวนระเบียนที่เขียนใหม่
- คอลัมน์หมวดที่ `PUT /v1/categories` สร้างถูกเก็บไว้เสมอ ไม่ต้องใส่ในรายการ

**ข้อผิดพลาด**

- `400` — เรียงด้วยข้อความ · ค้นด้วยคำในตัวเลข · ตัวกรองตัวเลขไม่มีช่วง · ชื่อฟิลด์ซ้ำ มีช่องว่าง หรือขึ้นต้นด้วย `_` / `ns_` · มีคีย์ที่ไม่รู้จัก · มีพารามิเตอร์ใน URL (ตัวเลือกทุกตัวอยู่ในเนื้อคำขอ)
- `409` — เปลี่ยน `id_field` ขณะที่ชุดข้อมูลมีระเบียนแล้ว · เปิดการค้นด้วยความหมายไว้แต่โครงใหม่ไม่มีฟิลด์ข้อความ
- `502` — เขียนสำเนาใหม่ไม่สำเร็จ — โครงเดิมยังใช้อยู่

### `GET /v1/synonyms` — คำพ้อง

กลุ่มคำที่ค้นคำไหนก็เจอทุกคำในกลุ่ม

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/synonyms" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "groups": [
    [
      "ไอโฟน",
      "iphone"
    ]
  ]
}
```

**หมายเหตุ**

- คำทับศัพท์ (`ไอโฟน` กับ `iphone`) ไม่เดาให้ เพราะเสียงคล้ายกันไม่ได้แปลว่าความหมายเดียวกันเสมอ — ใส่เป็นคำพ้องแล้วค้นได้เท่ากันทันที

### `PUT /v1/synonyms` — ตั้งคำพ้อง

แทนที่ทุกกลุ่มคำพ้องด้วยรายการนี้

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `groups` (array, ต้องมี) — รายการของกลุ่ม แต่ละกลุ่มมีอย่างน้อยสองคำที่ต่างกัน ไม่เกิน 5,000 กลุ่ม · รายการว่างคือลบทั้งหมด

**ตัวอย่าง**

```bash
curl -X PUT "https://api.intent-search.dev/v1/synonyms" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "groups": [
    [
      "ไอโฟน",
      "iphone"
    ],
    [
      "กันแดด",
      "sunscreen"
    ]
  ]
}'
```

**คำตอบ**

```json
{
  "groups": [
    [
      "ไอโฟน",
      "iphone"
    ],
    [
      "กันแดด",
      "sunscreen"
    ]
  ]
}
```

**หมายเหตุ**

- มีผลกับการค้นครั้งถัดไปทันที ไม่ต้องเขียนระเบียนใหม่ · ทั้งรายการในครั้งเดียว เพราะ backend มักเก็บคำศัพท์ไว้เป็นไฟล์

**ข้อผิดพลาด**

- `400` — กลุ่มที่มีคำไม่ถึงสองคำ

### `GET /v1/origins` — หน้าเว็บที่ใช้ client key ได้

รายชื่อ origin ที่ client key ของชุดข้อมูลนี้ใช้ค้นจากเบราว์เซอร์ได้

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/origins" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "origins": [
    "https://shop.example.com",
    "http://localhost:*"
  ]
}
```

**หมายเหตุ**

- client key ที่ถูกเรียกจากเบราว์เซอร์ (มี `Origin`) ต้องมาจากหน้าที่อยู่ในรายการนี้ ไม่อย่างนั้นได้ `403` · เรียกจากเซิร์ฟเวอร์ (ไม่มี `Origin`) ใช้ได้โดยไม่ต้องอยู่ในรายการ

### `PUT /v1/origins` — ตั้งหน้าเว็บที่ใช้ client key ได้

แทนที่รายชื่อ origin ทั้งหมดด้วยรายการนี้

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `origins` (array, ต้องมี) — origin คือ scheme + host + port ถ้ามี เช่น `https://shop.example.com` หรือ `http://localhost:3000` · `https://*.example.com` คือทุก subdomain · `http://localhost:*` คือทุกพอร์ตบนเครื่องนี้ สำหรับ dev server ระหว่างพัฒนา — `:*` ใช้ได้กับ `localhost` `127.0.0.1` และ `[::1]` เท่านั้น · ไม่เกิน 100 รายการ · รายการว่างคือไม่มีหน้าเว็บไหนใช้ client key ได้

**ตัวอย่าง**

```bash
curl -X PUT "https://api.intent-search.dev/v1/origins" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "origins": [
    "https://shop.example.com",
    "http://localhost:*"
  ]
}'
```

**คำตอบ**

```json
{
  "origins": [
    "https://shop.example.com",
    "http://localhost:*"
  ]
}
```

**หมายเหตุ**

- ทั้งรายการในครั้งเดียว ส่งรายการเดิมซ้ำได้โดยไม่มีอะไรเปลี่ยน · มีผลกับคำขอถัดไปทันที
- `http://localhost:3000` กับ `http://127.0.0.1:3000` เป็นคนละ origin และ `http://localhost:*` ก็ไม่ครอบ `127.0.0.1` ใส่ให้ตรงกับที่อยู่ในแถบที่อยู่ของเบราว์เซอร์
- ถ้ามีรายการไหนไม่ใช่ origin จะได้ `400` ที่บอกว่ารายการไหน และรายชื่อเดิมไม่เปลี่ยน

**ข้อผิดพลาด**

- `400` — รายการที่ไม่ใช่ origin รวมถึง `:*` หลังโฮสต์อื่นนอกจาก `localhost` `127.0.0.1` `[::1]` · เกิน 100 รายการ
- `403` — ใช้ client key

### `GET /v1/vectors` — สถานะการค้นด้วยความหมาย

เปิดไว้หรือยัง พร้อมใช้หรือยัง และสร้างไปถึงไหน

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/vectors" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "enabled": true,
  "ready": true,
  "model": "bge-m3@q8",
  "progress": null,
  "phase": "ready",
  "eta_seconds": null,
  "pending": 0,
  "stalled": null
}
```

**หมายเหตุ**

- ตัวอย่างคำตอบด้านบนคือชุดข้อมูลที่เปิดและสร้างเสร็จแล้ว ชุดที่ยังไม่เปิดได้ `enabled: false` `ready: false` และคีย์อื่นทุกตัวเป็น `null` — `pending` ด้วย ไม่ใช่ `0`
- `enabled` คือขอไว้แล้ว `ready` คือใช้ได้แล้ว — ช่องว่างระหว่างสองอย่างคือเวลาที่โมเดลกำลังอ่านระเบียน (`progress` บอกว่าไปถึงไหน) ระหว่างนั้นการค้นด้วยคำตอบตามปกติ
- `eta_seconds` คือเวลาที่เหลือโดยประมาณระหว่างสร้างครั้งแรก วัดจากความเร็วจริงของงานนี้ · เป็น `null` จนกว่าจะวัดได้
- `pending` คือระเบียนที่ส่งมาหลังพร้อมแล้วและกำลังรอเวกเตอร์ ระบบเติมให้เองในดัชนีที่ใช้อยู่ ปกติภายในไม่กี่วินาที ระหว่างนั้นระเบียนเหล่านี้ค้นด้วยคำเจอ แต่การค้นด้วยความหมายยังข้ามไป · เป็น `null` ระหว่างสร้างครั้งแรกหรือเมื่อปิดอยู่
- `stalled` เป็น `null` เมื่องานเดินปกติ ถ้างานหยุดเกินหนึ่งนาทีจะเป็น `{ reason, since, message }` — `reason` คือ `worker_offline` `model_unavailable` `model_mismatch` `engine_unavailable` หรือ `engine_refused` ทุกเหตุอยู่ฝั่งเรา ฝั่งคุณไม่ต้องทำอะไร ไม่มีอะไรหาย และการค้นยังตอบด้วยคำ
- **รอด้วยโปรแกรม:** เรียกเส้นนี้ทุก 5–10 วินาทีจน `ready` เป็น `true` (ใช้ `eta_seconds` ตั้งเวลารอได้) · ถ้าเจอ `stalled` ให้ห่างการเรียกเป็นทุกหนึ่งนาที งานเดินต่อเองเมื่อสาเหตุหาย

### `PUT /v1/vectors` — เปิดหรือปิดการค้นด้วยความหมาย

ให้โมเดลอ่านทุกระเบียนครั้งเดียว แล้ว `mode: "hybrid"` กับ `/v1/similar` ใช้ความหมายได้

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `enabled` (boolean, ต้องมี) — เปิดหรือปิด

**ตัวอย่าง**

```bash
curl -X PUT "https://api.intent-search.dev/v1/vectors" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'
```

**คำตอบ**

```json
{
  "enabled": true,
  "ready": false,
  "model": "bge-m3@q8",
  "progress": {
    "done": 0,
    "total": 3
  },
  "phase": "filling",
  "eta_seconds": null,
  "pending": null,
  "stalled": null
}
```

**หมายเหตุ**

- ไม่ต้องทำเวกเตอร์เอง — ระบบเลือกฟิลด์ข้อความที่ค้นได้ให้โมเดลอ่าน · คำตอบคือสถานะแบบเดียวกับ `GET /v1/vectors` ให้เรียกเส้นนั้นต่อจน `ready` เป็น `true`
- ระเบียนที่ส่งมาหลังจากนั้น รวมถึงหลังพร้อมแล้ว ได้เวกเตอร์เองโดยไม่ต้องสั่งอีก ระบบเติมในดัชนีที่ใช้อยู่โดยไม่สร้างใหม่ทั้งชุด · `pending` บอกว่ายังเหลือกี่ชิ้น
- ถ้าข้อความของสินค้าเปลี่ยนระหว่างที่โมเดลกำลังอ่าน เวกเตอร์ของข้อความเก่าจะถูกทิ้ง และอ่านใหม่จากข้อความล่าสุด
- ปิดแล้วเปิดใหม่คือให้โมเดลอ่านใหม่ทั้งชุด

**ข้อผิดพลาด**

- `402` — แพ็กเกจนี้ไม่มีการค้นด้วยความหมาย
- `409` — ชุดข้อมูลยังไม่มีระเบียน หรือไม่มีฟิลด์ข้อความให้อ่าน

### `GET /v1/categories` — หมวดที่จัดอัตโนมัติ

รายการหมวดของคุณ และจัดระเบียนเข้าหมวดไปแล้วเท่าไหร่

- **คีย์:** service key เท่านั้น

**ตัวอย่าง**

```bash
curl "https://api.intent-search.dev/v1/categories" \
  -H "Authorization: Bearer $NS_KEY"
```

**คำตอบ**

```json
{
  "field": "category",
  "categories": [
    {
      "name": "ความงาม"
    },
    {
      "name": "ต้นไม้และสวน"
    }
  ],
  "min_score": 0.6,
  "version": 1,
  "model": "bge-m3@q8",
  "progress": {
    "sorted": 3,
    "total": 3,
    "unfit": 0
  },
  "updated_at": "2026-09-25T09:31:00.000Z"
}
```

คีย์ที่มีบางครั้ง: `from` `field` `min_score` `version` `model` `progress` `updated_at`

**หมายเหตุ**

- ชุดข้อมูลที่ยังไม่ได้ตั้งหมวดตอบ `{"categories": []}`

### `PUT /v1/categories` — ตั้งหมวด

บอกชื่อหมวดของร้านคุณ แล้วระบบจัดทุกระเบียนเข้าหมวดด้วยโมเดล — ค้นและกรองด้วยหมวดได้

- **คีย์:** service key เท่านั้น

**เนื้อคำขอ**

- `categories` (array, ต้องมี) — หมวดทั้งหมด ไม่เกิน 200 · รายการว่างคือเลิกจัดหมวด
- `categories[].name` (string, ต้องมี) — ชื่อหมวด ตามที่ร้านใช้
- `categories[].description` (string) — อธิบายว่าอะไรอยู่ในหมวดนี้ — โมเดลอ่าน ไม่ได้แสดง
- `categories[].examples` (array) — ชื่อสินค้าตัวอย่างของหมวดนี้ ไม่เกิน 20 · ช่วยให้แม่นขึ้นมาก
- `field` (string) — ชื่อคอลัมน์ที่จะเขียนหมวดลงไป · ค่าเริ่มต้น `category` · ต้องไม่ซ้ำกับคอลัมน์ที่ระเบียนมีอยู่แล้ว
- `from` (array) — ฟิลด์ข้อความที่โมเดลอ่าน · ค่าเริ่มต้นคือฟิลด์ที่น้ำหนักค้นหาสูงสุด (ชื่อสินค้า)
- `min_score` (number) — สินค้าต้องใกล้หมวดที่ใกล้ที่สุดอย่างน้อยเท่านี้ (cosine 0–1) ถึงจะถูกจัดเข้า ไม่ถึงก็ไม่อยู่หมวดไหน · ค่าเริ่มต้น 0.6 · ส่งรายการเดิมพร้อมค่าใหม่ไม่ทำให้จัดหมวดใหม่ ส่งใหม่เฉพาะสินค้าที่ข้ามเส้น

**ตัวอย่าง**

```bash
curl -X PUT "https://api.intent-search.dev/v1/categories" \
  -H "Authorization: Bearer $NS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "categories": [
    {
      "name": "ความงาม",
      "description": "เครื่องสำอาง สกินแคร์ ครีม เซรั่ม"
    },
    {
      "name": "ต้นไม้และสวน",
      "examples": [
        "กระถางพลาสติก",
        "ดินปลูก"
      ]
    }
  ]
}'
```

**คำตอบ**

```json
{
  "field": "category",
  "categories": [
    {
      "name": "ความงาม",
      "description": "เครื่องสำอาง สกินแคร์ ครีม เซรั่ม"
    },
    {
      "name": "ต้นไม้และสวน",
      "examples": [
        "กระถางพลาสติก",
        "ดินปลูก"
      ]
    }
  ],
  "min_score": 0.6,
  "version": 1,
  "model": null,
  "progress": {
    "sorted": 0,
    "total": 3,
    "unfit": 0
  },
  "updated_at": "2026-09-25T09:30:00.000Z"
}
```

คีย์ที่มีบางครั้ง: `from`

**หมายเหตุ**

- โมเดลอ่านชื่อสินค้าทุกชิ้นแล้วเลือกหมวดที่ใกล้ที่สุด โดยเรียนจากสินค้าในร้านคุณเองว่าชื่อหมวดแต่ละชื่อหมายถึงอะไร · ทำเบื้องหลัง ดูความคืบหน้าที่ `GET /v1/categories` และหมวดที่จัดแล้วขึ้นดัชนีเองโดยไม่ต้อง sync
- หมวดอยู่ในคอลัมน์ `field` ของระเบียนในผลค้นหา ค้นด้วยคำได้ และเป็นตัวกรองได้ทันที (`filters: {"category": ["ความงาม"]}`) · เปลี่ยนรายการเมื่อไหร่ ทุกระเบียนถูกจัดใหม่ · การค้นด้วยความหมายใช้ได้ตลอด ไม่ต้องรอทำเวกเตอร์ใหม่ เพราะหมวดไม่ได้อยู่ในข้อความที่โมเดลอ่าน
- **ไม่บังคับให้ทุกชิ้นมีหมวด:** สินค้าที่ห่างทุกหมวดเกิน `min_score` ไม่มีคอลัมน์หมวด ตัวกรองหมวดนับไว้ใน `missing` และ `progress.unfit` บอกจำนวน · รายการหมวดที่ไม่ครอบคลุมทั้งร้านจึงไม่ยัดของที่ไม่เข้าพวกลงหมวดที่ใกล้ที่สุด · วัดกับสินค้าจริง: รายการครบ 16 หมวดยังจัดได้ 94% ส่วนรายการ 4 หมวดปล่อยสินค้าที่ไม่ใช่ทั้งสี่หมวดออกได้ราวหนึ่งในสาม
- วัดกับสินค้า Shopee ของลูกค้าจริง 1,451 ชิ้น 16 หมวดที่ลูกค้าตรวจแล้ว: ตรง 66.8% จากชื่อหมวดอย่างเดียว เทียบกับ 11.2% ของการค้นด้วยชื่อหมวดแล้วเอาผลมาเป็นหมวด · ใส่ `examples` หมวดละห้าชิ้นได้ราว 75%

**ข้อผิดพลาด**

- `402` — แพ็กเกจนี้ไม่มีการค้นด้วยความหมาย ซึ่งการจัดหมวดใช้
- `409` — ชื่อ `field` ซ้ำกับฟิลด์ในโครงหรือคอลัมน์ที่ระเบียนมีอยู่แล้ว

# ข้อผิดพลาดและเพดาน

## รหัสสถานะ

- `400` — คำขอผิด — เนื้อคำขอไม่ใช่ JSON, ขาดฟิลด์ที่ต้องมี, ค่าอยู่นอกช่วง (เช่น size ติดลบ), DSL ที่เอนจินปฏิเสธ, หัวข้อ X-End-User ที่ผิดรูป, พารามิเตอร์ใน URL ที่เส้นนั้นไม่อ่าน (ทุกเส้นของ /v1 ตรวจก่อนทำอะไร จึงไม่มีอะไรเปลี่ยน · ตัวเลือกอย่าง dry_run อยู่ในเนื้อคำขอ) · ลองซ้ำแล้วก็ได้คำตอบเดิม
- `401` — ไม่มีคีย์ หรือคีย์ใช้ไม่ได้ · มาพร้อม WWW-Authenticate และบอกว่าผิดแบบไหน (ไม่มี, ผิด scheme, ส่งสองตัว, ถูกเพิกถอน)
- `402` — ไม่ใช่ “ช้าลงหน่อย” แต่เป็น “แพ็กเกจนี้ทำไม่ได้” หรือ “โควตาเดือนนี้หมด” — ลองใหม่แล้วก็ได้คำตอบเดิม
- `403` — คีย์นี้ทำสิ่งนี้ไม่ได้ — client key ในเส้นที่ต้องใช้ service key, client key จากหน้าเว็บที่ไม่อยู่ในรายการ, explain ด้วย client key, X-End-User กับ client key, หรือคีย์ใดก็ตามที่เส้นของคอนโซลใต้ /api
- `404` — ไม่มีเส้นนี้ (รวมถึงเส้นที่มี / ท้าย), ไม่มีระเบียน id นี้, หรือ /v1/filters/:field ของฟิลด์ที่ไม่ใช่ตัวกรอง
- `405` — เส้นนี้มีอยู่ แต่ใช้ method อื่น · มาพร้อม Allow
- `409` — Idempotency-Key เดิมกำลังทำงานอยู่หรือเคยใช้กับคำขออื่น · เปลี่ยน id_field หลังมีข้อมูลแล้ว · ชื่อคอลัมน์หมวดชนกับคอลัมน์ที่มีอยู่
- `413` — เนื้อคำขอใหญ่เกินเพดานของเส้นนั้น (ส่งระเบียน 32 MB, ค้นหา 1 MB) — ข้อความบอกขนาด และมี CORS ให้เบราว์เซอร์อ่านได้
- `415` — เนื้อคำขอไม่ได้ส่งเป็น application/json
- `429` — ยิงถี่เกินอัตราของคีย์ หรือเกินส่วนแบ่งของผู้เข้าชมคนนั้น — ข้อความบอกว่าเกินของใคร (this plan, this visitor's share, this end user's share) · มี Retry-After มาด้วยเสมอ และเบราว์เซอร์อ่านได้
- `502` — เอนจินทำงานไม่สำเร็จ — sync หรือการเปลี่ยนโครงที่ล้ม ของเดิมยังอยู่ครบ ลองซ้ำได้
- `503` — เอนจินไม่ตอบ — ลองใหม่ได้

## อัตราต่อวินาที (ต่อคีย์)

- `Free` (20/s) — ต่อคีย์ · ผู้เข้าชมแต่ละคน 5/s
- `Starter` (50/s) — ต่อคีย์ · ผู้เข้าชมแต่ละคน 12.5/s
- `Growth` (200/s) — ต่อคีย์ · ผู้เข้าชมแต่ละคน 50/s
- `Scale` (1,000/s) — ต่อคีย์ · ผู้เข้าชมแต่ละคน 250/s

ผู้เข้าชมที่บอกได้ว่าเป็นใครได้ถังของตัวเองหนึ่งในสี่ของอัตราของคีย์ และยังนับในถังของคีย์ด้วย รวมกันจึงไม่เกินอัตราของคีย์:

- `client key + Origin` — เบราว์เซอร์ แยกตาม IP — แต่ละคนได้ถังหนึ่งในสี่ของอัตราของคีย์ (อย่างน้อย 2/s) ร้านไม่ต้องทำอะไร
- `service key + X-End-User` — หน้าที่เรนเดอร์บนเซิร์ฟเวอร์ ทุกคนมาจากเครื่องเดียว จึงส่งหัวข้อ X-End-User เป็น id ทึบของผู้เข้าชมหรือ IP ของเขา (ไม่ใช่อีเมล) — แต่ละค่าได้ถังหนึ่งในสี่เหมือนกัน · ตัวอักษร A–Z a–z 0–9 . _ : - ยาว 1–128 ไม่อย่างนั้นได้ 400 ที่บอกชื่อหัวข้อและกติกา
- `client key + X-End-User` — 403 — ใครอ่าน client key จากหน้าเว็บได้ก็ตั้งชื่อใหม่ได้ทุกคำขอ ส่วนแบ่งจะไม่จำกัดอะไรเลย · client key แยกผู้เข้าชมด้วย IP อยู่แล้ว
- `ไม่บอกว่าใคร` — คำขอจากเซิร์ฟเวอร์ที่ไม่มี X-End-User ใช้ถังของคีย์ทั้งถัง คนเดียวที่เปิดหลายแท็บจึงทำให้ทุกคนได้ 429 ได้

## โควตารายเดือน — อะไรนับอะไร

นับตามเดือนปฏิทิน (UTC) และเริ่มนับใหม่วันที่ 1 · เมื่อโควตาหมด การค้นยังตอบด้วยแบบที่ถูกกว่าพร้อม `degraded` ส่วนการเขียนได้ `402`

- `ค้นหา` (Free 10,000 · Starter 100,000 · Growth 1,000,000 · Scale 10,000,000) — ทุกครั้งที่เรียก POST /v1/search และ POST /v1/similar ไม่ว่าแบบไหน
- `ค้นด้วยความหมาย` (Free 1,000 · Starter 30,000 · Growth 400,000 · Scale 4,000,000) — POST /v1/search ที่ได้ answered.by เป็น meaning ไม่ว่า mode ไหน และ POST /v1/similar ที่ได้ by เป็น meaning — นับเพิ่มจากการค้นหา · ครั้งที่ตอบด้วยคำ (auto ที่อ่านเป็นชื่อหรือรหัส หรือถูกลดเป็นคำ) ไม่นับ
- `คำแนะนำ` (Free 100,000 · Starter 1,000,000 · Growth 10,000,000 · Scale 100,000,000) — ทุกครั้งที่เรียก GET /v1/suggest รวมที่ขอ products มาด้วย
- `จัดอันดับใหม่` (Free 0 · Starter 3,000 · Growth 50,000 · Scale 500,000) — POST /v1/search ที่ขอ rerank: "inline"
- `ระเบียนที่ส่งเข้าดัชนี` (Free 40,000 · Starter 400,000 · Growth 4,000,000 · Scale 40,000,000) — ระเบียนที่ POST /v1/sync ส่งจริง (sent) — ระเบียนที่ส่งซ้ำโดยไม่เปลี่ยนไม่นับ
- `สร้างเวกเตอร์ใหม่ทั้งชุด` (Free 1 · Starter 2 · Growth 6 · Scale 12) — เปิดการค้นด้วยความหมายอีกครั้งหลังปิด · ระเบียนที่ส่งมาหลังพร้อมแล้วไม่นับ
- `ไม่นับ` — POST /v1/filters, POST /v1/documents (นับตอน sync), GET ทุกเส้นที่อ่านการตั้งค่าหรือระเบียน และ PUT ทุกเส้นที่ตั้งค่า

## `degraded` — ตอบน้อยลง ไม่ใช่ล้มเหลว

การค้นที่ทำได้ไม่ครบตามที่ขอยังได้ผลเสมอ พร้อม `degraded` บอก `asked` `served` `reason` `message` และ `also` เมื่อถูกถอดมากกว่าหนึ่งอย่าง · แตกสาขาตาม `reason`:

- `quota_exhausted` — โควตาของเดือนนี้หมด — ได้ผลแบบที่ถูกกว่าแทน
- `not_on_plan` — แพ็กเกจนี้ไม่รวมความสามารถนั้น (vector, rerank)
- `not_enabled` — ยังไม่ได้เปิดการค้นด้วยความหมายของชุดข้อมูลนี้ (PUT /v1/vectors)
- `not_ready` — เปิดแล้ว แต่โมเดลยังอ่านระเบียนไม่เสร็จ
- `model_changed` — เวกเตอร์ของชุดข้อมูลทำด้วยโมเดลอื่น ต้องสร้างใหม่ก่อน
- `no_vector_supplied` — ขอความหมายแต่ไม่มีข้อความให้แปลง (query ไม่ใช่สตริง)
- `page_size_capped` — size เกินเพดานต่อหน้าของชุดข้อมูล และมีผลถูกตัดจริง · asked/served เป็นตัวเลข
- `window_capped` — from + size เกินตำแหน่งสุดท้ายของเส้นทางนั้น (10,000 เมื่อค้นด้วยคำ, 1,000 เมื่อค้นด้วยความหมาย) — ไล่ต่อด้วย search_after
- `pages_capped` — ขอ pages ไกลกว่าที่เคอร์เซอร์ไปถึง (หน้าที่ตำแหน่งแรกไม่เกิน 10,000) — served คือหน้าสุดท้ายที่มีเคอร์เซอร์ ไล่ต่อจากหน้านั้นด้วย next
- `no_page_cursors` — ค้นด้วยความหมายไม่มีเคอร์เซอร์ของหน้า — ใส่เลขหน้าด้วย from ภายใน 1,000
- `facet_buckets_capped` — ตัวกรองวันที่มีช่องที่มีสินค้าเกิน 200 ช่อง เพราะสินค้าเพิ่มหลังบันทึกขั้น — ได้ 200 ช่องล่าสุด สินค้าในช่องที่เก่ากว่านับรวมใน other ของตัวกรองนั้น · asked/served เป็นจำนวนช่อง
- `not_loaded` — ชุดข้อมูลยังไม่มีระเบียนที่ขึ้นดัชนี
- `unreachable · no_endpoint · bad_reply` — rerank แบบ inline ทำไม่สำเร็จ ผลยังเรียงตามคะแนนเดิม

## `warnings` — ตอบตามปกติ พร้อมเรื่องที่ควรแก้

คำเตือนไม่เปลี่ยนคำตอบ ทั้งสถานะและเนื้อเหมือนเดิม มีแค่ `warnings` เพิ่มในเนื้อ JSON เป็นรายการ `{"reason": "…", "message": "…"}` และหัวข้อ `NS-Warning: <reason>: <message>` ที่ JavaScript ในเบราว์เซอร์อ่านได้ · แตกสาขาตาม `reason`:

- `service_key_in_browser` — คำขอนี้ใช้ service key และมาจากหน้าเว็บ (มีหัวข้อ Origin) — ยังตอบตามปกติ แต่ service key แก้และลบชุดข้อมูลได้ และใครเปิดหน้านั้นก็อ่านคีย์ได้ · ในหน้าเว็บให้ใช้ client key ที่ค้นได้อย่างเดียว แล้วเพิ่มโดเมนของหน้าด้วย PUT /v1/origins · service key เก็บไว้ที่เซิร์ฟเวอร์
