Перейти к основному содержимому
API docs by Redocly

Jay Knowledge Hub public API (1.0.0)

Download OpenAPI specification:Download

ProjectsPublic

Работа с проектами.

Список проектов

Возвращает список проектов в аккаунте. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
query Parameters
pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 20

Размер страницы.

name
string

Фильтр по названию. Поиск выполняется по подстроке без учета регистра.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "paging": {
    }
}

Создание проекта

Создает новый проект базы знаний. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Название проекта.

Responses

Request samples

Content type
application/json
{
  • "name": "Справочная служба"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "CREATED",
  • "resources": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "indexingPriority": 1,
  • "indexingRetryCount": 10
}

Информация о проекте

Возвращает основную информацию о проекте базы знаний. Для этой операции требуется API-ключ проекта. Чтобы получить настройки проекта, используйте метод GET /projects/{projectId}/settings.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "CREATED",
  • "resources": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "indexingPriority": 1,
  • "indexingRetryCount": 10
}

Обновление проекта

Изменяет название проекта базы знаний. Для этой операции требуется административный API-ключ. Чтобы изменить настройки проекта, используйте метод POST /projects/{projectId}/settings.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

Request Body schema: application/json
required
name
required
string

Название проекта.

Responses

Request samples

Content type
application/json
{
  • "name": "Справочная служба"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "CREATED",
  • "resources": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "indexingPriority": 1,
  • "indexingRetryCount": 10
}

Удаление проекта

Удаляет проект базы знаний. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Получение настроек проекта

Получение настроек проекта базы знаний. Для этой операции подойдет проектный или административный API-ключ.

Подробное описание настроек см. в документации.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

Responses

Response samples

Content type
application/json
{
  • "indexing": {
    },
  • "search": {
    },
  • "generation": {
    },
  • "notAppliedFields": [
    ]
}

Обновление настроек проекта

Обновление настроек проекта базы знаний. Для этой операции подойдет проектный или административный API-ключ.

В запросе необходимо передать все настройки проекта, в том числе прежние значения для тех настроек, которые менять не требуется. Рекомендуем предварительно получить настройки с помощью метода GET /projects/{projectId}/settings.

Подробное описание настроек см. в документации.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

Request Body schema: application/json
required
required
object (ProjectIndexingSettingsDTO)

Настройки индексации. Подробное описание см. в документации.

required
object (ProjectSearchSettingsDTO)

Настройки поиска чанков. Подробное описание см. в документации.

required
object (ProjectGenerationSettingsDTO)

Настройки генерации ответов. Подробное описание см. в документации.

Responses

Request samples

Content type
application/json
{
  • "indexing": {
    },
  • "search": {
    },
  • "generation": {
    }
}

Response samples

Content type
application/json
{
  • "indexing": {
    },
  • "search": {
    },
  • "generation": {
    },
  • "notAppliedFields": [
    ]
}

QueriesPublic

Одиночные запросы на поиск чанков и генерацию ответов. Дополнительно можно передать в запросе историю сообщений.

Поиск чанков (retrieving)

Получение чанков, релевантных запросу пользователя, — только по корпусу этой базы знаний: по проиндексированным фрагментам документов-источников. Ни страницы вики, ни внешние MCP-источники этой операцией не читаются.

Отдает разрозненные чанки с оценкой релевантности и ссылкой на документ, из которого они взяты, — без структуры и без ответа на вопрос. По ним нельзя понять, чего в базе знаний нет: пустая выдача значит «ничего не совпало», а не «такой темы в корпусе не существует».

Смежные операции, если нужно другое:

  • готовый текст ответа по тому же корпусу — POST /query;
  • что в базе знаний вообще есть — POST /wiki/toc и POST /wiki/page;
  • где искать ответ на конкретный вопрос — POST /context/route;
  • дословные фрагменты сразу из вики, документов и внешних источников — POST /context/build;
  • живое чтение подключенного внешнего источника — POST /context/source/call.
Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

Array of objects (HistoryRecord)

История диалога. Записи отображаются в обратном хронологическом порядке (от поздних к ранним).

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RetrievingSettings)

Настройки поиска чанков.

enableAgentTableProcessing
boolean
Default: false

Извлекать чанки из файлов CSV и XLSX с помощью LLM (может увеличить затраты).

object

Явное указание версии документа: ключ — идентификатор группы, объединяющей версии одного документа (documentGroupId), значение — метка версии (documentVersion). Получить их можно методом GET /sources или GET /sources/{sourceId}. Для перечисленных групп используется указанная версия, минуя автоматический подбор версии. Группы, не указанные здесь, разрешаются автоматически.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "accessSettings": {
    },
  • "settings": {
    },
  • "enableAgentTableProcessing": false,
  • "versionOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "chunks": [
    ],
  • "graphContext": "string",
  • "graphEnrichment": { }
}

Генерация ответа

Синхронный запрос на генерацию ответа на пользовательский запрос. Ответ пишет модель по фрагментам документов-источников этой базы знаний и больше ни по чему: ни страницы вики, ни внешние MCP-источники в генерацию не попадают. Возвращается текст модели и ссылки на документы, из которых он собран, — сам материал не возвращается.

Это вызов модели: он стоит токенов и времени. Если нужно найти, а не получить готовый текст, — это POST /retrieve по тому же корпусу.

Учитывайте, что обработка запроса может занимать значительное время. Убедитесь, что используемый вами HTTP-клиент имеет установленный таймаут соединения более 1 минуты.

Смежные операции: карта базы знаний — POST /wiki/toc; маршрут по вопросу — POST /context/route; пакет дословных фрагментов сразу из трех слоев — POST /context/build.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

Array of objects (HistoryRecord)

История диалога. Записи отображаются в обратном хронологическом порядке (от поздних к ранним).

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RagSettings)

Настройки обработки запроса.

object

Явное указание версии документа: ключ — идентификатор группы, объединяющей версии одного документа (documentGroupId), значение — метка версии (documentVersion). Получить их можно методом GET /sources или GET /sources/{sourceId}. Для перечисленных групп используется указанная версия, минуя автоматический подбор версии. Группы, не указанные здесь, разрешаются автоматически.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "accessSettings": {
    },
  • "settings": {
    },
  • "versionOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

Генерация ответа (асинхронный запрос)

Асинхронный запрос на генерацию ответа на пользовательский запрос.

Получить результат можно методом GET /query/{queryId}, где queryId — идентификатор запроса, полученный в текущем ответе.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

Array of objects (HistoryRecord)

История диалога. Записи отображаются в обратном хронологическом порядке (от поздних к ранним).

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RagSettings)

Настройки обработки запроса.

object

Явное указание версии документа: ключ — идентификатор группы, объединяющей версии одного документа (documentGroupId), значение — метка версии (documentVersion). Получить их можно методом GET /sources или GET /sources/{sourceId}. Для перечисленных групп используется указанная версия, минуя автоматический подбор версии. Группы, не указанные здесь, разрешаются автоматически.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "accessSettings": {
    },
  • "settings": {
    },
  • "versionOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

Генерация ответа (стриминг)

Запрос на генерацию ответа на пользовательский запрос с потоковой передачей результата через Server-Sent Events (SSE).

Ответ возвращается в формате SSE с типами событий:

  • start: начало обработки;
  • chunk: фрагмент текста от LLM;
  • done: завершение с полным ответом и метаданными;
  • error: информация об ошибке.

Убедитесь, что используемый вами HTTP-клиент поддерживает SSE и имеет установленный таймаут соединения более 1 минуты.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

Array of objects (HistoryRecord)

История диалога. Записи отображаются в обратном хронологическом порядке (от поздних к ранним).

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RagSettings)

Настройки обработки запроса.

object

Явное указание версии документа: ключ — идентификатор группы, объединяющей версии одного документа (documentGroupId), значение — метка версии (documentVersion). Получить их можно методом GET /sources или GET /sources/{sourceId}. Для перечисленных групп используется указанная версия, минуя автоматический подбор версии. Группы, не указанные здесь, разрешаются автоматически.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "accessSettings": {
    },
  • "settings": {
    },
  • "versionOverrides": {
    }
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Статус обработки запроса на генерацию ответа

Возвращает текущий статус обработки запроса на генерацию ответа. Использует long-polling, если указан параметр waitTimeSeconds.

Authorizations:
bearerAuth
path Parameters
queryId
required
integer <int64> (LongId)

Идентификатор запроса на генерацию ответа.

query Parameters
waitTimeSeconds
integer <int32> [ 0 .. 30 ]
Default: 3

Время ожидания ответа в HTTP-запросе. Используется в long-polling.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

Отмена обработки запроса на генерацию ответа

Authorizations:
bearerAuth
path Parameters
queryId
required
integer <int64> (LongId)

Идентификатор запроса на генерацию ответа.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

ChatsPublic

Запросы на поиск чанков и генерацию ответов в рамках пользовательского чата.

Создание чата

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Название пользовательского чата.

object (RagSettings)

Настройки обработки запроса.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "settings": {
    }
}

Информация о пользовательском чате

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Идентификатор чата.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "settings": {
    }
}

Поиск чанков (retrieving)

Получение чанков, релевантных запросу пользователя, в рамках чата.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Идентификатор чата.

Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RetrievingSettings)

Настройки поиска чанков.

enableAgentTableProcessing
boolean
Default: false

Извлекать чанки из файлов CSV и XLSX с помощью LLM (может увеличить затраты).

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "accessSettings": {
    },
  • "settings": {
    },
  • "enableAgentTableProcessing": false
}

Response samples

Content type
application/json
{
  • "chunks": [
    ],
  • "graphContext": "string",
  • "graphEnrichment": { }
}

Генерация ответа

Синхронный запрос на генерацию ответа на пользовательский запрос. При этом учитывается история сообщений в чате.

Учитывайте, что обработка запроса может занимать значительное время. Убедитесь, что используемый вами HTTP-клиент имеет установленный таймаут соединения более 1 минуты.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Идентификатор чата.

Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RagSettings)

Настройки обработки запроса.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "accessSettings": {
    },
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

Генерация ответа (асинхронный запрос)

Асинхронный запрос на генерацию ответа на пользовательский запрос. При этом учитывается история сообщений в чате.

Получить результат можно методом GET /chat/{chatId}/query/{queryId}, где queryId — идентификатор запроса, полученный в текущем ответе.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Идентификатор чата.

Request Body schema: application/json
required
query
required
string non-empty

Текст пользовательского запроса.

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

object (RagSettings)

Настройки обработки запроса.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "accessSettings": {
    },
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

Статус обработки запроса на генерацию ответа

Возвращает текущий статус обработки запроса на генерацию ответа в пользовательском чате. Использует long-polling, если указан параметр waitTimeSeconds.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Идентификатор чата.

queryId
required
integer <int64> (LongId)

Идентификатор запроса на генерацию ответа.

query Parameters
waitTimeSeconds
integer <int32> [ 0 .. 30 ]
Default: 3

Время ожидания ответа в HTTP-запросе. Используется в long-polling.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

Отмена обработки чат-запроса

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Идентификатор чата.

queryId
required
integer <int64> (LongId)

Идентификатор запроса на генерацию ответа.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ],
  • "graphEnrichment": { }
}

SourcesPublic

Работа с источниками базы знаний.

Список источников

Возвращает информацию об источниках базы знаний. Поддерживает постраничный вывод. Максимальный размер страницы (pageSize) — 10 000. При вызове без параметров пагинации поведение аналогично предыдущей версии API (возврат до 10 000 записей).

Authorizations:
bearerAuth
query Parameters
createDateFrom
string <date>

Отбирать источники, добавленные начиная с указанной даты включительно.

createDateTo
string <date>

Отбирать источники, добавленные до указанной даты включительно.

sourceStatus
string

Отбирать источники с указанным статусом индексации. Возможные статусы:

  • READY_TO_INGEST — готов для индексации.
  • PROCESSING — в обработке.
  • INGESTED — проиндексирован.
  • FAILED_TO_INGEST — ошибка индексации.
pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 10000

Размер страницы. Значение по умолчанию и максимально допустимое — 10 000.

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ],
  • "paging": {
    }
}

Добавление из текста

Добавляет переданный текст в качестве источника в базу знаний. После добавления источника автоматически запускается его индексация.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Название источника. Должно содержать расширение файла (например, txt, md, json) и быть уникальным в рамках проекта. Если не указано, формируется автоматически.

text
required
string

Текст источника. Максимальный размер указан в требованиях к файлам.

segment
string
Deprecated

Сегмент (тег) базы знаний. Параметр устарел. Используйте segments.

segments
Array of strings

Сегменты (теги) базы знаний. Источник будет доступен при поиске по этим сегментам.

Длина названия сегмента — от 1 до 100 символов. В названиях не допускаются запятые.

accessControlAttributes
Array of strings

Группы доступа, которым разрешен доступ к источнику. Если группы с указанным названием нет, она создается.

Если группы доступа не назначены, источник доступен всем пользователям.

Responses

Request samples

Content type
application/json
{
  • "name": "filename.txt",
  • "text": "string",
  • "segment": "string",
  • "segments": [
    ],
  • "accessControlAttributes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "type": "FILE",
  • "accessControlAttributes": [
    ],
  • "hash": "sha256:abcd1234ef5678…",
  • "documentGroupId": "doc-42",
  • "documentVersion": "v3",
  • "isDefaultVersion": true,
  • "versionDescription": "Изменены пункты 4.1 и 4.2"
}

Обновление из текста

Заменяет источник с указанным названием на переданный текст. После обновления источника автоматически запускается его индексация.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Название источника. Если в базе знаний нет источника с таким названием, возвращается ошибка.

text
required
string

Текст источника. Максимальный размер указан в требованиях к файлам.

segment
string
Deprecated

Сегмент (тег) базы знаний. Параметр устарел. Используйте segments.

segments
Array of strings

Сегменты (теги) базы знаний. Источник будет доступен при поиске по этим сегментам.

Длина названия сегмента — от 1 до 100 символов. В названиях не допускаются запятые.

accessControlAttributes
Array of strings

Группы доступа, которым разрешен доступ к источнику. Если группы с указанным названием нет, она создается.

Если значение не передано, группы доступа у источника не меняются (поведение обратно совместимо).

Чтобы очистить группы доступа у источника, передайте пустой массив.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "text": "string",
  • "segment": "string",
  • "segments": [
    ],
  • "accessControlAttributes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "type": "FILE",
  • "accessControlAttributes": [
    ],
  • "hash": "sha256:abcd1234ef5678…",
  • "documentGroupId": "doc-42",
  • "documentVersion": "v3",
  • "isDefaultVersion": true,
  • "versionDescription": "Изменены пункты 4.1 и 4.2"
}

Добавление из файла

Добавляет переданный файл в качестве источника в базу знаний. После добавления источника автоматически запускается его индексация.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Загружаемый файл. См. требования к файлам.

name
string

Название источника. Должно содержать расширение файла и быть уникальным в рамках проекта. Если не указано, формируется автоматически.

segment
string
Deprecated

Сегмент (тег) базы знаний. Параметр устарел. Используйте segments.

segments
Array of strings

Сегменты (теги) базы знаний. Источник будет доступен при поиске по этим сегментам.

Длина названия сегмента — от 1 до 100 символов. В названиях не допускаются запятые.

accessControlAttributes
Array of strings

Группы доступа, которым разрешен доступ к источнику. Если группы с указанным названием нет, она создается.

Если группы доступа не назначены, источник доступен всем пользователям.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "type": "FILE",
  • "accessControlAttributes": [
    ],
  • "hash": "sha256:abcd1234ef5678…",
  • "documentGroupId": "doc-42",
  • "documentVersion": "v3",
  • "isDefaultVersion": true,
  • "versionDescription": "Изменены пункты 4.1 и 4.2"
}

Обновление из файла

Заменяет источник с указанным названием на переданный файл. После обновления источника автоматически запускается его индексация.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Загружаемый файл. См. требования к файлам.

name
string

Название источника. Если в базе знаний нет источника с таким названием, возвращается ошибка.

segment
string
Deprecated

Сегмент (тег) базы знаний. Параметр устарел. Используйте segments.

segments
Array of strings

Сегменты (теги) базы знаний. Источник будет доступен при поиске по этим сегментам.

Длина названия сегмента — от 1 до 100 символов. В названиях не допускаются запятые.

accessControlAttributes
Array of strings

Группы доступа, которым разрешен доступ к источнику. Если группы с указанным названием нет, она создается.

Если значение не передано, группы доступа у источника не меняются (поведение обратно совместимо).

Чтобы очистить группы доступа у источника, передайте пустой массив.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "type": "FILE",
  • "accessControlAttributes": [
    ],
  • "hash": "sha256:abcd1234ef5678…",
  • "documentGroupId": "doc-42",
  • "documentVersion": "v3",
  • "isDefaultVersion": true,
  • "versionDescription": "Изменены пункты 4.1 и 4.2"
}

Информация об источнике

Возвращает информацию об источнике базы знаний.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "type": "FILE",
  • "accessControlAttributes": [
    ],
  • "hash": "sha256:abcd1234ef5678…",
  • "documentGroupId": "doc-42",
  • "documentVersion": "v3",
  • "isDefaultVersion": true,
  • "versionDescription": "Изменены пункты 4.1 и 4.2"
}

Удаление источника

Удаляет источник из базы знаний.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Скачивание источника

Скачивает файл-источник из базы знаний.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Распаршенное содержимое источника

Возвращает текст, извлеченный из источника при индексации, — тот же, по которому построены чанки. Позволяет прочитать документ целиком, когда найденных фрагментов не хватает: например, дойти от страницы вики до первоисточника по идентификатору из поля sources ответа POST /wiki/page.

Текст лежит в поле content в том виде, в каком его дал разбор (для большинства форматов это Markdown), и совпадает с содержимым, которое ушло на индексацию.

Если распаршенного текста нет — источник не разбирался или его содержимое нетекстовое (например, изображение), — ответ приходит с contentAvailable: false, и вместо текста в content лежит пояснение с метаданными файла. Двоичное содержимое этот метод не отдает никогда: исходный файл как есть скачивается методом GET /sources/{sourceId}/download.

Источник, который еще не проиндексирован, а также источник чужого проекта и страница вики отвечают 404. Страницы вики читаются методом POST /wiki/page.

Метод учитывает группы доступа (access control attributes): документ, которому они назначены, этим методом не читается и отвечает 404 — тем же ответом, что и несуществующий идентификатор, так что по отказу нельзя понять, есть ли такой источник.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

Responses

Response samples

Content type
application/json
{
  • "sourceId": 0,
  • "name": "regulations/order-118.pdf",
  • "parsedFileName": "order-118.pdf.md",
  • "sizeBytes": 254013,
  • "sizeChars": 18422,
  • "contentAvailable": true,
  • "content": "string"
}

IntegrationsPublic

Работа с интеграциями базы знаний.

Создание интеграции

Добавление новой интеграции в базу знаний. Индексация запускается автоматически после загрузки данных при создании интеграции и при автоматической синхронизации, если она включена.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Название интеграции.

returnUrl
string

URL для перенаправления пользователя после OAuth-авторизации. Применяется для интеграций с Confluence Cloud, Google Диском, OneDrive, Sharepoint, Яндекс Диском. К адресу добавляется query-параметр status=success или status=error&error_description=…. Если URL не указан, результат отобразится на стандартной HTML-странице.

autoSync
boolean

Признак необходимости автоматически синхронизировать данные.

downloadAttachmentFiles
boolean

Признак необходимости загружать прикрепленные к страницам файлы в допустимых форматах, см. требования к файлам. Эта настройка не влияет на загрузку изображений: они загружаются всегда.

syncIntervalMinutes
integer

Период обновления в минутах. Не менее 30 минут.

accessControlAttributes
Array of strings

Группы доступа, которым разрешен доступ к источникам из этой интеграции. Если группы с указанным названием нет, она создается. Если группы доступа не назначены, источники доступны всем пользователям.

required
object (IntegrationSettings)

Настройки интеграции.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "returnUrl": "https://my-app.example.com/oauth/callback",
  • "autoSync": true,
  • "downloadAttachmentFiles": true,
  • "syncIntervalMinutes": 0,
  • "accessControlAttributes": [
    ],
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "autoSync": true,
  • "syncIntervalMinutes": 0,
  • "settings": {
    },
  • "status": "ACTIVE",
  • "lastError": "string",
  • "accessControlAttributes": [
    ],
  • "lastSuccessfulSyncAt": "2019-08-24T14:15:22Z"
}

Список интеграций

Возвращает список интеграций базы знаний.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "integrations": [
    ]
}

Информация об интеграции

Возвращает информацию об интеграции.

Authorizations:
bearerAuth
path Parameters
integrationId
required
integer <int64> (LongId)

Идентификатор интеграции.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "autoSync": true,
  • "syncIntervalMinutes": 0,
  • "settings": {
    },
  • "status": "ACTIVE",
  • "lastError": "string",
  • "accessControlAttributes": [
    ],
  • "lastSuccessfulSyncAt": "2019-08-24T14:15:22Z"
}

Удаление интеграции

Удаляет интеграцию из базы знаний.

Authorizations:
bearerAuth
path Parameters
integrationId
required
integer <int64> (LongId)

Идентификатор интеграции.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

SegmentsPublic

Работа с сегментами (тегами) базы знаний.

Список сегментов

Возвращает список сегментов (тегов) базы знаний с фильтрацией по названию и постраничным выводом.

Authorizations:
bearerAuth
query Parameters
pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 20

Размер страницы.

name
string

Фильтр по названию. Поиск выполняется по подстроке без учета регистра.

Responses

Response samples

Content type
application/json
{
  • "segments": [
    ],
  • "paging": {
    }
}

Переименование сегмента

Меняет название сегмента (тега) во всех источниках, которые относятся к этому сегменту.

Authorizations:
bearerAuth
Request Body schema: application/json
required
oldName
required
string

Текущее название сегмента.

newName
required
string

Новое название сегмента. От 1 до 100 символов. В названии не допускаются запятые.

Responses

Request samples

Content type
application/json
{
  • "oldName": "Право",
  • "newName": "Юридические документы"
}

Response samples

Content type
application/json
{
  • "updatedFileIds": [
    ]
}

Привязка сегментов к источникам

Для каждого источника добавляет указанные сегменты (теги) в список сегментов, к которым относится источник.

Authorizations:
bearerAuth
Request Body schema: application/json
required
sourceIds
required
Array of integers <int64> (LongId) [ items <int64 > ]

Идентификаторы источников. Если не указаны, изменения будут применены ко всем источникам в базе знаний.

segments
required
Array of strings

Сегменты, которые нужно привязать к источникам. Длина названия сегмента — от 1 до 100 символов. В названиях не допускаются запятые.

Responses

Request samples

Content type
application/json
{
  • "sourceIds": [
    ],
  • "segments": [
    ]
}

Response samples

Content type
application/json
{
  • "updatedFileIds": [
    ]
}

Отвязка сегментов от источников

Для каждого источника удаляет указанные сегменты (теги) из списка сегментов, к которым относится источник. Если у источника отсутствует удаляемый сегмент, он игнорируется.

Authorizations:
bearerAuth
Request Body schema: application/json
required
sourceIds
required
Array of integers <int64> (LongId) [ items <int64 > ]

Идентификаторы источников.

segments
required
Array of strings

Сегменты, которые нужно отвязать от источников.

Responses

Request samples

Content type
application/json
{
  • "sourceIds": [
    ],
  • "segments": [
    ]
}

Response samples

Content type
application/json
{
  • "updatedFileIds": [
    ]
}

IndexingPublic

Управление индексацией.

Запуск индексации базы знаний

Запускает индексацию источников, которые не были проиндексированы после загрузки или индексация которых завершилась ошибкой.

Authorizations:
bearerAuth

Responses

Остановка индексации базы знаний

Прерывает текущую индексацию.

Authorizations:
bearerAuth

Responses

AutoConfigPublic

Индексация с автоподбором настроек по содержимому базы знаний.

Запуск индексации с автонастройкой

Запускает индексацию базы знаний с автоматическим подбором настроек по ее содержимому. Автонастройка выполняется без оценки качества.

Возвращает идентификатор операции, по которому можно получить ее статус и результат методом GET /autoconfig/status/{operationId}.

При отсутствии тела запроса используются значения по умолчанию.

Authorizations:
bearerAuth
Request Body schema: application/json
optional
graphPolicy
string (AutoConfigGraphPolicy)
Default: "IF_USEFUL"
Enum: "NEVER" "IF_USEFUL" "ALWAYS"

Использовать ли граф знаний:

  • NEVER — граф знаний отключен независимо от содержимого базы знаний.
  • IF_USEFUL — граф знаний включается, если он улучшит ответы по текущему содержимому базы знаний (решение принимается автоматически).
  • ALWAYS — граф знаний включен.
preset
string (AutoConfigPreset)
Default: "balanced"
Enum: "fast" "balanced" "quality"

Вариант автонастройки:

  • fast — минимум запросов к LLM, быстрая индексация.
  • balanced — баланс между скоростью индексации и качеством ответов.
  • quality — максимальное качество (обогащение чанков и поиск по метаданным включаются принудительно).
useType
string (AutoConfigUseType)
Default: "single"
Enum: "dialog" "single"

Сценарий использования базы знаний — влияет на подбор настроек генерации:

  • dialog — диалоговый бот с историей переписки.
  • single — одиночные независимые запросы.

Responses

Request samples

Content type
application/json
{
  • "graphPolicy": "NEVER",
  • "preset": "fast",
  • "useType": "dialog"
}

Response samples

Content type
application/json
{
  • "operationId": "string",
  • "status": "PENDING",
  • "phase": "PENDING",
  • "terminal": true,
  • "progress": { },
  • "lastError": "string"
}

Отмена операции автонастройки

Останавливает выполняющуюся операцию автонастройки по ее идентификатору, полученному при запуске.

Метод идемпотентен: для уже завершенной операции возвращается ее текущий статус, а не ошибка.

Отмена операции также останавливает индексацию документов, которую эта операция запустила: документы выходят из очереди на разбор и индексацию, поэтому сразу после отмены можно запустить автонастройку заново. Уже проиндексированные документы из индекса не удаляются.

Отмена индексации базы знаний также останавливает операцию автонастройки, если она выполняется.

Authorizations:
bearerAuth
path Parameters
operationId
required
string

Идентификатор операции автонастройки, полученный при запуске.

Responses

Response samples

Content type
application/json
{
  • "operationId": "string",
  • "status": "PENDING",
  • "phase": "PENDING",
  • "terminal": true,
  • "progress": { },
  • "lastError": "string"
}

Статус операции автонастройки

Возвращает текущий статус операции автонастройки по ее идентификатору, полученному при запуске. Для завершенных операций поле terminal равно true.

Authorizations:
bearerAuth
path Parameters
operationId
required
string

Идентификатор операции автонастройки, полученный при запуске.

Responses

Response samples

Content type
application/json
{
  • "operationId": "string",
  • "status": "PENDING",
  • "phase": "PENDING",
  • "terminal": true,
  • "progress": { },
  • "lastError": "string"
}

ApiKeysPublic

Работа с проектными API-ключами.

Создание API-ключа

Создает новый API-ключ для проекта базы знаний. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

Request Body schema: application/json
required
name
required
string

Название API-ключа.

expiredAt
string <date-time>

Дата и время окончания действия API-ключа. Если значение не указано, будет создан бессрочный ключ.

Responses

Request samples

Content type
application/json
{
  • "name": "Для сайта и приложений",
  • "expiredAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "projectId": 0,
  • "name": "string",
  • "key": "string",
  • "status": "string",
  • "ownerLogin": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiredAt": "2019-08-24T14:15:22Z",
  • "lastUsedAt": "2019-08-24T14:15:22Z"
}

Список API-ключей

Возвращает список API-ключей для проекта базы знаний. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

query Parameters
pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 20

Размер страницы.

onlyActive
boolean
Default: false

Возвращать только активные API-ключи.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "paging": {
    }
}

Деактивация API-ключа

Деактивирует API-ключ проекта базы знаний. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Идентификатор проекта базы знаний.

apiKeyId
required
integer <int64> (LongId)

Идентификатор API-ключа.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "projectId": 0,
  • "name": "string",
  • "key": "string",
  • "status": "string",
  • "ownerLogin": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiredAt": "2019-08-24T14:15:22Z",
  • "lastUsedAt": "2019-08-24T14:15:22Z"
}

WikiPublic

LLM-вики по источникам базы знаний: генерация и чтение.

Запуск генерации вики

Запускает асинхронную генерацию (или перегенерацию) вики базы знаний. Доступно, если в настройках проекта включена LLM-вики и установлен ручной режим запуска.

Возвращает идентификатор операции, по которому можно получить ее статус методом GET /wiki/status/{operationId}.

Authorizations:
bearerAuth
Request Body schema: application/json
optional
strategy
string

Зарезервировано для будущего использования.

Responses

Request samples

Content type
application/json
{
  • "strategy": "string"
}

Response samples

Content type
application/json
{
  • "operationId": "string",
  • "status": "string",
  • "progress": "string",
  • "error": "string"
}

Состояние генерации вики проекта

Возвращает состояние генерации вики проекта, не требуя идентификатора операции: идущий прогон, а если активного нет — последний завершённый. Если прогонов не было ни одного, поле operationId отсутствует, а status равен NONE. Для этой операции требуется API-ключ проекта.

Дополняет GET /wiki/status/{operationId}, который отвечает по конкретной операции и работает по-прежнему. Эта ручка нужна вызывающему, который идентификатор потерял (перезагрузка страницы) или не получал вовсе.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "operationId": "string",
  • "status": "string",
  • "progress": "string",
  • "error": "string"
}

Статус генерации вики

Возвращает статус генерации вики по идентификатору операции, полученному при запуске.

Authorizations:
bearerAuth
path Parameters
operationId
required
string

Идентификатор операции генерации вики, полученный при запуске.

Responses

Response samples

Content type
application/json
{
  • "operationId": "string",
  • "status": "string",
  • "progress": "string",
  • "error": "string"
}

Список страниц вики

Возвращает постраничный список страниц вики.

Страницы отбираются с учетом переданных в accessSettings групп доступа: если группы не указаны, возвращаются только страницы без ограничений доступа.

Authorizations:
bearerAuth
Request Body schema: application/json
optional
object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 20

Размер страницы.

name
string

Фильтр по названию страницы. Поиск выполняется по подстроке без учета регистра.

sort
string
Default: "title"
Enum: "title" "updatedAt" "path"

Поле сортировки.

direction
string
Default: "asc"
Enum: "asc" "desc"

Направление сортировки.

Responses

Request samples

Content type
application/json
{
  • "accessSettings": {
    },
  • "pageNum": 0,
  • "pageSize": 20,
  • "name": "string",
  • "sort": "title",
  • "direction": "asc"
}

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "paging": {
    }
}

Оглавление вики

Возвращает оглавление вики в виде дерева.

Страницы отбираются с учетом переданных в accessSettings групп доступа.

Authorizations:
bearerAuth
Request Body schema: application/json
optional
object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

accessControlAttributes
Array of strings

Группы доступа для фильтрации источников.

  • Если указаны, отбираются источники, которым назначена хотя бы одна из указанных групп доступа, а также источники без групп доступа.
  • Если не указаны, отбираются только источники без групп доступа.

Подробное описание см. в документации.

integrationId
integer <int64>

Идентификатор интеграции с Confluence. Обязательный, если указан externalUserId.

externalUserId
string

Идентификатор пользователя Confluence для фильтрации источников. Обязательный, если указан integrationId.

Responses

Request samples

Content type
application/json
{
  • "accessSettings": {
    }
}

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "stats": {
    }
}

Содержимое страницы вики

Возвращает страницу вики вместе с ее содержимым в формате Markdown.

Если страница недоступна с учетом переданных в accessSettings групп доступа, возвращается ответ 404.

Authorizations:
bearerAuth
Request Body schema: application/json
required
pageId
required
string

Адрес страницы вики в любой из печатных форм платформы: 24111, wiki_page:24111 или wiki_page:24111:<локатор> — это одна и та же страница, локатор у страницы вики значения не имеет и отбрасывается. Форму вид:идентификатор печатает POST /context/route в поле handle, и передать её сюда дословно — штатный способ. Строка, не разобранная ни в одну из форм, и адрес ЧУЖОГО вида (например mcp_source:123) отвечают 400 khub.context.handle_unresolved: чужой вид читается другой операцией, а не этой, и молча прочитать по нему страницу вики с тем же номером нельзя.

object (AccessSettings)

Настройки для фильтрации источников.

Если указаны параметры integrationId и externalUserId, на основе прав пользователя в Confluence автоматически формируется список групп доступа, который объединяется со списком из параметра accessControlAttributes. Подробное описание см. в документации.

Responses

Request samples

Content type
application/json
{
  • "pageId": "string",
  • "accessSettings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "path": "string",
  • "title": "string",
  • "type": "string",
  • "summary": "string",
  • "external": false,
  • "externalIntegrationId": 0,
  • "externalPartial": true,
  • "externalLastSurveyedAt": "string",
  • "sources": [
    ],
  • "updatedAt": "string",
  • "markdown": "string"
}

McpServerPublic

Параметры подключения агента к базе знаний — плагин Claude Code и MCP-сервер Knowledge Hub.

Значения зависят от инсталляции, поэтому команды подключения собираются из ответа, а не хранятся в клиенте константами. API-ключ для операции не нужен.

Параметры подключения агента

Возвращает все, из чего собираются две команды подключения агента к базе знаний этой инсталляции: установка плагина Claude Code и запуск MCP-сервера вручную — для любого другого MCP-клиента.

Значения задаются администратором инсталляции, поэтому клиент должен брать их из ответа, а не хранить константами. Образ сервера и адрес инсталляции здесь те же, что в раздаваемом плагине, — две команды не могут указать на разные сборки.

Операция не требует API-ключа: ее читают до того, как ключ появился, и она не содержит ни секретов, ни данных проектов. Сам ключ проекта в ответ не входит — передаются только имена настройки и переменной окружения, в которые его нужно подставить.

Responses

Response samples

Content type
application/json
{
  • "name": "khub",
  • "image": "docker-hub.just-ai.com/components/knowledge-hub-mcp-release:trunk-latest",
  • "port": 8000,
  • "path": "/mcp",
  • "env": {},
  • "projectTokenEnv": "KHUB_PROJECT_API_TOKEN",
  • "projectApiKeyName": "agent-wiki",
  • "plugin": {}
}

ContextPublic

Контекстное API: маршрутизация вопроса по базе знаний и сборка пакета материала для агента.

Тела операций не содержат accessSettings: фильтр доступа выводится из типа ключа, которым сделан запрос, и вызывающий не может его расширить.

Маршрутизация вопроса по базе знаний

По тексту вопроса возвращает указатели на то, где искать ответ: страницы вики, документы под ними и корневые страницы описей внешних источников. Ответа на вопрос операция не дает и содержимого не отдает — только адреса, заголовки и обоснования, по которым выбирают, куда идти дальше.

Отбор делает модель. Ей показывают узлы оглавления вики (заголовок и аннотация) и имена документов-источников под ними; она называет те единицы, которые нужны для этого вопроса, и пишет обоснования. Это всегда один вызов модели: операция не мгновенная, и ее расход начисляется на базу знаний.

Лексического запасного пути нет. Если ранжирование не настроено, модель не отвечает или не укладывается в отведенное время — операция отдает ЯВНУЮ ошибку (khub.context.ranking_not_configured — 500, khub.context.ranking_failed — 503, khub.context.ranking_timed_out — 504), а не выдачу худшего качества.

Законных пустых ответов ДВА, и они различимы по mapStatus:

  • у проекта нет построенной вики — pointers пуст, mapStatus.wikiBuilt равен false, rankedBy отсутствует, расход нулевой: модель не вызывалась;
  • модель вызвана и не выбрала ничего — pointers пуст, но mapStatus.wikiBuilt равен true, mapStatus.note это называет, rankedBy заполнен, candidatesSent и usage не нулевые, и в warnings есть строка об этом. Это 200, а не ошибка: ранкер отработал, повтор того же вопроса на той же модели даст то же самое.

Любое сокращение названо: inputTruncated и candidatesSent/candidatesTotal — если часть базы знаний не поместилась в потолок входа, selectionTruncated и selectedTotal — если отбор не поместился в limit, и warnings — словами, включая случай, когда отбор сделала модель инсталляции, а не запрошенная.

Фильтр доступа выводится из типа ключа: accessSettings в теле нет и передать его нельзя.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string

Вопрос пользователя, как он задан.

limit
integer <int32>

Сколько указателей вернуть. По умолчанию 25, потолок 50 — значение выше потолка приводится к нему, а не отвергается.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "pointers": [
    ],
  • "mapStatus": {
    },
  • "rankedBy": "string",
  • "rankedByOwner": "string",
  • "candidatesTotal": 0,
  • "candidatesSent": 0,
  • "inputTruncated": true,
  • "selectedTotal": 0,
  • "selectionTruncated": true,
  • "warnings": [
    ],
  • "usage": {
    }
}

Сборка пакета материала под вопрос

Собирает под вопрос пакет материала: бюджетированный цикл читает страницы вики, документы под ними и допущенные внешние источники, отбирает фрагменты и снабжает каждый провенансом, по которому его можно перепроверить. В отличие от route, операция отдает содержимое.

Прогон стоит денег и времени: расход держится в объявленном бюджете, дедлайн сервер приводит к своим границам (по умолчанию 90 сек, потолок 120 сек, пол 60 сек; ниже пола — 400 khub.context.deadline_too_short, потому что такой прогон не может начаться). async: true — прогон уходит в фон, ответ 202 несет operationId, результат читается операцией ниже тем же ключом, которым запущен.

Неполный результат — это ответ, а не ошибка. Прогон, который не уложился в бюджет или дедлайн, отдает то, что успел, с заполненным degraded.reason; прогон, не собравший ничего, отдает выдачу route — указатели на то, где искать, — с тем же degraded.reason. Ошибка сказала бы вызывающему о базе знаний меньше, чем карта.

Пустая карта прогон не отменяет. Если ранкер не выбрал ни одного адреса, build все равно запускается: указатели — это якоря, они и по умолчанию не подаются, а базу знаний цикл читает сам. В ответе тогда pointers пуст и mapStatus.wikiBuilt равен true с пояснением в mapStatus.note — ровно то же, что отдал бы route.

pointers по умолчанию не подаются циклу: замер показал, что указатель работает якорем и сужает исследование (покрытие падает на 0,10–0,14). Подавать стоит там, где вызывающий сам называет адрес. В ответе pointers присутствуют всегда, независимо от режима подачи.

Поданный адрес разбирается кодом и никогда не отбрасывается молча. Формы адреса: вид:идентификатор, вид:идентификатор:локатор и голый идентификатор. Адрес, не разобранный ни в одной из них, — 400 khub.context.handle_unresolved с перечнем форм в теле; разобранный, но неизвестный, чужой или невидимый этому ключу — 404 без пояснений (неизвестное и недоступное отвечают одинаково).

Фильтр доступа выводится из типа ключа: accessSettings в теле нет и передать его нельзя.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string

Вопрос пользователя, как он задан.

object (ContextBuildBudget)

Потолки прогона. Оба необязательны. Запрос выше потолка приводится к потолку — вызывающий, попросивший больше, не сделал ошибки, ради которой стоит отказывать в чтении; дедлайн ниже пола отклоняется, потому что такой прогон не может начаться.

pointers
Array of strings

Адреса из route, которые подать циклу как подсказку. По умолчанию пусто — «не подавать»: указатель сужает исследование, и это поведение самого build, а не забота вызывающего. Подавать стоит, когда адрес и есть ответ («что на странице X»). Формы: вид:идентификатор, вид:идентификатор:локатор, голый идентификатор. Неразобранный адрес — 400 khub.context.handle_unresolved с перечнем форм; разобранный, но недоступный — 404.

async
boolean

Отдать 202 с operationId и вести прогон в фоне. По умолчанию false — ответ приходит по завершении прогона, в пределах дедлайна.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "budget": {
    },
  • "pointers": [
    ],
  • "async": true
}

Response samples

Content type
application/json
{
  • "operationId": "3051932a-fdd2-48fa-b330-7e7d41535969",
  • "status": "string",
  • "fragments": [
    ],
  • "pointers": [
    ],
  • "mapStatus": {
    },
  • "degraded": {
    },
  • "usage": {
    },
  • "manifest": {
    }
}

Состояние и результат фонового прогона сборки

Отдает состояние прогона и, когда он завершен, собранный пакет.

Читается только тем ключом, которым запущен (keyId + проект): пакет — производный артефакт, собранный под фильтр доступа своего создателя, и второй ключ того же проекта может держать другие атрибуты. Чужой, неизвестный и истекший прогон отвечают одинаково — 404, и различить их нельзя.

Строка прогона живет ограниченное время (по умолчанию час после завершения), после чего убирается.

Authorizations:
bearerAuth
path Parameters
operationId
required
string <uuid>

Идентификатор прогона из ответа 202.

Responses

Response samples

Content type
application/json
{
  • "operationId": "3051932a-fdd2-48fa-b330-7e7d41535969",
  • "status": "string",
  • "fragments": [
    ],
  • "pointers": [
    ],
  • "mapStatus": {
    },
  • "degraded": {
    },
  • "usage": {
    },
  • "manifest": {
    }
}

Вызов инструмента внешнего источника

Вызывает один допущенный инструмент внешнего MCP-источника и отдает его ответ фрагментами, каждый — с провенансом, по которому вызов воспроизводится.

Порядок отказов: источника нет у этого проекта — 404, тот же, что у несуществующего идентификатора; инструмент не подтвержден администратором, аргументы не подходят под сохраненную схему или нарушают ограничения — 400 с названием инструмента. Проверка идет по схеме, сохраненной в момент подтверждения, а не по живой декларации источника: живая могла измениться после того, как человек принял решение.

Аргументы проходят как есть — JQL с кириллицей, wildcard-предикаты, fields-проекции. Платформа их не нормализует и не переписывает.

Отказ, пришедший от исполнителя вызова, доезжает до вызывающего своим кодом khub.context.*, своим сообщением и своими аргументами, под своим статусом: 400 с названием инструмента и перечнем допустимых имен аргументов, 415 с типом и размером бинарного ответа.

Каждый вызов пишется в аудит с полными аргументами.

Authorizations:
bearerAuth
Request Body schema: application/json
required
integrationId
required
integer <int64>

Идентификатор источника. Чужой и неизвестный отвечают одинаково — 404.

tool
required
string

Имя инструмента. Вызвать можно только инструмент, подтвержденный администратором.

cursor
string

Продолжить с той страницы, которую назвал предыдущий ответ. Отсутствие — первая страница. Вызов с курсором обходит кэш дедупликации: «следующая страница» — по определению не тот ответ, который был закэширован для первой.

required
object

Аргументы инструмента. Проходят к источнику как есть: платформа их не нормализует. Проверяются по схеме, сохраненной при подтверждении инструмента.

Responses

Request samples

Content type
application/json
{
  • "integrationId": 0,
  • "tool": "string",
  • "cursor": "string",
  • "args": { }
}

Response samples

Content type
application/json
{
  • "tool": "string",
  • "fragments": [
    ],
  • "truncated": true,
  • "cursor": "string",
  • "fingerprint": {
    }
}

AccessControlPublic

Список групп доступа

Возвращает список групп доступа в аккаунте. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
query Parameters
pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 20

Размер страницы.

name
string <= 100 characters
Example: name=HR

Отбирать группы доступа по названию. Поиск выполняется по подстроке без учета регистра.

projectIds
Array of integers <int64> [ items <int64 > ]
Example: projectIds=1,2,3

Отбирать группы доступа, назначенные хотя бы одному источнику в одном из указанных проектов. Идентификаторы проектов указываются через запятую.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "paging": {
    }
}

Информация о группе доступа

Возвращает детальную информацию о группе доступа с постраничным выводом источников. Для этой операции требуется административный API-ключ.

Authorizations:
bearerAuth
path Parameters
attributeId
required
integer <int64> (LongId)

Идентификатор группы доступа.

query Parameters
pageNum
integer <int32> >= 0
Default: 0

Порядковый номер страницы для постраничного вывода, начиная с 0.

pageSize
integer <int32> [ 1 .. 10000 ]
Default: 20

Размер страницы.

filename
string

Отбирать источники по названию. Поиск выполняется по подстроке без учета регистра.

projectIds
string

Отбирать источники из указанных проектов. Идентификаторы проектов указываются через запятую.

segments
string

Отбирать источники из указанных сегментов. Сегменты указываются через запятую.

Responses

Response samples

Content type
application/json
{
  • "attribute": {
    },
  • "files": [
    ],
  • "paging": {
    }
}

ChunksPublic

Список чанков источника

Возвращает все чанки, полученные из источника при индексации, в том числе описания изображений (если эта опция включена) и суммаризации (если построены по отдельным документам).

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Получение чанка

Возвращает данные чанка. Работает, только если идентификатор чанка не содержит /. Для поиска чанка по идентификатору в любом формате используйте GET /chunks/lookup.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

chunkId
required
string

Идентификатор чанка (без /).

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "docId": "string",
  • "chunkNumber": 0,
  • "content": "string",
  • "summary": "string",
  • "questions": [
    ],
  • "keywords": [
    ],
  • "segments": [
    ],
  • "metadata": {
    },
  • "raptorLevel": 0,
  • "isRaptorSummary": true,
  • "accessControlAttributes": [
    ]
}

Поиск чанка по идентификатору из логов

Возвращает данные чанка. Принимает идентификатор в любом формате, в том числе устаревшем (с /, из логов версии до версии AP-2026.1).

Authorizations:
bearerAuth
query Parameters
id
required
string

Идентификатор чанка (любой формат).

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "docId": "string",
  • "chunkNumber": 0,
  • "content": "string",
  • "summary": "string",
  • "questions": [
    ],
  • "keywords": [
    ],
  • "segments": [
    ],
  • "metadata": {
    },
  • "raptorLevel": 0,
  • "isRaptorSummary": true,
  • "accessControlAttributes": [
    ]
}

Дерево суммаризаций источника

Возвращает структуру дерева суммаризаций (RAPTOR — Recursive Abstractive Processing for Tree-Organized Retrieval) документа-источника, если построены суммаризации по отдельным документам.

Структура не включает тексты суммаризаций: используйте GET /sources/{sourceId}/chunks/{chunkId} или GET /chunks/lookup для получения текста.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Идентификатор источника.

Responses

Response samples

Content type
application/json
{
  • "hasRaptor": true,
  • "maxLevel": 0,
  • "totalNodes": 0,
  • "summaryNodes": 0,
  • "leafNodes": 0,
  • "nodes": [
    ]
}

Дерево суммаризаций всей базы знаний

Возвращает структуру дерева суммаризаций (RAPTOR — Recursive Abstractive Processing for Tree-Organized Retrieval) всей базы знаний или всех документов-источников — в зависимости от режима построения суммаризаций.

Структура не включает тексты суммаризаций.

Объем данных может быть большим для проектов со множеством источников.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}