Запись в справку

Создание и правка статей и категорий справки — чтобы содержимое можно было

синхронизировать из Notion, Google Docs или откуда угодно ещё, а не переносить руками.

Нужна область доступа kb:write.

Тело статьи — это Markdown

Не формат редактора. Заголовки, абзацы, списки и таблицы разбираются тем же кодом, который читает загруженные файлы, поэтому статья, созданная через API, ничем не отличается от написанной в редакторе: те же блоки, то же разбиение на части, тот же семантический поиск для ИИ-оператора.

curl -X POST https://api.tygy.ru/v1/kb/articles \
  -H "Authorization: Bearer $TYGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handbook_id": "hb_123",
    "title": "Возврат товара",
    "markdown": "# Возврат товара\n\nВернуть можно в течение 14 дней.\n\n- товар не был в употреблении\n- сохранена упаковка"
  }'

Заголовки важны. По ним содержимое режется на части для поиска: статья с заголовками отвечает точнее, а сплошная стена текста индексируется одним куском.

Черновик по умолчанию

Новая статья создаётся черновиком. Это сделано намеренно: синхронизация, которая пошла не так, не должна публиковать что-то клиентам.

Опубликовать — отдельное решение, параметром status:

{ "status": "published" }

Публикация — это ещё и момент, когда статья попадает в семантический поиск ИИ-оператора. До неё агент статью не увидит.

Правка

Все поля необязательные. Если передаёте markdown, нужен и title — в справке заголовок и тело лежат вместе, одной записью на язык.

curl -X PATCH https://api.tygy.ru/v1/kb/articles/art_456 \
  -H "Authorization: Bearer $TYGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Возврат товара", "markdown": "# Возврат\n\nОбновлённый текст." }'

Язык можно указать параметром locale; без него берётся язык самого справочника.

Категории

curl -X POST https://api.tygy.ru/v1/kb/categories \
  -H "Authorization: Bearer $TYGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handbook_id": "hb_123",
    "slug": "returns",
    "translations": [{ "locale": "ru", "title": "Возвраты" }]
  }'

Вложить категорию в другую — параметром parent_id.

Удаления нет

kb:write разрешает только создавать и править. Удалить статью или категорию через API нельзя, и права на это у ключа нет вовсе. Убрать опубликованное — это решение, которое принимает человек в кабинете; синхронизации оно не мешает, а от ошибки в скрипте защищает.

Если статья больше не нужна, поставьте ей status: "archived" — она исчезнет у клиентов и у ИИ-оператора, но останется у вас.

Справочники

Сами справочники-контейнеры через API не создаются: их заводят один раз руками в кабинете. Список доступных — GET /v1/kb/handbooks.