# Knowledge API

The AI assistant answers only from your knowledge. Instead of letting it crawl your website, you can push your documents yourself: from your help center, CMS, product catalogue or internal docs, under your own ids. Your system stays the source of truth, every change reaches the assistant on your next push, and nothing depends on a crawler reading your pages.

- Each document has **your id** (`external_id`): send it again and it is updated in place.
- A document that has not changed is not re-indexed, so you can push everything on every deploy.
- A **collection** can be synced as a whole: documents you no longer send are deleted.
- Each document has a **language**. The assistant prefers documents in the customer's language, so a help center in Vietnamese and English answers each customer in theirs.

## Before you start

- An [API key](https://hatang.dev/docs/guides/getting-started/authentication.md) with the `chat:write` scope (and `chat:read` to list and search).
- The Customer Support module is on for the business.

## Documents

| Field | Type | Notes |
|---|---|---|
| `title` | string, 1–300 | Shown to agents and used in each chunk's breadcrumb. |
| `content` | string, up to 200,000 | Markdown or plain text. Headings (`#`, `##`…) split it into chunks of about 800 characters that keep their heading path. |
| `url` | URL or `null` | The page the document lives at. The assistant cites it. |
| `locale` | `vi`, `en`… or `null` | The document's language. `vi-VN` is stored as `vi`. |
| `tags` | up to 20 strings | Free labels you can filter by. |
| `collection` | string or `null` | A set you sync as a whole, such as `help` or `products`. |

The id in the path is 1–200 letters, digits or `. _ : -`, for example `help:vi:inbox:assign` or `sku-1042`.

Writes return at once with `status: "pending"`; chunking and embeddings run in the background and `status` becomes `indexed` (or `error` with a reason). Responses to writes carry `changed`: `false` means the document was already exactly this and nothing was re-indexed.

## Endpoints

| Endpoint | Purpose |
|---|---|
| `PUT /chat/knowledge/documents/{id}` | Create or update one document |
| `POST /chat/knowledge/documents/batch` | Create or update up to 100 documents: `{ "documents": [{ "external_id": "…", … }] }` |
| `POST /chat/knowledge/collections/{name}/sync` | Make the collection hold exactly these documents (up to 1,000): the listed ones are written, every other document of the collection is deleted |
| `GET /chat/knowledge/documents` | List documents in id order; filter with `collection`, `tag`, `locale`; page with `after` (the last id) and `limit` (up to 100) |
| `GET /chat/knowledge/documents/{id}` | Get a document |
| `DELETE /chat/knowledge/documents/{id}` | Delete a document |
| `GET /chat/knowledge/search?q=…&locale=vi` | Search the knowledge the assistant answers from, preferring a language |

Documents pushed here show in the dashboard under **Support → AI assistant → Knowledge**, one row per collection, and are read-only there.

## Push one document

**cURL**

```bash
curl -X PUT https://api.hatang.dev/chat/knowledge/documents/help:vi:shipping \
  -H "Authorization: Bearer ht_123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Phí giao hàng",
    "content": "# Phí giao hàng\n\n30.000đ toàn quốc, miễn phí cho đơn từ 500.000đ.",
    "url": "https://shop.vn/ho-tro/giao-hang",
    "locale": "vi",
    "tags": ["shipping"],
    "collection": "help"
  }'
```

**Node.js**

```js
import { Hatang } from "@hatang/sdk"; // hatang.knowledge needs @hatang/sdk 0.5.0+

const hatang = new Hatang(process.env.HATANG_API_KEY);
const { data, error } = await hatang.knowledge.upsert("help:vi:shipping", {
  title: "Phí giao hàng",
  content: "# Phí giao hàng\n\n30.000đ toàn quốc, miễn phí cho đơn từ 500.000đ.",
  url: "https://shop.vn/ho-tro/giao-hang",
  locale: "vi",
  tags: ["shipping"],
  collection: "help",
});
```

**Python**

```python
from hatang import Hatang

hatang = Hatang()  # reads HATANG_API_KEY
hatang.knowledge.upsert("help:vi:shipping", {
    "title": "Phí giao hàng",
    "content": "# Phí giao hàng\n\n30.000đ toàn quốc, miễn phí cho đơn từ 500.000đ.",
    "url": "https://shop.vn/ho-tro/giao-hang",
    "locale": "vi",
    "tags": ["shipping"],
    "collection": "help",
})
```

## Sync a whole collection on every deploy

The simplest way to keep the assistant current: after each deploy of your help center or CMS, send all its documents to one collection. New and edited documents are indexed, unchanged ones are skipped, and removed ones are deleted.

```js
import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY);
const articles = await loadHelpArticles(); // your own source: files, a CMS API, a database

const { data, error } = await hatang.knowledge.sync("help", articles.map((a) => ({
  external_id: `help:${a.locale}:${a.slug}`,
  title: a.title,
  content: a.markdown,
  url: a.url,
  locale: a.locale,
  tags: [a.category],
})));
// data: { written: 3, unchanged: 231, deleted: 1, … }
```

A sync takes up to 1,000 documents. For more, use one collection per section (`help-inbox`, `help-billing`…) or write with `batch` and delete with `DELETE`.

## Languages

Give each translation its own document and `locale`. The assistant uses the customer's language when it knows it (the website widget and the apps report it), otherwise it guesses from the question. A document in another language is ranked lower, not hidden: a much better match in English still reaches a Vietnamese customer, and the assistant answers in the customer's language.

## Search

`GET /chat/knowledge/search?q=…` returns the chunks the assistant would read for that question, with their heading, URL, language and score. Use it to check that a document is indexed and found.

```bash
curl -G https://api.hatang.dev/chat/knowledge/search \
  -H "Authorization: Bearer ht_123..." \
  --data-urlencode "q=phí giao hàng bao nhiêu" \
  --data-urlencode "locale=vi"
```

## Next steps

- [AI assistant](https://hatang.dev/docs/guides/support/ai-assistant.md): modes, situations and budget.
- [REST API reference](https://hatang.dev/docs/reference/api.md): every field of these endpoints.

Source: https://hatang.dev/docs/guides/support/knowledge-api