База знаний через API
Используйте авторизацию и идентификатор существующего бота.
1. Создать группу документов
POST /api/v1/knowledge-groups
URL
https://app.helpfy.ai/api/v1/knowledge-groups
Заголовки
| Заголовок | Значение |
|---|---|
Authorization | Basic <base64(email:api_key)> |
Accept | application/json |
Content-Type | application/json |
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
bot_unique_id | строка | Да | Идентификатор бота. |
name | строка | Да | Название группы. |
Пример запроса
curl --request POST "https://app.helpfy.ai/api/v1/knowledge-groups" \
--user "user@example.com:api_key" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"bot_unique_id": "11111111-1111-4111-8111-111111111111",
"name": "Доставка"
}
JSON
Ответы
Успешный запрос: HTTP 201.
Пример ответа — HTTP 201
Сокращённый пример; значения условные.
{
"unique_id": "22222222-2222-4222-8222-222222222222",
"name": "Доставка"
}
Сохраните unique_id группы и указывайте его в поле knowledge_group_unique_id при добавлении документов.
2. Добавить текстовый документ
POST /api/v1/knowledges
URL
https://app.helpfy.ai/api/v1/knowledges
Заголовки
| Заголовок | Значение |
|---|---|
Authorization | Basic <base64(email:api_key)> |
Accept | application/json |
Content-Type | application/json |
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
bot_unique_id | строка | Да | Идентификатор бота. |
knowledge_group_unique_id | строка | Да | Идентификатор группы. |
name | строка | Да | Название документа. |
type | строка | Да | TEXT — текстовый документ. |
content | строка | Да | Актуальные сведения для ответов. |
source | строка | Нет | Ссылка на исходную статью или примечание. |
is_private_source | логическое значение | Нет | Скрывать ссылку на источник. По умолчанию true. |
is_indexed | логическое значение | Нет | Использовать документ при поиске ответа. По умолчанию true. |
Пример запроса
curl --request POST "https://app.helpfy.ai/api/v1/knowledges" \
--user "user@example.com:api_key" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-binary @- <<JSON
{
"bot_unique_id": "11111111-1111-4111-8111-111111111111",
"knowledge_group_unique_id": "22222222-2222-4222-8222-222222222222",
"name": "Изменение адреса доставки",
"type": "TEXT",
"content": "Адрес можно изменить до передачи заказа в доставку.",
"source": "https://example.com/help/delivery",
"is_private_source": false,
"is_indexed": true
}
JSON
Ответы
Успешный запрос: HTTP 201.
Пример ответа — HTTP 201
Сокращённый пример; значения условные.
{
"message": "Knowledge successfully created",
"is_exists": false,
"data": {
"unique_id": "e07ab05f-f97d-44f4-b668-2339d642e373",
"name": "Изменение адреса доставки"
}
}
Приватность скрывает ссылку, но не запрещает использовать текст документа. Поле is_exists сообщает о существовании документа с таким же содержимым.
3. Посмотреть документы группы
GET /api/v1/knowledges
URL
https://app.helpfy.ai/api/v1/knowledges
Заголовки
| Заголовок | Значение |
|---|---|
Authorization | Basic <base64(email:api_key)> |
Accept | application/json |
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
bot_unique_id | строка | Нет | Фильтр по боту в строке запроса. |
knowledge_group_unique_id | строка | Нет | Фильтр по группе в строке запроса. |
Пример запроса
curl --request GET "https://app.helpfy.ai/api/v1/knowledges" \
--user "user@example.com:api_key" \
--header 'Accept: application/json' \
--get \
--data-urlencode "bot_unique_id=11111111-1111-4111-8111-111111111111" \
--data-urlencode "knowledge_group_unique_id=22222222-2222-4222-8222-222222222222"
Ответы
Успешный запрос: HTTP 200.
Пример ответа — HTTP 200
Сокращённый пример; значения условные.
{
"data": [
{
"unique_id": "e07ab05f-f97d-44f4-b668-2339d642e373",
"name": "Изменение адреса доставки",
"is_indexed": true
}
],
"meta": {
"skip": 0,
"take": 10,
"total": 1
}
}
Все фильтры и параметры просмотра списка — в методе получения документов.
4. Загрузить PDF
POST /api/v1/knowledges/upload
URL
https://app.helpfy.ai/api/v1/knowledges/upload
Заголовки
| Заголовок | Значение |
|---|---|
Authorization | Basic <base64(email:api_key)> |
Accept | application/json |
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
bot_unique_id | строка | Да | Идентификатор бота. |
knowledge_group_unique_id | строка | Да | Идентификатор группы. |
name | строка | Да | Название документа. |
type | строка | Да | FILE — загрузка файла. |
file | файл | Да | PDF-файл с вашего компьютера. |
Пример запроса
curl --request POST "https://app.helpfy.ai/api/v1/knowledges/upload" \
--user "user@example.com:api_key" \
--header 'Accept: application/json' \
--form "bot_unique_id=11111111-1111-4111-8111-111111111111" \
--form "knowledge_group_unique_id=22222222-2222-4222-8222-222222222222" \
--form "name=Условия доставки" \
--form "type=FILE" \
--form "file=@./delivery.pdf;type=application/pdf"
Ответы
Успешный запрос: HTTP 201.
Пример ответа — HTTP 201
Сокращённый пример; значения условные.
Тело ответа не описано. Успех определяется HTTP-статусом 201.
Файл должен существовать. curl сам формирует заголовок Content-Type для составного запроса. Схема тела ответа на загрузку PDF не описана в API; проверьте HTTP-статус и появление документа в списке.
Для фонового добавления текста используйте асинхронное создание документа, затем получите состояние обработки. После завершения индексации отправьте вопрос в режиме SUPPORT.