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 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

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

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

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.

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.

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: modes, situations and budget.
• REST API reference: every field of these endpoints.