openapi: 3.1.0 info: title: Документерра API версия 2.0.0 description: | Каждый портал Документерры оснащен интерфейсом REST API, позволяющим автоматизировать задачи и интегрировать процесс создания докуметации в существующие бизнес-процессы. Базовый URL-адрес: https://{your-portal-URL}/api/v2/ Авторизация: Большинство запросов к REST API Документерры используют базовую авторизацию (login + API key), некоторые запросы можно делать анонимно. [Запросить API ключ](https://docs.documenterra.ru/articles/manual/polucheniye-klyucha-api) можно в профиле пользователя. При возникновении ошибок смотрите статью [Устранение неполадок API](https://docs.documenterra.ru/articles/manual/ustraneniye-nepoladok-api). version: 2.0.0 servers: - url: "https://{your-portal-URL}/api/v2/" description: API портала variables: your-portal-URL: default: library.documenterra.net tags: - name: Проекты и публикации description: API проектов и публикаций позволяет получать информацию о проектах и публикациях, экспортировать их и изменять их видимость. - name: Отчеты и аналитика description: API отчетности и аналитики позволяет получать различную статистику портала, например, просмотры топиков или поисковые запросы пользователей. - name: Поиск description: API полнотекстового поиска позволяет отправлять поисковые запросы на портале Документерра и получать результаты поиска для дальнейшего использования. - name: Хранилище файлов description: API хранилища файлов позволяет работать с файлами в хранилище Документерры — создавать новые файлы, получать информацию о них, удалять файлы и т.д. - name: Элементы Дерева страниц description: API Дерева страниц позволяет управлять деревом элементов контента и связанными с ними страницами — получать информацию о них, удалять, обновлять и т.д. - name: Страницы description: API страниц позволяет управлять страницами в рамках проекта — создавать, обновлять, получать информацию и т.д. - name: Пользователи description: API пользователей позволяет генерировать токены для входа в систему, создавать учетные записи для авторизованных читателей и т.д. - name: ИИ Помощник description: API ИИ помощника позволяет отправлять запросы к ИИ помощнику и получать ответы на основе документации на вашем портале Документерры. - name: Статусы рабочего процесса description: API статусов рабочего процесса позволяет управлять статусами — получать информацию, создавать, обновлять и удалять их. - name: Переходы рабочего процесса description: API переходов рабочего процесса позволяет управлять переходами между статусами — получать информацию, создавать и удалять их. paths: # ────────────────────────────────────────────── # Проекты и публикации # ────────────────────────────────────────────── /projects: get: operationId: getAllProjectsPublications summary: Получение всех проектов и публикаций description: Получение информации обо всех проектах и публикациях, доступных пользователю, сделавшему запрос. tags: - Проекты и публикации parameters: - name: types in: query required: false description: Тип(ы) получаемой записи – Project or Publication. Если не указано, возвращает оба типа. schema: type: string - name: parentId in: query required: false description: Идентификатор проекта. Если указано, возвращает публикации только для указанного проекта. schema: type: string responses: "200": $ref: "#/components/responses/ProjectDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} post: operationId: createProject summary: Создать новый проект description: Создаёт новый пустой проект, проект из шаблона или копирует существующий проект. tags: - Проекты и публикации requestBody: required: true content: application/json: schema: type: object required: - projectName properties: projectName: type: string description: Имя нового проекта. projectId: type: string description: Идентификатор (URL-адрес) нового проекта. Если не указан, он будет сгенерирован на основе названия проекта. sourceType: type: string description: "Тип источника для создания проекта: `Empty` (по умаолчанию), `Template`, или `Copy`. Используется при `action=create`." enum: [Empty, Template, Copy] sourceProjectId: type: string description: Идентификатор существующего проекта, который будет использоваться в качестве источника. Обязательно, если `sourceType` имеет значение `Template` (используйте 'minimalist-template', 'api-documentation-template', 'coffee-break-template', 'colorize-template', 'mountain-peak-template' или 'stardust-template') или `Copy` (используйте идентификатор вашего существующего проекта). Используется при `action=create`. languageFourLetterCode: type: string description: Четырехбуквенный код языка нового проекта (например, 'en-US'). Если не указано, будет использован язык портала по умолчанию. Используется при `action=create`. responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{id}: get: operationId: getProjectPublication summary: Получение информации о проекте/публикации description: Получение информации об отдельном проекте или публикации. tags: - Проекты и публикации parameters: - name: id in: path required: true description: Идентификатор проекта/публикации, о котором нужно получить информацию. schema: type: string responses: "200": $ref: "#/components/responses/ProjectInfoResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} patch: operationId: changePublicationVisibility summary: Изменение видимости публикации description: "Изменение видимости публикации." tags: - Проекты и публикации parameters: - name: id in: path required: true description: Идентификатор публикации, видимость которой необходимо изменить. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: updatedFields: type: string description: Разделённый запятыми список полей, которые подлежат обновлению. Если имя поля отсутствует в списке, то оно не будет обновлено, даже если значение поля указано в других параметрах запроса. example: visibility visibility: type: string description: Новое значение видимости. Это может быть одно из следующих значений с учетом регистра - Private, Restricted, Public enum: - Private - Restricted - Public required: - updatedFields - visibility responses: "200": $ref: "#/components/responses/ProjectInfoResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: operationId: deleteProject summary: Удаление проекта/публикации description: Удаляет проект или публикацию из вашего портала. tags: - Проекты и публикации parameters: - name: id in: path required: true description: Идентификатор проекта или публикации для удаления. schema: type: string requestBody: $ref: "#/components/requestBodies/DeleteProject" responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/import: post: operationId: importNewProject summary: Импорт нового проекта description: Создает новый проект путём импортирования из одного из поддерживаемых форматов. tags: - Проекты и публикации parameters: - name: format in: query required: true description: Формат предоставления данных для импорта. Может быть url или base64. schema: type: string enum: [url, base64] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ImportProjectBody" responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/export: post: operationId: exportPublication summary: Экспорт публикации description: Экспорт публикации в указанный формат. tags: - Проекты и публикации parameters: - name: project-id in: path required: true description: Идентификатор экспортируемой публикации. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: format: type: string description: Один из разрешенных форматов экспорта с учетом регистра символов. enum: - WebHelp - PureHtml - Markdown - Chm - Pdf - Doc - Docx - Rtf - Epub - Mht - Odt outputFileName: type: string description: Полное имя выходного файла. Если выходной файл сохраняется в хранилище файлов Документерры (по умолчанию), должно быть указано полное имя файла, включая путь к файлу, начинающийся с Storage/. example: Storage/export-files/deep-space-1.0-docs.zip exportPresetName: type: string description: Только для печатных форматов. Полное название используемого Пресета экспорта. ftpInfo: type: object description: Объект, определяющий параметры подключения к FTP-серверу. Если указано значение null, выходной файл будет записан в хранилище файлов портала Документерра. properties: hostName: type: string description: Имя FTP-хоста вашего FTP-сервера, например ftp.library.net. userName: type: string description: Имя пользователя FTP. password: type: string description: Пароль пользователя FTP. isUsePassiveMode: type: boolean description: Определяет, следует ли использовать пассивный режим для подключения через FTP-соединение. Попробуйте установить значение true (верно), если вы сталкиваетесь с ошибками FTP, в частности с ошибкой 425 «Не удается открыть подключение к данным». port: type: integer description: Порт FTP-сервера, с которым установлено соединение. Если указано значение null или значение не указано, используется порт FTP по умолчанию. responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/download: post: operationId: downloadProject summary: Создание резервной копии проекта description: Создание резервной копии проекта в указанном месте в хранилище портала с указанным именем файла. tags: - Проекты и публикации parameters: - name: project-id in: path required: true description: Идентификатор проекта, резервную копию которого необходимо создать. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: outputFileName: type: string description: Полное имя файла, включая путь к файлу, начинающийся сStorage/. example: Storage/backups/deep-space-backup.zip responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/publish: post: operationId: publishProject summary: Публикация проекта description: Создает новую онлайн-публикацию или обновляет существующую. tags: - Проекты и публикации parameters: - name: project-id in: path required: true description: Идентификатор проекта, который нужно опубликовать. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: pubId: type: string description: Идентификатор создаваемой публикации. pubName: type: string description: Имя создаваемой публикации. isPublishOnlyReadyTopics: type: boolean description: Указывает, следует ли публиковать только разделы со статусом Готово. outputTags: type: array items: type: string description: Массив строк, содержащих условные теги, которые необходимо применить. pubVisibility: type: string description: Видимость целевой публикации. Возможные значения `Public`, `Restricted` и `Private`. enum: - Public - Restricted - Private publishedTocNodeIds: type: array items: type: string description: Массив строк, содержащих идентификаторы элементов Дерева страниц, которые подлежат публикации. Если не указано, публикуется весь проект. updatedPubId: type: string description: Идентификатор публикации, которую нужно обновить. updateMode: type: string description: Определяет, какой режим обновления выбрать. Укажите режим полного обновления `FullReplace` или частичного обновления `Partial`. enum: - FullReplace - Partial isReplacePubStyles: type: boolean description: Указывает, следует ли заменять стили публикации. Доступно только в том случае, если установлен режим частичного обновления `Partial`. По умолчанию значение `false`. isReplacePubScripts: type: boolean description: Указывает, следует ли заменять скрипты публикации. Доступно только в том случае, если установлен режим частичного обновления. По умолчанию значение `false`. responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/import: post: operationId: importToProject summary: Импорт в существующий проект description: Импортирует документацию различных форматов в существующий проект. tags: - Проекты и публикации parameters: - name: project-id in: path required: true description: Идентификатор проекта, в который нужно импортировать файл. schema: type: string - name: format in: query required: true description: Формат предоставления данных для импорта. Может быть url или base64. schema: type: string enum: [url, base64] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ImportProjectBody" responses: "200": $ref: "#/components/responses/SuccessfulTask" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{projectId}/publications: get: operationId: getProjectPublications summary: Получение информации о публикациях проекта description: Возвращает список публикаций относящихся к определённому проекту. tags: - Проекты и публикации parameters: - name: projectId in: path required: true description: Идентификатор проекта, к которому относятся публикации. schema: type: string responses: "200": $ref: "#/components/responses/ProjectDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/users: get: operationId: getUsersWithAccessToProjectPublication summary: Получение информации о пользователях с доступом к проекту/публикации description: Возвращает список пользователей, имеющих доступ к конкретному проекту или публикации. tags: - Проекты и публикации parameters: - name: project-id in: path required: true description: Идентификатор проекта/публикации для получения информации о нем. schema: type: string - name: types in: query required: false description: Фильтр по типам пользователей (через запятую). schema: type: string enum: [PowerReader, Contributor] responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: userInfo: type: object description: Объект, содержащий основную информацию профиля. properties: about: type: string description: Информация, указанная пользователем в поле «Информация». avatarImageUrl: type: string nullable: true description: URL-адрес изображения, используемого в качестве аватара. cultureInfoId: type: string description: Четырехбуквенный код языка пользователя. email: type: string description: Электронная почта пользователя. firstName: type: string description: Имя пользователя. isAutoDetectCultureInfo: type: boolean description: Определяется ли формат даты/времени автоматически. Значение `false`, если формат даты/времени явно установлен пользователем. isAutoDetectTimeZone: type: boolean description: Установлено ли автоматическое определение часового пояса. lastActivityDate: type: string nullable: true description: Временная метка ISO 8601 даты последней активности пользователя. Часовой пояс GMT. lastName: type: string description: Фамилия пользователя. middleName: type: string description: Отчество пользователя. timeZoneId: type: string description: Идентификатор часового пояса, указанный пользователем. userName: type: string description: Логин пользователя. userType: type: string description: Тип пользователя – `PowerReader` или `Contributor`. userRole: type: string nullable: true description: Список групп доступа рецензентов или Авторизованных читателей, к которым принадлежит этот пользователь (через запятую). isEnabled: type: boolean description: Включена ли учетная запись. example: - userInfo: about: "" avatarImageUrl: null cultureInfoId: ru-RU email: admin@email.com firstName: "" isAutoDetectCultureInfo: true isAutoDetectTimeZone: true lastActivityDate: "/Date(1734525940030+0000)/" lastName: "" middleName: "" timeZoneId: Jordan Standard Time userName: admin userRole: Administrator userType: Contributor isEnabled: true - userInfo: about: "" avatarImageUrl: null cultureInfoId: en-GB email: power-reader@email.com firstName: "" isAutoDetectCultureInfo: false isAutoDetectTimeZone: true lastActivityDate: null lastName: "" middleName: "" timeZoneId: UTC userName: power-reader userRole: null userType: PowerReader isEnabled: true "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /tasks/{taskKey}: get: operationId: getProjectManagementTaskStatus summary: Получение статуса задачи управления проектом description: "Получение статуса задачи в рамках проекта. После завершения задания сервер будет ждать от вас получения статуса, после чего задание будет завершено — т.е. на все последующие запросы к одному и тому же завершенному заданию будет выдаваться ошибка 404." tags: - Проекты и публикации parameters: - name: taskKey in: path required: true description: Ключ задачи, статус которой необходимо получить. schema: type: string responses: "200": $ref: "#/components/responses/TaskStatusResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /users/{user-login}/projects: get: operationId: getPublicationsAvailableToUser summary: Получение списка публикаций, доступных авторизованному читателю description: Получение списка публикаций, доступных авторизованному читателю. tags: - Проекты и публикации parameters: - name: user-login in: path required: true description: Логин авторизованного читателя для получения списка доступных публикаций. schema: type: string responses: "200": description: OK $ref: "#/components/responses/ProjectDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" # ────────────────────────────────────────────── # Topics # ────────────────────────────────────────────── /projects/{id}/articles: get: operationId: getAllTopicsFromProject summary: Получение всех страниц из проекта/публикации description: Получение информации по всем страницам проекта. tags: - Страницы parameters: - name: id in: path required: true description: Идентификатор проекта или публикации, из которой необходимо получить страницы. schema: type: string - name: isReturnSnippets in: query required: false description: Если true, возвращает `ftsTitle` и `ftsSnippet` в ответе. schema: type: boolean example: true - name: format in: query required: false description: "Формат поля `compiledContent` в ответе. Допустимые значения `html`, `md`. По умолчанию: `html`." schema: type: string enum: - html - md example: "html" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Topic" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} delete: operationId: deleteTopics summary: Удаление нескольких страниц description: Удаление нескольких страниц из проекта. tags: - Страницы parameters: - name: id in: path required: true description: Идентификатор проекта или публикации, из которой необходимо удалить страницы. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - ids properties: ids: type: array items: type: string description: Массив строк, содержащих идентификаторы страниц. responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/articles: post: operationId: createTopic summary: Создание страницы description: Создание новой страницы в проекте. tags: - Страницы parameters: - name: project-id in: path required: true description: Идентификатор проекта, в котором будет создана страница. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - id properties: assigneeUserName: type: string description: Логин исполнителя, которому назначена страница. body: type: string description: HTML-контент страницы. id: type: string description: Идентификатор страницы. isShowInToc: type: boolean description: Определяет, отображается ли страница в качестве элемента Дерева страниц в публикациях. Определяет соответствующий параметр в свойствах страницы. Условие `false` (ложно) по умолчанию. ownerUserName: type: string description: Логин владельца страницы. parentTocNodeId: type: string description: Уникальный идентификатор родительского элемента Дерева страниц. Если указано значение `null`, страница будет создана на корневом уровне. statusName: type: string description: Статус рабочего процесса страницы. title: type: string description: Название страницы. tocNodeCaption: type: string description: Пользовательское обозначение элемента Дерева страниц. Если не указано иное, то вместо этого используется название страницы. tocNodeOrdinalNo: type: integer description: Порядковый номер, указывающий на позицию страницы в Дереве страниц. Если не указано иное, страница будет создана на последней позиции на соответствующем уровне. indexKeywords: type: array items: type: string description: Массив строк, содержащих ключевые слова, которые необходимо использовать при создании страницы. responses: "201": description: Создано headers: Location: description: URL созданной страницы schema: type: string format: uri content: application/json: schema: $ref: "#/components/schemas/Topic" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{id}/articles/{topic-id}: get: operationId: getTopic summary: Получение страницы description: Получение информации об одной странице. tags: - Страницы parameters: - name: id in: path required: true description: Идентификатор проекта или публикации, из которой следует взять указанную страницу. schema: type: string - name: topic-id in: path required: true description: Идентификатор страницы, о которой необходимо получить информацию. schema: type: string - name: format in: query required: false description: "Формат поля `compiledContent` в ответе. Допустимые значения: `html`, `md`. по умолчанию: `html`." schema: type: string enum: - html - md example: "html" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Topic" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} delete: operationId: deleteTopic summary: Удаление страницы description: Удаление одной страницы из проекта или публикации. tags: - Страницы parameters: - name: id in: path required: true description: Идентификатор проекта или публикации, из которой необходимо удалить страницу. schema: type: string - name: topic-id in: path required: true description: Идентификатор страницы, которую необходимо удалить. schema: type: string responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/articles/{topic-id}: patch: operationId: updateTopic summary: Обновление страницы description: Обновление контента страницы и/или метаданных. tags: - Страницы parameters: - name: project-id in: path required: true description: Идентификатор проекта, в котором необходимо обновить страницу. schema: type: string - name: topic-id in: path required: true description: Идентификатор страницы, которую необходимо обновить. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - updatedFields properties: assigneeUserName: type: string description: Логин исполнителя, которому назначена страница. body: type: string description: HTML-контент страницы. ownerUserName: type: string description: Логин владельца страницы. statusName: type: string description: Статус рабочего процесса по странице. title: type: string description: Название страницы. indexKeywords: type: array items: type: string description: Массив строк, содержащих ключевые слова, которые необходимо использовать при обновлении страницы. updatedFields: type: string description: Разделенный запятыми список полей, которые подлежат обновлению. Если имя поля отсутствует в списке, то оно не будет обновлено, даже если значение поля указано в других параметрах запроса. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Topic" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" # ────────────────────────────────────────────── # TOC Nodes # ────────────────────────────────────────────── /projects/{project-id}/toc/nodes: post: operationId: createTocNodeFolder summary: Создание элемента Дерева страниц (папки) description: Создание папки в Дереве страниц проекта. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request POST 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes' \ --data-raw '{ "caption": "Новая папка", "isShowInToc": true, "ordinalNo": 0, "parentId": "0e7adad0-2572-4966-8f02-bc46930cf848" }' requestBody: required: true content: application/json: schema: type: object required: - caption properties: caption: type: string description: Имя папки. example: "Новая папка" isShowInToc: type: boolean default: false description: "Определяет, нужно ли отображать папку в Дереве страниц в публикациях. Устанавливает соответствующий параметр в свойствах страницы. Условие `false` (ложно) по умолчанию." example: true ordinalNo: type: integer description: "Положение элемента в Дереве страниц. Если параметр не отправлен, элемент отобразится в конце." example: 0 parentId: type: string nullable: true description: "Уникальный идентификатор родительского элемента Дерева страниц. При отправке `null` или отказе от отправки параметра элемент будет создан на корневом уровне." example: "0e7adad0-2572-4966-8f02-bc46930cf848" parameters: - name: project-id in: path required: true description: Идентификатор проекта, в котором будет создана папка. schema: type: string responses: "201": description: Создано headers: Location: description: URL созданной папки schema: type: string format: uri content: application/json: schema: type: object properties: caption: type: string description: "Пользовательское имя папки установленное в свойствах страницы. Пусто, если используется название папки." id: type: string description: "Уникальный идентификатор элемента Дерева страниц. " isAutoDocsMountPoint: type: boolean description: "Является ли страница mount point API документации." isShowInToc: type: boolean description: "Определяет, нужно ли отображать папку в Дереве страниц в публикациях. По умолчанию устанавливается false (ложно)." ordinalNo: type: integer description: "Положение элемента в Дереве страниц." parentId: type: string nullable: true description: "Уникальный идентификатор родительского элемента Дерева страниц. При значении null элемент находится на корневом уровне." topicId: type: string description: "Уникальный идентификатор страницы, связанный с элементом Дерева страниц." topicTitle: type: ["string", "null"] description: Название страницы, связанной с элементом дерева страниц или null, если нет связанного элемента. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" get: operationId: getSeveralTocNodes summary: Получение нескольких элементов Дерева страниц description: Получение информации обо всех элементах Дерева страниц в рамках проекта. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request GET 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes' parameters: - name: project-id in: path required: true description: Идентификатор проекта, для которого нужно получить список элементов Дерева страниц. schema: type: string example: "project-deep-space-exploration" - name: isRootNodesOnly in: query required: false description: Если `true`, возвращает только элементы дерева страниц на корневом уровне. По умолчанию `false`. schema: type: boolean default: false responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: caption: type: string description: Пользовательское обозначение элемента Дерева страниц, заданное в свойствах страницы. Пусто, если используется заголовок страницы. example: "" id: type: string description: Уникальный идентификатор элемента Дерева страниц. example: "0e7adad0-2572-4966-8f02-bc46930cf848" isAutoDocsMountPoint: type: boolean description: Является ли страница mount point API документации. example: false isShowInToc: type: boolean description: Показывает, отображается ли элемент в Дереве страниц в публикациях. Определяет соответствующий параметр в свойствах страницы. example: true ordinalNo: type: integer description: Число, обозначающее положение элемента в Дереве страниц. example: 1 parentId: type: string nullable: true description: Уникальный идентификатор родительского элемента Дерева страниц. `null`, если элемент находится на корневом уровне. example: null topicId: type: string description: Уникальный идентификатор страницы, связанный с элементом Дерева страниц. example: "outer-space" topicTitle: type: ["string", "null"] description: Название страницы, связанной с элементом дерева страниц или null, если нет связанного элемента. example: "Outer Space" example: - caption: "" id: "0e7adad0-2572-4966-8f02-bc46930cf848" isAutoDocsMountPoint: false isShowInToc: true ordinalNo: 1 parentId: null topicId: "outer-space" topicTitle: "Outer Space" - caption: "" id: "928d32c6-579b-4e98-a79e-aae03f12f1b5" isAutoDocsMountPoint: false isShowInToc: true ordinalNo: 2 parentId: null topicId: "astronomical-object" topicTitle: "Astronomical Object" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} delete: operationId: deleteTocNodes summary: Удаление нескольких элементов Дерева страниц description: Удаление из проекта нескольких элементов Дерева страниц вместе со связанными страницами. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request DELETE 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes' \ --data-raw '{ "tocNodeIds": [ "9b874ccc-0e0d-470e-839a-73f966b53662", "c487c94e-f5c0-4c2d-a9ce-243bd77d1873" ] }' requestBody: required: true content: application/json: schema: type: object properties: tocNodeIds: type: object description: Объект, состоящий из строк идентификаторов элементов Дерева страниц. example: - "9b874ccc-0e0d-470e-839a-73f966b53662" - "c487c94e-f5c0-4c2d-a9ce-243bd77d1873" example: tocNodeIds: - "9b874ccc-0e0d-470e-839a-73f966b53662" - "c487c94e-f5c0-4c2d-a9ce-243bd77d1873" parameters: - name: project-id in: path required: true description: Идентификатор проекта, из которого необходимо удалить указанные элементы Дерева страниц. schema: type: string responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/toc/nodes/{node-id}: get: operationId: getTocNode summary: Получение элемента Дерева страниц description: Получение информации об одном элементе Дерева страниц. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request GET 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes/0e7adad0-2572-4966-8f02-bc46930cf848' parameters: - name: project-id in: path required: true description: Идентификатор проекта, из которого необходимо получить указанный элемент Дерева страниц. schema: type: string example: "project-deep-space-exploration" - name: node-id in: path required: true description: Идентификатор элемента Дерева страниц для получения информации. schema: type: string example: "0e7adad0-2572-4966-8f02-bc46930cf848" responses: "200": description: OK content: application/json: schema: type: object properties: caption: type: string description: Пользовательское обозначение элемента Дерева страниц, заданное в свойствах страницы. Пусто, если используется заголовок страницы. example: "" id: type: string description: Уникальный идентификатор элемента Дерева страниц. example: "0e7adad0-2572-4966-8f02-bc46930cf848" isAutoDocsMountPoint: type: boolean description: Является ли страница mount point API документации. example: false isShowInToc: type: boolean description: Показывает, отображается ли элемент в Дереве страниц в публикациях. Определяет соответствующий параметр в свойствах страницы. example: true ordinalNo: type: integer description: Число, обозначающее положение элемента в Дереве страниц. example: 1 parentId: type: string nullable: true description: Уникальный идентификатор родительского элемента Дерева страниц. `null`, если элемент находится на корневом уровне. example: null topicId: type: string description: Уникальный идентификатор страницы, связанный с элементом Дерева страниц. example: "outer-space" topicTitle: type: ["string", "null"] description: Название страницы, связанной с элементом дерева страниц или null, если нет связанного элемента. example: "Outer Space" example: caption: "" id: "0e7adad0-2572-4966-8f02-bc46930cf848" isAutoDocsMountPoint: false isShowInToc: true ordinalNo: 1 parentId: null topicId: "outer-space" topicTitle: "Outer Space" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} patch: operationId: updateTocNode summary: Обновление элемента Дерева страниц description: Обновление метаданных элементов Дерева страниц. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request PATCH 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes/0e7adad0-2572-4966-8f02-bc46930cf848' \ --data-raw '{ "caption":"", "isShowInToc":true, "ordinalNo":2, "parentId":null, "updatedFields":"parentId, caption, ordinalNo, isShowInToc" }' requestBody: required: true content: application/json: schema: type: object required: - caption - updatedFields properties: caption: type: string description: Обозначение элемента Дерева страниц. example: "" isShowInToc: type: boolean default: false description: "Определяет, нужно ли отображать папку в Дереве страниц в публикациях. Устанавливает соответствующий параметр в свойствах страницы. Условие `false` (ложно) по умолчанию." example: true ordinalNo: type: integer description: "Положение элемента в Дереве страниц. Если параметр не отправлен, элемент отобразится в конце." example: 2 parentId: type: string nullable: true description: "Уникальный идентификатор родительского элемента Дерева страниц. При отправке `null` или отказе от отправки параметра элемент будет создан на корневом уровне." example: null updatedFields: type: string description: "Разделенный запятыми список полей, которые подлежат обновлению. Если имя поля отсутствует в списке, то оно не будет обновлено, даже если значение поля указано в других параметрах запроса." example: "parentId, caption, ordinalNo, isShowInToc" example: caption: "" isShowInToc: true ordinalNo: 2 parentId: null updatedFields: "parentId, caption, ordinalNo, isShowInToc" parameters: - name: project-id in: path required: true description: Идентификатор проекта для обновления указанного элемента Дерева страниц. schema: type: string - name: node-id in: path required: true description: Идентификатор элемента Дерева страниц, который подлежит обновлению. schema: type: string responses: "200": description: OK content: application/json: schema: type: object properties: caption: type: string description: "Пользовательское обозначение элемента Дерева страниц, заданное в свойствах страницы. Пусто, если используется заголовок страницы." example: "" id: type: string description: "Уникальный идентификатор элемента Дерева страниц." example: "0e7adad0-2572-4966-8f02-bc46930cf848" isAutoDocsMountPoint: type: boolean description: "Является ли страница mount point API документации." example: false isShowInToc: type: boolean description: "Показывает, отображается ли элемент в Дереве страниц в публикациях. Определяет соответствующий параметр в свойствах страницы." example: true ordinalNo: type: integer description: "Число, обозначающее положение элемента в Дереве страниц." example: 2 parentId: type: string nullable: true description: "Уникальный идентификатор родительского элемента Дерева страниц. `null`, если элемент находится на корневом уровне." example: null topicId: type: string description: "Уникальный идентификатор страницы, связанный с элементом Дерева страниц." example: "history-of-space-exploration" topicTitle: type: ["string", "null"] description: Название страницы, связанной с элементом дерева страниц или null, если нет связанного элемента. example: "History of Space Exploration" example: caption: "" id: "0e7adad0-2572-4966-8f02-bc46930cf848" isAutoDocsMountPoint: false isShowInToc: true ordinalNo: 2 parentId: null topicId: "history-of-space-exploration" topicTitle: "History of Space Exploration" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: operationId: deleteTocNode summary: Удаление элемента Дерева страниц description: Удаление из проекта одного элемента Дерева страниц вместе со связанной с ним страницей. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request DELETE 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes/0e7adad0-2572-4966-8f02-bc46930cf848' parameters: - name: project-id in: path required: true description: Идентификатор проекта, из которого необходимо удалить указанный элемент Дерева страниц. schema: type: string example: "project-deep-space-exploration" - name: node-id in: path required: true description: Идентификатор элемента Дерева страниц, который подлежит удалению. schema: type: string example: "0e7adad0-2572-4966-8f02-bc46930cf848" responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /projects/{project-id}/toc/nodes/{toc-node-id}/children: get: operationId: getChildTocNodes summary: Получение дочерних элементов Дерева страниц description: Получение списка дочерних элементов Дерева страниц. tags: - Элементы Дерева страниц x-codeSamples: - lang: curl source: | curl --location -g --request GET 'https://{portal-url}/api/v2/projects/project-deep-space-exploration/toc/nodes/0e7adad0-2572-4966-8f02-bc46930cf848/children?isRecursive=true' parameters: - name: project-id in: path required: true description: Идентификатор проекта, из которого нужно получить дочерние элементы. schema: type: string - name: toc-node-id in: path required: true description: Идентификатор элемента Дерева страниц, дочерние элементы которого необходимо получить. schema: type: string - name: isRecursive in: query required: false description: "Определяет, нужно ли получать информацию и обо всех дочерних элементах. Условие `false` (ложно) по умолчанию." schema: type: boolean default: false responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: caption: type: string description: "Пользовательское обозначение элемента Дерева страниц, заданное в свойствах страницы. Пусто, если используется заголовок страницы." id: type: string description: "Уникальный идентификатор элемента Дерева страниц." example: "69fc2771-20ef-496a-8141-b8fe38e0fac4" isAutoDocsMountPoint: type: boolean description: "Является ли страница mount point API документации." example: false isShowInToc: type: boolean description: "Показывает, отображается ли элемент в Дереве страниц в публикациях. Определяет соответствующий параметр в свойствах страницы." example: true ordinalNo: type: integer description: "Число, обозначающее положение элемента в Дереве страниц." example: 0 parentId: type: string nullable: true description: "Уникальный идентификатор родительского элемента Дерева страниц. null, если элемент находится на корневом уровне." example: "928d32c6-579b-4e98-a79e-aae03f12f1b5" topicId: type: string description: "Уникальный идентификатор страницы, связанный с элементом Дерева страниц." example: "planetary-system" topicTitle: type: ["string", "null"] description: Название страницы, связанной с элементом дерева страниц или null, если нет связанного элемента. example: "Planetary System" example: - caption: "" id: "69fc2771-20ef-496a-8141-b8fe38e0fac4" isAutoDocsMountPoint: false isShowInToc: true ordinalNo: 0 parentId: "928d32c6-579b-4e98-a79e-aae03f12f1b5" topicId: "planetary-system" topicTitle: "Planetary System" - caption: "" id: "42914509-ee9b-4b95-9c25-0334419f86db" isAutoDocsMountPoint: false isShowInToc: true ordinalNo: 1 parentId: "928d32c6-579b-4e98-a79e-aae03f12f1b5" topicId: "star-cluster" topicTitle: "Star Cluster" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} # ────────────────────────────────────────────── # Reporting & Analytics # ────────────────────────────────────────────── /reports/user-events/{user-login}/articles: get: operationId: getTopicViews summary: Получение просмотров страницы description: Получение информации о страницах, просмотренных анонимными пользователями или конкретным авторизованным читателем. tags: - Отчеты и аналитика x-codeSamples: - lang: curl source: | curl --location -g --request GET 'https://{portal-url}/api/v2/reports/user-events/pr1/articles?startDate=2022-08-09T02:35:00&endDate=2022-12-31T02:35:00' parameters: - name: user-login in: path required: true description: Логин авторизованного читателя для получения информации о просмотренных им страницах. Для получения данных по анонимным пользователям вместо логина используйте `-` . schema: type: string example: pr1 - name: startDate in: query required: true description: Временная метка ISO 8601 даты начала диапазона отчета. Часовой пояс GMT. schema: type: string example: "2022-08-09T02:35:00" - name: endDate in: query required: true description: Временная метка ISO 8601 даты окончания диапазона отчета. Часовой пояс GMT. schema: type: string example: "2022-12-31T02:35:00" responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: actionType: type: string description: | Тип действия, примененного к странице. Это может быть один из следующих вариантов: - DirectNavigation (непосредственная навигация) — навигация по щелчкам на ссылках. - FromToc (через Дерево страниц) — страница была открыта щелчком мыши по элементу Дерева страниц. - FromIndex (по ключевому слову) — страница была открыта по щелчку на ключевом слове. - FromSearch (через поиск) — страница была открыта из результатов поиска. - FromContextHelp (через контекстную справку) — страница была загружена в виде сниппета контекстной справки. dateTime: type: string format: date-time description: Временная метка события по стандарту ISO 8601. Часовой пояс GMT. href: type: string description: URL, по которому можно получить подробную информацию о просматриваемой пользователем странице. referrerUrl: type: string description: URL страницы, с которой пользователь перешел к новой странице. example: - actionType: DirectNavigation dateTime: "2025-02-15T10:20:30Z" href: "/api/v2/projects/deep-space-exploration/articles/basic-functionality" referrerUrl: "https://docs.hedronlabs.org/articles/" - actionType: FromToc dateTime: "2025-05-10T14:45:00Z" href: "/api/v2/projects/deep-space-exploration/articles/advanced-functionality" referrerUrl: "https://docs.hedronlabs.org/articles/toc" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] /reports/user-events/{user-login}/search-queries: get: operationId: getSearchQueries summary: Получение поисковых запросов description: Получение информации о поисковых запросах анонимных пользователей или конкретного авторизованного читателя. tags: - Отчеты и аналитика x-codeSamples: - lang: curl source: | curl --location -g --request GET 'https://{portal-url}/api/v2/reports/user-events/pr1/search-queries?startDate=2022-08-09T02:35:00&endDate=2022-12-31T02:35:00&projectId=project-deep-space-exploration' \ --header 'Authorization: Basic ' parameters: - name: user-login in: path required: true description: Логин авторизованного читателя для получения поисковых запросов. Для получения данных по анонимным пользователям вместо логина используйте `-` . schema: type: string example: "pr1" - name: startDate in: query required: true description: Временная метка ISO 8601 даты начала диапазона отчета. Часовой пояс GMT. schema: type: string example: "2022-11-07T15:25:00" - name: endDate in: query required: true description: Временная метка ISO 8601 даты окончания диапазона отчета. Часовой пояс GMT. schema: type: string example: "2022-11-07T15:30:00" - name: projectId in: query required: false description: Идентификатор публикации, по которой необходимо получить статистику поисковых запросов. schema: type: string example: "deep-space-exploration-publication" responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: dateTime: type: string format: date-time description: Временная метка события по стандарту ISO 8601. Часовой пояс GMT. example: "2022-11-07T15:25:34" queryText: type: string description: Полнотекстовый поисковый запрос. example: "click" resultsTotal: type: integer description: Общее количество полученных результатов поиска. example: 5 projectId: type: string description: Идентификатор публикации, по которой проводился поиск. example: "deep-space-exploration-publication" example: - dateTime: "2022-11-07T15:25:34" queryText: "click" resultsTotal: 5 projectId: "deep-space-exploration-publication" - dateTime: "2022-11-07T15:25:27" queryText: "nebula" resultsTotal: 0 projectId: "deep-space-exploration-publication" - dateTime: "2022-11-07T15:25:22" queryText: "some" resultsTotal: 0 projectId: "deep-space-exploration-publication" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] # ────────────────────────────────────────────── # Search # ────────────────────────────────────────────── /search: get: operationId: searchThePortal summary: Поиск по порталу description: Выдает результаты полнотекстового поискового запроса. Проекты/публикации, закрытые для пользователя, отправившего запрос, будут пропущены. Для неавторизованных пользователей выдаются результаты только из открытых публикаций. tags: - Поиск x-codeSamples: - lang: curl source: | curl --location -g --request GET 'https://{portal-url}/api/v2/search?count=2&projectIds=project-deep-space-exploration,space-program-pub&lang=en-us&isReturnSnippets=true&q=nebula' parameters: - name: q in: query required: true description: Полнотекстовый поисковый запрос. Может содержать любые [поддерживаемые операторы поиска](https://docs.documenterra.ru/articles/manual/polnotekstovyy-poisk-podderzhivayemyye-operatory-poiska/). schema: type: string example: "nebula" - name: count in: query required: false description: Максимальное количество выдаваемых результатов. Если не указано, то выдается 10 лучших результатов. Если указано отрицательное число, то выдаются все результаты поиска независимо от их общего количества. schema: type: integer example: 2 - name: projectIds in: query required: false description: Разделенный запятыми список идентификаторов проектов/публикаций для поиска. Идентификаторы проектов/публикаций, к которым у вас нет доступа, будут игнорироваться. schema: type: string example: "project-deep-space-exploration,space-program-pub" - name: lang in: query required: false description: Четырехбуквенный код языка. Если указано, то поиск ведется только по проектам/публикациям на этом языке. schema: type: string example: "en-us" - name: isReturnSnippets in: query required: false description: Если условие верное, то в теле ответа выдаются `ftsTitle` и `ftsSnippet`. schema: type: boolean example: true - name: format in: query required: false description: "Формат поля `compiledContent` в ответе. Допустимые значения: `html`, `md`. По умолчанию: `html`." schema: type: string enum: - html - md example: "html" responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: assigneeUserName: type: string description: Логин исполнителя, которому назначена страница. example: "admin" body: type: string nullable: true description: Содержание тега страницы. Возвращает значение null для всех способов, кроме [Получение страницы](https://docs.documenterra.ru/articles/manual/poluchenie-stranitsy). example: null compiledContent: type: string nullable: true description: Контент страницы в формате указанном с помощью параметра`format`. Возвращает `null` для всех методов кроме Получение страницы. example: null compiledContentType: type: string nullable: true description: Формат поля `compiledContent`. Допустимые значения `html` и `md`. enum: - html - md createdOn: type: string format: date-time description: Временная метка ISO 8601 даты создания страницы. Часовой пояс GMT. example: "2021-05-10T12:32:25" ftsSnippet: type: string nullable: true description: Выделена HTML-разметка заголовка страницы с совпадениями с полнотекстовым поисковым запросом. Заполняется только в том случае, если `isReturnSnippets = true`. example: "...A nebula ..." ftsTitle: type: string nullable: true description: HTML-разметка сниппета контента страницы с выделенными соответствиями полнотекстовому поисковому запросу. Заполняется только в том случае, если `isReturnSnippets = true`. example: "New topic created with API" fullUrl: type: string description: Полный URL-адрес страницы. example: "https://docs.hedron.org/articles/project-deep-space-exploration/nebula" id: type: string description: Идентификатор страницы. example: "nebula" indexKeywords: type: array items: type: string description: Массив строк, содержащих ключевые слова, связанные со страницей. Иерархические ключевые слова представляются в виде значений, разделенных запятыми. example: ["cluster", "N", "nebula"] modifiedOn: type: string format: date-time description: Временная метка ISO 8601 даты изменения страницы. Часовой пояс GMT. example: "2022-11-07T12:59:40" ownerUserName: type: string description: Логин владельца страницы. example: "admin" projectId: type: string description: Уникальный идентификатор проекта или публикации. example: "project-deep-space-exploration" projectTitle: type: string description: Название проекта или публикации, к которой относится данная страница. example: "Project Deep Space Exploration" statusName: type: string description: Статус рабочего процесса страницы. example: null title: type: string description: Название страницы. example: "New topic created with API" tocNodeId: type: string description: Идентификатор элемента Дерева страниц, связанный со страницей. example: "cd1ad87f-55a4-46e5-b496-c3434d555cd1" isAutoTopic: type: boolean description: Возвращает `true`, если страница является автоматически созданной страницей. example: false example: - assigneeUserName: "admin" compiledContent: null compiledContentType: null createdOn: "2021-05-10T12:32:25" ftsSnippet: "...A nebula ( Latin for 'cloud' or 'fog'...) is an interstellar cloud of dust, hydrogen, helium and other ionized gases..." ftsTitle: "New topic created with API" fullUrl: "https://docs.hedron.org/articles/project-deep-space-exploration/nebula" id: "nebula" indexKeywords: ["cluster", "N", "nebula", "N, nebula"] modifiedOn: "2022-11-07T12:59:40" ownerUserName: "admin" projectId: "project-deep-space-exploration" projectTitle: "Project Deep Space Exploration" statusName: null title: "New topic created with API" tocNodeId: "cd1ad87f-55a4-46e5-b496-c3434d555cd1" isAutoTopic: false - assigneeUserName: "admin" compiledContent: null compiledContentType: null createdOn: "2022-10-25T13:32:19" ftsSnippet: "...A nebula ( Latin for 'cloud' or 'fog'...) is an interstellar cloud of dust, hydrogen, helium and other ionized gases..." ftsTitle: "Nebula" fullUrl: "https://docs.hedron.org/articles/space-program-pub/nebula" id: "nebula" indexKeywords: [] modifiedOn: "2022-10-25T13:32:27" ownerUserName: "admin" projectId: "space-program-pub" projectTitle: "Space Program Pub" statusName: null title: "Nebula" tocNodeId: "cd1ad87f-55a4-46e5-b496-c3434d555cd1" isAutoTopic: false "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" security: - basicAuth: [] - {} # ────────────────────────────────────────────── # Storage # ────────────────────────────────────────────── /storage/{filePath}: get: operationId: getFiles summary: Получение файла(ов) или папки. description: | Получение информации об одном файле, папке или о нескольких файлах. **Сценарий 1: Получение файла** * Используйте `format=base64` если хотите скачать файл * **Не используйте** `filter` и `isRecursive`. **Сценарий 2: Получение информации о нескольких файлах** * Используйте `filter` для указания типа файлов, которые хотите получить (например, `*` для того чтобы получить все файлы, и `*.png` для изображений). * Используйте `isRecursive=true` если вы хотите включить информацию из подпапок. * **Не используйте** `format`. **Сценарий 3: Получение информации о папке** * **Не используйте** `format` и `filter`. tags: - Хранилище файлов x-codeSamples: - lang: bash source: | # Scenario 1: Get a Single File curl --location -g --request GET 'https://{portal-url}/api/v2/storage/project-deep-space-exploration/info.png?format=base64' # Scenario 2: Get Several Files curl --location -g --request GET 'https://{portal-url}/api/v2/storage/project-deep-space-exploration?filter=*&isRecursive=false' # Scenario 3: Get Folder Information curl --location -g --request GET 'https://{portal-url}/api/v2/storage/project-deep-space-exploration/images' parameters: - name: filePath in: path required: true description: | Путь к папке относительно корня, т.е. все, что после ... resources/Storage/. - Для **одного файла**, используйте полный путь и расширение. - Для **нескольких файлов** или **папки**, испольузуйте путь к папке. schema: type: string example: "project-deep-space-exploration" - name: format in: query required: false description: | **[Только для одного файла]** Допустимое значение: `base64`. Используйте для получение контента файла в ответе. Не используйте этот параметр для получения информации о нескольких файлах или папке. schema: type: string - name: filter in: query required: false description: | **[Только для получения информации о нескольких файлах]** Маска имени файла. Используйте `*` для получения всех файлов, или укажите расширение `*.png`. schema: type: string - name: isRecursive in: query required: false description: | **[Только для получения информации о нескольких файлах]** Определяет, следует ли рекурсивно выдавать все папки и содержащиеся в них файлы, т. е. извлекать все вложенные папки. По умолчанию значение false (ложно). schema: type: boolean responses: "200": description: ОК. content: application/json: schema: oneOf: - $ref: "#/components/schemas/StorageItem" - type: array items: $ref: "#/components/schemas/StorageItem" examples: GetFileResponse: summary: Get File (format=base64) value: fileName: "info.png" fileFullName: "Storage\\project-deep-space-exploration\\info.png" content: "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAQklEQVQ4y2P0av/xn4ECwMRAIcBrwNYKdoatFey0dQELPknvjp/kG4DsdHwGMVFiO+1jYdQACg1ATgf4kjPLgKcDAL8dECIPWD7kAAAAAElFTkSuQmCC" modifiedBy: "katherine" modifiedOn: "2021-04-07T15:50:15" size: 123 isFolder: false GetSeveralFilesResponse: summary: Get Several Files value: - fileName: "2b7f5b28-771e-46fc-9b60-427c6f6e10d9.gif" fileFullName: "Storage\\project-deep-space-exploration\\2b7f5b28-771e-46fc-9b60-427c6f6e10d9.gif" content: null modifiedBy: "jen" modifiedOn: "2022-05-06T08:16:29" size: 490 isFolder: false - fileName: "Artist_Concept_Planetary_System.jpg" fileFullName: "Storage\\project-deep-space-exploration\\Artist_Concept_Planetary_System.jpg" content: null modifiedBy: "admin" modifiedOn: "2022-09-27T12:45:57" size: 80801 isFolder: false GetFolderInfoResponse: summary: Get Folder Information value: fileName: "images" fileFullName: "Storage\\project-deep-space-exploration\\images" content: null modifiedBy: "admin" modifiedOn: "2024-01-15T12:00:00" size: 0 isFolder: true "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" patch: operationId: updateFile summary: Обновление файла description: Обновляет контент существующего файла. Максимальный размер файла, который вы можете загрузить через API, составляет 1 ГБ. tags: - Хранилище файлов parameters: - name: filePath in: path required: true description: Путь к файлу относительно корня, т.е. все, что после `... resources/Storage/`. schema: type: string example: "project-deep-space-exploration/info.png" requestBody: required: true content: application/json: schema: type: object properties: content: type: string description: Контент файла в кодировке Base64. updatedFields: type: string description: Разделенный запятыми список полей, которые подлежат обновлению. Если имя поля отсутствует в списке, то оно не будет обновлено, даже если значение поля указано в других параметрах запроса. examples: UpdateFileExample: summary: Update file content value: content: "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH5gsICiIy3F/ZtwAAC95JREFUeNrtm19QW9edxz/3CgkQIIGE+A82BjuAsWwgCAyecZ3a3pmknmy3k05eNrN1nLQznTYP7VM7s9uHTd8y2c2Dm8ZtdtpJk6k7bt02u6ETtnYTY/7IKIDcAAYRgWywwAgkAfqD7r37ANZyA8GORKymzm9GL+eec+7v9z2/c37f3+9cCYqiAOQAZ4DngL1AGn+fsgq4gNeBV4GgoChKDvAi8E1Al2oNHyAQrwI/TAO+tf7TplqrByha1hb8I0FRlGGgJtUapUiGBUVRojxcq79RYoKyfgo+rCKmWoFUyxcApFqBVEvKCE84HMbv96PRaMjLy0Oj0Tw8AEiSxG/On6e7uxudTsczzzxDY1PTwwOAoijcvHmT2dlZNBoNC4uLKTEeUngGiKKIIAjx30MFgCiKsMFoMYUAPNAtEAqFuDM3h3d2lgWfL77yozduYDKbsVgsWCwW0tIenFpJM8HFxUVcLhd1dXVkZmZu27ezs5Pzv/41oVCI1VgM1l8tCAKatDSKiop44YUXKC8v33ae6elp5u/cobauLmmwktoCCwsLnHvtNf7j5Zf5zfnzhMPh+LNoNEo0GlX137VrF7Isr7VvwF1RFCLhMGaTCYvFohoTCoXYuEaeqSl+cvYsL730Em//8Y9IkpQ6AAYHBujv7ycajdLR0cH58+cJh0JMut385OxZ3nvvPVX/yspKDh48yFZOp9PpaD9yhIyMjHhbOBzml7/4BRcvXmRlZQWPx8NPX3uN0dFRVlZW6OzsZG5uLikAkvKf/fX1NDQ04HA4kCSJP3V0MOv1cmt6Gs/UFH6/n/b29vjWSEtLo629HbvdrvIOWZbZvXs3VqtVNb/b7aa3t5dQKMToyAiBYJDxsTEEQSA9PZ3jx49jNpuTAiApD7BYLJw5c4bGpiYEQUCSJPr6+pi+dQuNRsPExATjY2OqMbW1tVRXVyPLcrxNEARaWlvJzc1V9bX39bG0tISiKDgcDlzj4wiCQEZGBv/0ta/xlVOn0GqTy+STDoPm/HyeffZZ9u7diyzLqvi+srJCb2+vyuX1ej2H29ri1FdRFCwWCzabTTXv/Pw8AwMD/6/ohnlPnDzJqVOndiRa7AgPWFlZYWl5eROhEQSBoaEhvF6vqr2xsZGSkhJkWUZRFBoaGigpKVH1cTqdzMzMrHGGDaIoCnNzc0QjkZ1QPXkAIpEIFy5cwDM1tSUAc3NzDA0NqdrNZjPN6yuenZ3N4bY21dhoNIq9r49YLLblO3t7erj8l7/8bQAQi8UoLi6moqICURTjq3pXJEnC3tenCpEArS0tGI1GHqmpobq6WvVscnKS0dFRFSiKoiDLMpmZmdTU1mIwGNiJYlbSmygrK4unn36aEydO4Bwaos9u58boKIFAAFjzgvHxcVwuF/v374+PK6+ooNlmY39dHTqduhp/zW4nEAggCAKyLKPRaCgoLOSg1YrNZqOquhq9Xp+08bADTPDjEo1GmXS7sV+7xgcOB9PT00QiEZ544gm+cfq0qq/X6yU7O5usrKx4m8/n48cvvojb7SbHYKC6qopmm42DVisFhYU7njh9pkVRn8/H9evX6enuJhgM8p3vfpeCgoJtx3R1dfHbCxeor6/H1tJCVVWVihzttCQMQDAYxOl0Ul1dfU+jotEoN2/eJC8vj7y8vG37Tk1Okp6efs/VjsViTExMsLy8zKFDhxL2jITPAI/Hw8/OncNoNNJss9Ha2kpFRcWWsVmn07Fnz577mrdi165tny8vLzM8PEzXlSsMDQ1RsWsXtbW1CXtJwgDMzMysxf+lJW397ndcvnQJq9VKW3s7NTU1O3ZI3ZW5uTk+cDi4evUqExMT8ahyZ26OgN9PRkZGPCp8Gm+4ry2wvLzMf7/9NgsLC3E25na7GV+nprAWphRFITMzk6rqatrb22loaMBkMiVstCRJTE1N0dPdjd1uZ2ZmBkmSVORIq9VitVrJyspCARRZ5oDVytGjR+/rHfflAV6vl46ODoKBQLySc5eaxpFcByYSiXDd6WT4ww8pKSmhra2N4ydOYDQaP5XxLpeLd955h6HBQfx+P4qiIIriJma4urqK3W6Pr74sy" updatedFields: "content" responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: operationId: uploadFile summary: Создание файла или папки / Начать возобновляемую загрузку description: | Создаёт файл или папку в хранилище. **Методы загрузки:** - **Загрузка Base64 (`format=base64`)**: Лучше всего для небольших файлов (<5 МБ). Посылает `application/json` тело со свойством `content`. - **Сздаёт папку (`format=base64`)**: Посылает `application/json` тело с `isFolder: true`. - **Загрузка Multipart/Form-Data (`format=multipart`)**: Лучше всего стандартной загрузки (≤10 МБ). Максимальный размер файла для загрузки - is 10 Мб. - **Возобновляемая загрузка Шаг 1 (`format=resumable`)**: Начинает чанковую загрузку для больших файлов. Тело запроса и тело ответа пустые. tags: - Хранилище файлов parameters: - name: filePath in: path required: true description: Путь к файлу или папке относительно корня, т.е. все, что после `...resources/Storage/`. schema: type: string example: "project-deep-space-exploration/info.png" - name: format in: query required: true description: Кодировка файла. schema: type: string enum: [base64, multipart, resumable] - name: isOverwrite in: query required: false description: Определяет, нужно ли перезаписывать существующий файл. Условие false (ложно) по умолчанию. schema: type: boolean default: false requestBody: required: false description: Тело запроса обязательно для форматов base64, multipart и должно быть пустым для возобновляемой загрузки. content: application/json: schema: type: object properties: content: type: string description: Контент файла в кодировке Base64. Только для format=base64. isFolder: type: boolean description: Определяет, создавать папку или файл. Если условие true (верно), контент игнорируется. Условие false (ложно) по умолчанию. default: false examples: Base64UploadExample: summary: Загрузка Base64 description: Загрузить format=base64 value: content: "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAQklEQVQ4y2P0av/xn4ECwMRAIcBrwNYKdoatFey0dQELPknvjp/kG4DsdHwGMVFiO+1jYdQACg1ATgf4kjPLgKcDAL8dECIPWD7kAAAAAElFTkSuQmCC" isFolder: false CreateFolderExample: summary: Создать пустую папку description: Создать пустую папку в хранилище value: isFolder: true ResumableUploadStep1Example: summary: Возобновляемая загрузка (Шаг 1) description: поле запроса должно быть пустым для format=resumable. value: {} multipart/form-data: schema: type: object properties: file: type: string format: binary description: Файл для загрузки. Только для format=multipart. responses: "201": description: Создано. Возвращает метаданные файлов для загрузки в формате base64 и multipart. Тело ответа пустое для формата format=resumable. content: application/json: schema: $ref: "#/components/schemas/StorageItem" examples: Base64ResponseExample: summary: Response for Base64 (Small file) value: content: null fileFullName: "Storage\\info.png" fileName: "info.png" isFolder: false modifiedBy: "admin" modifiedOn: "2025-10-29T13:21:28" size: 123 MultipartResponseExample: summary: Response for Multipart (Medium file) value: content: null fileFullName: "Storage\\manual.docx" fileName: "manual.docx" isFolder: false modifiedBy: "admin" modifiedOn: "2025-10-29T13:21:28" size: 99849 ResumableResponseExample: summary: Response for Resumable Step 1 description: Response body is completely empty. value: {} "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: operationId: uploadResumableChunk summary: Загрузка частей файла (Возобновляемая загрузка Шаг 2) description: | Загрузка фрагментов – несколько запросов, каждый из которых отправляет часть файла. Фрагменты загружаются последовательно до полной передачи всего файла. Максимальный размер одного фрагмента — 10 МБ. **Примеры:** **Загрузка первого фрагмента:** ```bash curl --location -g --request PUT 'https://{portal-url}/api/v2/storage/file.zip?format=resumable' \ --header 'Content-Range: bytes 0-10485759/52428800' \ --data-binary @chunk1.bin ``` **Загрузка последнего фрагмента:** ```bash curl --location -g --request PUT 'https://{portal-url}/api/v2/storage/file.zip?format=resumable' \ --header 'Content-Range: bytes 41943040-52428799/52428800' \ --data-binary @last_chunk.bin ``` tags: - Хранилище файлов parameters: - name: filePath in: path required: true description: Тот же путь, что был указан при инициализации загрузки на Шаге 1. schema: type: string example: "file.zip" - name: format in: query required: true description: Должно быть 'resumable'. schema: type: string enum: [resumable] - name: Content-Range in: header required: true description: "Указывает диапазон байтов текущей части и общий размер файла. Формат: bytes {начало}-{конец}/{общий-размер} или bytes {начало}-{конец}/* (когда общий размер неизвестен). Значение {начало} должно быть равно последнему успешно загруженному байту + 1. Для финальной части {конец} + 1 должно равняться {общий-размер}. Размер одной части ограничен 10 МБ. Пример: bytes 0-10485759/52428800." schema: type: string examples: FirstChunk: summary: Загрузка первого фрагмента value: "bytes 0-10485759/52428800" LastChunk: summary: Загрузка последнего фрагмента value: "bytes 41943040-52428799/52428800" requestBody: required: true description: Тело запроса содержит сырые байты части файла (бинарные данные). content: application/octet-stream: schema: type: string format: binary responses: "201": description: Последний ответ. Последний фрагмен был загружен и взагрузка всего файла прошла успешно. content: application/json: schema: $ref: "#/components/schemas/StorageItem" examples: ResumableFinalResponse: summary: Final response (Large file) value: content: null fileFullName: "Storage\\file.zip" fileName: "file.zip" isFolder: false modifiedBy: "admin" modifiedOn: "2025-10-31T09:45:00" size: 52428800 "202": description: Промежуточный ответ. Фрагмент был успешно получен, но загрузка ещё не завершена. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" head: operationId: checkFileExists summary: Проверка наличия файла или папки description: Получение информации о наличии файла или папки. tags: - Хранилище файлов parameters: - name: filePath in: path required: true description: Путь к файлу относительно корня, т.е. все, что после `...resources/Storage/`. schema: type: string example: "project-deep-space-exploration/info.png" responses: "200": description: Файл существует. "404": description: Файл не найден. delete: operationId: deleteFile summary: Удаление файла description: Удаление одного файла. tags: - Хранилище файлов parameters: - name: filePath in: path required: true description: Путь к файлу относительно корня, т.е. все, что после `...resources/Storage/`. schema: type: string example: "project-deep-space-exploration/info.png" responses: "204": description: Файл успешно удален (без тела ответа) "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /storage: delete: operationId: deleteFiles summary: Удаление нескольких файлов. description: Удаление нескольких файлов tags: - Хранилище файлов requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeleteFilesRequest" responses: "204": description: Файлы успешно удалены (без тела ответа) "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" # ────────────────────────────────────────────── # Users # ────────────────────────────────────────────── /users: post: operationId: createUser summary: Создание учетной записи пользователя description: Создание новой учетной записи пользователя. tags: - Пользователи requestBody: required: true content: application/json: schema: type: object required: - userName - userInfo properties: userName: type: string description: Логин авторизованного читателя. userInfo: type: object description: Объект, содержащий основную информацию о профиле. required: - email properties: email: type: string description: Электронная почта авторизованного читателя. firstName: type: string description: Имя авторизованного читателя. middleName: type: string description: Второе имя авторизованного читателя. lastName: type: string description: Фамилия авторизованного читателя. isPasswordChangeRequired: type: boolean description: "Перенаправлять ли пользователя на страницу смены пароля при первом входе в систему. По умолчанию — `false`." userRole: type: string description: "Если userType — Contributor, указывается роль пользователя: Reviewer, Translator, Administrator и т. д. Если пользователь является участником программы Power Reader или Reviewer, указывается список групп доступа Power Reader или Reviewer, разделенных запятыми, которые следует назначить этому пользователю." userType: type: string description: "Тип пользователя – Contributor (Автор) или PowerReader (Авторизованный читатель), по умолчанию." isDontSendEmail: type: boolean description: Посылать ли email пользователю, когда создаётся аккаунт. responses: "201": description: Создано content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" get: operationId: getUsers summary: Получение профилей пользователей description: Выдает информацию о пользователях портала. tags: - Пользователи responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /users/{user-login}: patch: operationId: changeUserProfile summary: Изменить профиль пользователя description: "Обновление информации профиля пользователя." tags: - Пользователи parameters: - name: user-login in: path required: true description: Логин пользователя, чей профиль нужно обновить. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - updatedFields properties: updatedFields: type: string description: Разделенный запятыми список полей, которые подлежат обновлению. Если имя поля отсутствует в списке, то оно не будет обновлено, даже если значение поля указано в других параметрах запроса. email: type: string description: Электронная почта авторизованного читателя. userRole: type: string description: "Если userType — Contributor, указывается роль пользователя: Reviewer, Translator, Administrator и т. д. Если пользователь является участником программы Power Reader или Reviewer, указывается список групп доступа Power Reader или Reviewer, разделенных запятыми, которые следует назначить этому пользователю." userType: type: string description: "Тип пользователя – Contributor (Автор) или PowerReader (Авторизованный читатель)" isEnabled: type: boolean description: Активен аккаунт или нет. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" get: operationId: getUserProfile summary: Получение профиля пользователя description: Выдает информацию о пользователе. tags: - Пользователи parameters: - name: user-login in: path required: true description: Логин авторизованного читателя для получения информации о нем. schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /users/{user-login}/tokens: get: operationId: getLoginToken summary: Получение токена входа description: Получение токена входа для авторизованного читателя. Чтобы узнать больше о механизме входа с помощью токенов и о том, как использовать токены, обратитесь к Механизму входа с помощью токенов. tags: - Пользователи parameters: - name: user-login in: path required: true description: Логин пользователя, для которого требуется получить токен. schema: type: string - name: exp in: query required: false description: Временная метка ISO 8601 даты истечения срока действия токена. Часовой пояс GMT. Значение по умолчанию — 30 минут с текущего момента. schema: type: string - name: muse in: query required: false description: "Следует ли ограничить использование токена одним входом. Если условие true (верно), токен можно использовать неограниченное количество раз, пока не истечет срок его действия. По умолчанию значение false (ложно)." schema: type: boolean responses: "200": description: OK content: application/json: schema: type: object properties: expirationDate: type: string format: date-time description: Временная метка ISO 8601 даты истечения срока действия токена. Часовой пояс GMT. token: type: string description: Сгенерированный токен входа. userName: type: string description: Логин пользователя. isMultiUse: type: boolean description: Определяет, можно ли использовать токен несколько раз, т.е. не ограничивать токен первым использованием. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" # ────────────────────────────────────────────── # AnswerGenius # ────────────────────────────────────────────── /answergenius/ask: post: operationId: askAnswerGenius summary: Спросить ИИ Помощника description: Послать запрос ИИ Помощнику. tags: - ИИ Помощник parameters: - name: format in: query required: false description: "Формат поля `сontent` в ответе чата. Допустимые значения `html`, `md`. По умолчанию: `html`." schema: type: string enum: - html - md example: "html" requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: Запрос к ИИ Помощнику chatId: type: string description: ID определённого диалога с ИИ Помощником. Указание ID диалога добавляет дополнительный контекст. projectId: type: string description: ID приоритетной публикации для поиска ответа. responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: ID определённого диалога с ИИ Помощником. messages: type: array description: Ответ на запрос. items: type: object properties: content: type: string description: Контент ответа в формате указанном в параметре `format`. contentType: type: string description: "Формат поля `content`. Возможные значение `html` и `md`." enum: - html - md messageType: type: string description: "The type of the message, for example: Assistant." "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" security: - basicAuth: [] - {} # ────────────────────────────────────────────── # Workflow Statuses # ────────────────────────────────────────────── /workflow/statuses: get: operationId: getWorkflowStatuses summary: Получить статусы рабочего процесса description: возвращает список всех статусов рабочего процесса. tags: - Статусы рабочего процесса parameters: - name: isTranslation in: query required: false description: Если указано, фильтрует статусы по типу - являются ли они статусами рабочего процесса перевода. schema: type: boolean responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/WorkflowStatus" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: operationId: createWorkflowStatus summary: Создать статус рабочего процесса description: Создаёт новый статус рабочего процесса (только для обычных статусов, не переводных). tags: - Статусы рабочего процесса requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateWorkflowStatusParam" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/WorkflowStatus" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /workflow/statuses/{statusName}: get: operationId: getWorkflowStatus summary: Получить статус рабочего процесса description: Возвращает информацию о статусе рабочего процесса по имени. tags: - Статусы рабочего процесса parameters: - name: statusName in: path required: true description: Имя статуса рабочего процесса. schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/WorkflowStatus" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" patch: operationId: updateWorkflowStatus summary: Обновить статус рабочего процееса description: Обновляет существующий статус рабочего процесса (только обычный, не переводной). tags: - Статусы рабочего процесса parameters: - name: statusName in: path required: true description: Имя статуса рабочего процесса. schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateWorkflowStatusParam" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/WorkflowStatus" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: operationId: deleteWorkflowStatus summary: Удалить статус рабочего процесса description: Удаляет статус рабочего процесса по имени (только для обычных статусов, не переводных). tags: - Статусы рабочего процесса parameters: - name: statusName in: path required: true description: Имя статуса рабочего процесса для удаления. schema: type: string responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" # ────────────────────────────────────────────── # Workflow Transitions # ────────────────────────────────────────────── /workflow/transitions: get: operationId: getWorkflowTransitions summary: Получить переходы рабочего процесса description: Возвращает списко всех переходов рабочего процесса. tags: - Переходы рабочего процесса responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/WorkflowTransition" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" post: operationId: createWorkflowTransition summary: Создать переход рабочего процесса description: Создаёт новый переход рабочего процесса (только для обычных статусов, не переводных). tags: - Переходы рабочего процесса requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateWorkflowTransitionParam" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/WorkflowTransition" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /workflow/transitions/{transitionId}: delete: operationId: deleteWorkflowTransition summary: Удалить переход рабочего процесса description: Удаляет переход рабочего процесса по ID (только для обычных статусов, не переводных). tags: - Переходы рабочего процесса parameters: - name: transitionId in: path required: true description: Идентификатор перехода рабочего процесса для удаления. schema: type: string responses: "200": description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" components: schemas: ApiError: type: object properties: Message: type: string description: Детали исключения. ExceptionType: type: string description: Тип исключения. ExceptionDetail: type: ["string", "null"] description: Зарезервировано для использования в будущем. StackTrace: type: ["string", "null"] description: Зарезервировано для использования в будущем. AdditionalData: type: ["string", "object", "null"] description: Дополнительные детали исключения. TaskStatus: type: object properties: isSucceeded: type: boolean description: Определяет, успешно или нет выполнена задача. Если задача еще не завершена, выдается `null`. isWorking: type: boolean description: Определяет, находится ли задача в процессе выполнения. maxOverallProgress: type: string description: Максимальное значение прогресса выполнения данной задачи. overallProgress: type: string description: Текущий прогресс выполнения задачи. Вместе с `maxOverallProgress` может использоваться для расчета процента выполнения задачи. statusText: type: string description: Название текущего статуса задачи. taskName: type: string description: Название задачи. example: isSucceeded: true isWorking: false maxOverallProgress: 100 overallProgress: 100 statusText: Export finished. taskName: Exporting Publication ProjectInfo: type: object properties: createdOn: type: string description: Временная метка ISO 8601, отражающая дату создания проекта/публикации. Часовой пояс GMT. fullUrl: type: string description: Полный URL-адрес проекта или публикации. id: type: string description: Уникальный идентификатор проекта или публикации. parentId: type: string description: Уникальный идентификатор родительского элемента. Возвращает `null` для проектов. Для публикаций возвращается идентификатор связанного с ними проекта. title: type: string description: Название проекта или публикации. visibility: type: string description: Видимость проекта/публикации. Всегда возвращается значение Private для проектов. lang: type: string description: Четырехбуквенный код языка проекта или публикации (например, 'en-US', 'de-DE'). baseLangProjectId: type: ["string", "null"] description: Идентификатор базового проекта. Для непереводных проектов возвращает `null`. Для переводных проектов возвращает идентификатор связанного проекта на базовом языке. example: createdOn: 2024-05-17T20:21:51 fullUrl: https://docs.hedronlabs.org/articles/my-manual-publication id: my-manual-publication parentId: project-my-manual title: Публикация руководства visibility: Private lang: en-US baseLangProjectId: null ProjectsInfo: type: array items: $ref: "#/components/schemas/ProjectInfo" example: - createdOn: 2024-05-17T20:21:51 fullUrl: https://docs.hedronlabs.org/articles/my-manual-publication id: my-manual-publication parentId: project-my-manual title: My Manual Publication visibility: Private lang: en-US baseLangProjectId: null - createdOn: 2025-01-31T09:24:15 fullUrl: https://docs.hedronlabs.org/articles/pro id: pro parentId: project-my-manual title: Pro visibility: Restricted lang: de-DE baseLangProjectId: my-manual-publication Topic: type: object properties: assigneeUserName: type: string description: Логин исполнителя, которому назначена страница. body: type: string description: "Содержание тега страницы. Возвращает значение null для всех способов, кроме Получение страницы." createdOn: type: string format: date-time description: Временная метка ISO 8601 даты создания страницы. Часовой пояс GMT. compiledContent: type: string description: Контент страницы в формате указанном с помощью параметра `format`. Возвращает `null` для всех методов кроме Получение страницы. compiledContentType: type: string description: Формат поля `compiledContent`. Допустимые значения `html` и `md`. enum: - html - md ftsSnippet: type: string description: Выделена HTML-разметка заголовка страницы с совпадениями с полнотекстовым поисковым запросом. Заполняется только в том случае, если `isReturnSnippets = true`. ftsTitle: type: string description: HTML-разметка сниппета контента страницы с выделенными соответствиями полнотекстовому поисковому запросу. Заполняется только в том случае, если `isReturnSnippets = true`. fullUrl: type: string description: Полный URL-адрес страницы. id: type: string description: Идентификатор страницы. indexKeywords: type: array items: type: string description: Массив строк, содержащих ключевые слова, связанные со страницей. Иерархические ключевые слова представляются в виде значений, разделенных запятыми. modifiedOn: type: string format: date-time description: Временная метка ISO 8601 даты изменения страницы. Часовой пояс GMT. ownerUserName: type: string description: Логин владельца страницы. projectId: type: string description: Уникальный идентификатор проекта или публикации. projectTitle: type: string description: Название проекта или публикации, к которой относится данная страница. statusName: type: string description: Статус рабочего процесса страницы. title: type: string description: Название страницы. tocNodeId: type: string description: Идентификатор элемента Дерева страниц, связанный со страницей. isAutoTopic: type: boolean description: Возвращает `true`, если страница является автоматически созданной страницей. User: type: object properties: userInfo: type: object description: Объект, содержащий основную информацию о профиле. properties: about: type: string description: Информация, указанная пользователем в окне Информация. avatarImageUrl: type: string description: URL-адрес изображения, используемого в качестве аватара. cultureInfoId: type: string description: Четырехбуквенный языковой код авторизованного читателя. email: type: string description: Электронная почта пользователя. firstName: type: string description: Имя пользователя. isAutoDetectCultureInfo: type: boolean description: Определяет, выбирается ли язык автоматически. Условие false (ложно), если язык задается пользователем. isAutoDetectTimeZone: type: boolean description: Определяет, установлен ли режим автоматического определения часового пояса. lastActivityDate: type: string format: date-time description: Временная метка ISO 8601, отражающая дату последней активности пользователя. Часовой пояс GMT. lastName: type: string description: Фамилия пользователя. middleName: type: string description: Отчество пользователя. timeZoneId: type: string description: Идентификатор часового пояса, указанного пользователем. userName: type: string description: Логин пользователя. userType: type: string description: "Тип пользователя: Авторизованный читатель (PowerReader) или Автор (Contributor)" userRole: type: string description: Разделенный запятыми список групп доступа, к которым относится авторизованный читатель. isEnabled: type: boolean description: Определяет, активна ли учетная запись или нет. StorageItem: type: object properties: fileName: type: string description: Имя и расширение файла. example: "info.png" fileFullName: type: string description: Полное имя файла, включая основную папку Storage/. example: "Storage\\project-deep-space-exploration\\info.png" content: type: string nullable: true description: Контент файла в кодировке Base64. modifiedBy: type: string description: Логин пользователя, который последним изменял файл. example: "katherine" modifiedOn: type: string format: date-time description: Временная метка ISO 8601 даты изменения файла. Часовой пояс GMT. example: "2021-04-07T15:50:15" size: type: integer description: Размер файла в байтах. example: 123 isFolder: type: boolean description: Определяет, является ли объект файлом или папкой. example: false DeleteFilesRequest: type: object required: [fileFullNames] properties: fileFullNames: type: array description: Объект, состоящий из строк пути к файлу. Каждая строка должна начинаться с Storage/. items: type: string example: - "Storage/project-deep-space-exploration/test-folder/API methods.cs" - "Storage/project-deep-space-exploration/test-folder/API notes.md" WorkflowStatus: type: object properties: name: type: string description: Имя статуса рабочего процесса. color: type: ["integer", "null"] description: Цвет статуса рабочего процесса - integer. type: type: ["string", "null"] description: Тип статуса рабочего процесса. enum: [Draft, Review, Ready, Translation, null] isTranslationStatus: type: boolean description: Является ли статус статусом рабочего процесса перевода. description: type: ["string", "null"] description: Описание статуса рабочего процесса. CreateWorkflowStatusParam: type: object required: - name - type properties: name: type: string description: Имя статуса рабочего процесса. color: type: ["integer", "null"] description: Цвет статуса рабочего процесса - integer. type: type: string description: Тип статуса рабочего процесса. enum: [Draft, Review, Ready] description: type: ["string", "null"] description: Описание статуса рабочего процесса. UpdateWorkflowStatusParam: type: object properties: name: type: string description: Имя статуса рабочего процесса. color: type: ["integer", "null"] description: Цвет статуса рабочего процесса - integer. type: type: string description: Тип статуса рабочего процесса. enum: [Draft, Review, Ready, Translation] description: type: ["string", "null"] description: Описание статуса рабочего процесса. WorkflowTransition: type: object properties: id: type: integer description: Идентификатор перехода рабочего процесса. sourceStatusName: type: string description: Имя статуса рабочего процесса, из которого происходит переход. destinationStatusName: type: string description: Имя статуса рабочего процесса, в который происходит переход. CreateWorkflowTransitionParam: type: object required: - sourceStatusName - destinationStatusName properties: sourceStatusName: type: string description: Имя статуса рабочего процесса, из которого происходит переход. destinationStatusName: type: string description: Имя статуса рабочего процесса, в который происходит переход. ImportProjectBody: type: object properties: importFormat: type: string description: Формат импорта. enum: [ Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx, AutoDocs, ] inputFileContent: type: string description: Контент файла в формате base64. Требуется, если в качестве параметра запроса формата выбран base64. Если выбран формат url, этот параметр игнорируется. inputFileName: type: string description: Имя файла с расширением. Требуется, если в качестве параметра запроса формата выбран base64 . Если выбран формат url, этот параметр игнорируется. inputFileUrl: type: string description: URL-адрес файла. Это может быть публичный URL (не требующий аутентификации) или ссылка на файл в Хранилище файлов Документерры. Требуется, если в качестве параметра запроса формата выбран url. Если выбран формат base64, этот параметр игнорируется. newProjectId: type: string description: Идентификатор нового проекта, в который нужно импортировать спецификацию. Следует указать либо newProjectId, либо newProjectName. newProjectName: type: string description: Имя нового проекта, в который нужно импортировать спецификацию. Следует указать либо newProjectId, либо newProjectName. newProjectLanguageFourLetterCode: type: string description: Четырехбуквенный код языка нового проекта, в который нужно импортировать спецификацию. Если не указано, используется код en-US. options: type: object description: Дополнительные парамерты импорта. properties: __type: type: string description: Тип папаметров импорта. enum: [ AutoDocs, Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx, ] isDownloadExternalLinkedFiles: type: boolean description: Загружать ли файлы, на которые есть ссылки в документе. По умолчанию False. Доступно для форматов - Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx. isDownloadExternalLinkedImages: type: boolean description: Загружать ли изображения, на которые есть ссылки в документе. По умолчанию True. Доступно для форматов - Word, Rtf, Epub, Odt, Html, Markdown, ProjectBackup, Docfx. tocGenerationType: type: string description: Определяет, как импортируемый документ будет разбит на страницы. Допустимые значения для форматов Word, Rtf, Epub, Odt - UseStyleOutline, UseParagraphOutline, UseTcFields, ImportAsSingleTopic. По умолчанию UseStyleOutline. Допустимые значения для форматов Html и Markdown - UseParagraphOutline и ImportAsSingleTopic. По умолчанию ImportAsSingleTopic. maxTocOutlineLevel: type: string description: Максимальный уровень заголовков для импортируемого файла. По умолчанию 2. Доступно для форматов - Word, Rtf, Epub, Odt. stylesProcessingType: type: string description: Настройка обработки стилей Документеррой. Допустимые значения KeepPreciseStyles, OptimizeStyles, DoNotImportStyles. По умолчанию OptimizeStyles. Доступно для форматов Word, Rtf, Epub, Odt, Html, Markdown. imageFormat: type: string description: Желаемый формат изображений Png или Jpeg. По умолчанию Png. Доступно для форматов Word, Rtf, Epub, Odt. splitModeType: type: string description: Режим импорта для формата AutoDocs GroupMethods, SeparateTopics или SingleTopic. updatedMountPointTocNodeId: type: string description: Идентификатор mount point элемента дерева станиц, который нужно обновить. идентификатор соответсвуут tocNodeId, который можно получить с помощью метода Получение страницы. Если указано, все автоматически сгенерированные страницы будут обновлениы. Доступно для формата AutoDocs. requestBodies: DeleteProject: description: Удаляет проект или публикацию required: false content: application/json: schema: type: object properties: isDeleteFiles: type: boolean default: false isDeleteStyles: type: boolean default: false isDeleteScripts: type: boolean default: false responses: SuccessfulTask: description: OK content: application/json: schema: type: object properties: taskKey: type: string example: f8de60eb4ad8757c5a2b533afae6251aa ProjectDetails: description: OK content: application/json: schema: $ref: "#/components/schemas/ProjectsInfo" ProjectInfoResponse: description: OK content: application/json: schema: $ref: "#/components/schemas/ProjectInfo" TaskStatusResponse: description: OK content: application/json: schema: $ref: "#/components/schemas/TaskStatus" BadRequest: description: Ошибка валидации запроса content: application/json: schema: $ref: "#/components/schemas/ApiError" Unauthorized: description: Требуется авторизация content: application/json: schema: $ref: "#/components/schemas/ApiError" Forbidden: description: Доступ запрещен content: application/json: schema: $ref: "#/components/schemas/ApiError" NotFound: description: Ресурс не найден content: application/json: schema: $ref: "#/components/schemas/ApiError" securitySchemes: basicAuth: type: http scheme: basic description: Логин + API ключ (не пароль). [Получение ключа API](https://docs.documenterra.ru/articles/manual/polucheniye-klyucha-api). security: - basicAuth: []