База знаний

Все методы · Ключи и права · Ошибки

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

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Получить статьи

GET /api/v1/kb/articles

Действие ключа: kb:read. Оно не заменяет права владельца на объекты и поля.

locale по умолчанию ru-RU. Используется операторский канал и права базы знаний; это не список всех черновиков.

Параметры пути: нет. Тело: не требуется.

Query-пример: locale=ru-RU.

Пример запроса

GET /api/v1/kb/articles?locale=ru-RU HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив статей.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Прочитать статью

GET /api/v1/kb/articles/{articleId}

Действие ключа: kb:read. Оно не заменяет права владельца на объекты и поля.

articleId — ID статьи, не её версии; locale выбирает перевод.

Параметры пути: articleId. Тело: не требуется.

Query-пример: locale=ru-RU.

Пример запроса

GET /api/v1/kb/articles/ARTICLE_ID?locale=ru-RU HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Проекция статьи с содержимым.

{
  "data": {
    "id": "ARTICLE_ID",
    "versionId": "VERSION_ID",
    "title": "Название",
    "body": "Текст"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать черновик статьи

POST /api/v1/kb/articles

Действие ключа: kb:write. Оно не заменяет права владельца на объекты и поля.

Нужны существующие база и раздел. visibility должна соответствовать базе (internal/portal). Можно передать summary, tags, responsibleId, bodyDocument вместо plain body. Черновики здесь — версии статей, не черновики заявок.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/kb/articles HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "baseId": "BASE_ID",
  "sectionId": "SECTION_ID",
  "code": "sample-article",
  "title": "Название",
  "locale": "ru-RU",
  "body": "Текст",
  "visibility": "internal"
}

Ответ и ошибки

Успех: 201. Версия статьи.

{
  "data": {
    "id": "ARTICLE_ID",
    "versionId": "VERSION_ID",
    "state": "DRAFT",
    "title": "Название"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Изменить черновик статьи

PATCH /api/v1/kb/article-versions/{versionId}

Действие ключа: kb:write. Оно не заменяет права владельца на объекты и поля.

Только DRAFT. Изменяемые поля: title, summary, body/bodyDocument, tags, responsibleId, visibility. Перемещение в другой sectionId требует отдельного UI-действия и здесь запрещено.

Параметры пути: versionId. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

PATCH /api/v1/kb/article-versions/VERSION_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "Новое название",
  "body": "Новый текст"
}

Ответ и ошибки

Успех: 200. Версия статьи.

{
  "data": {
    "id": "ARTICLE_ID",
    "versionId": "VERSION_ID",
    "state": "DRAFT",
    "title": "Новое название"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Опубликовать статью

POST /api/v1/kb/articles/publish

Действие ключа: kb:write. Оно не заменяет права владельца на объекты и поля.

Дополнительно право kb.publish. Для версии нужна хотя бы одна аудитория. Настройка аудитории не предоставлена отдельным публичным v1 endpoint: выполните её в интерфейсе.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/kb/articles/publish HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "versionId": "VERSION_ID"
}

Ответ и ошибки

Успех: 200. Опубликованная версия.

{
  "data": {
    "id": "ARTICLE_ID",
    "versionId": "VERSION_ID",
    "state": "ACTIVE"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Архивировать статью

POST /api/v1/kb/articles/archive

Действие ключа: kb:write. Оно не заменяет права владельца на объекты и поля.

Для современных раздельных баз выполняется material action: version — непрозрачный токен актуального материала, не номер версии статьи. Получение этого токена не покрыто публичным v1 API: используйте архивирование в интерфейсе. Наличие route не означает самостоятельный полный внешний сценарий.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/kb/articles/archive HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "versionId": "VERSION_ID",
  "version": "CURRENT_MATERIAL_VERSION",
  "confirmed": true
}

Ответ и ошибки

Успех: 200. Результат архивирования; форма зависит от модели базы.

{
  "data": {
    "id": "ARTICLE_ID"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Связанные статьи

• Обзор API
• Права доступа
• Интеграции