Справка

База знаний

Облачный Pyrus

База знаний Pyrus предназначена для хранения документов и совместной работы над ними. Это упорядоченное хранилище информации и полноценный текстовый редактор в одном флаконе. В нём есть всё для совместного редактирования и комментирования документов в режиме онлайн.

Методы Public API для Базы знаний позволяют работать со статьями и темами в ней: читать, создавать, обновлять, удалять контент, получать дерево структуры и управлять правами доступа к материалам.

GET /knowledgebase/{id}

Получение статьи или темы по ID. Метод возвращает содержание статьи или темы в формате Markdown.

GET https://api.pyrus.com/v4/knowledgebase/{id}

Тело ответа

{
    "id": "OJHEAFQ26YT",
    "title": "Title",
    "type": "article",
    "body": "# Hello\n\n- one\n- two\n\n![image.png](https://files.pyrus.com/services/kb?Id=ab43bc19-079d-4ba2-94ad-e8b18f05a885)\n\n",
    "author": {
        "id": 1731,
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "Bob.Smith@gmail.com",
        "type": "user"
    },
    "parent_topic_id": "OJHEAFQ26YT",
    "created_at": "2026-01-10T12:34:56Z",
    "updated_at": "2026-01-22T09:15:00Z",
    "last_edited_by": {
        "id": 1731,
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "Bob.Smith@gmail.com",
        "type": "user"
    },
    "version": 4,
    "access_right": "write",
    "is_open_for_organization": true,
    "is_public": false,
	"attachments": [
		{
			"id": "ab43bc19-079d-4ba2-94ad-e8b18f05a885",
			"name": "image.png",
			"size": 13567,
			"url": "https://files.pyrus.com/services/kb?Id=ab43bc19-079d-4ba2-94ad-e8b18f05a885"
		}
	]
}

curl

curl -X GET 'https://api.pyrus.com/v4/knowledgebase/{id}' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

PUT /knowledgebase/{id}

Обновление контента статьи или параметров темы по ID.

PUT https://api.pyrus.com/v4/knowledgebase/{id}

Тело запроса

{
  "title": "Title",
  "body": "# Hello\n\n- one\n- two\n",
  "parent_topic_id": "TOPIC123",
  "parent_topic_id_changed": true
}

Тело ответа

{
  "id": "OJHEAFQ26YT",
  "title": "Title",
  "type": "article",
  "body": "# Hello\n\n- one\n- two\n",
  "author": {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com",
      "type": "user"
  },
  "parent_topic_id": "OJHEAFQ26YT",
  "created_at": "2026-01-10T12:34:56Z",
  "updated_at": "2026-01-22T09:15:00Z",
  "last_edited_by": {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com",
      "type": "user"
  },
  "version": 4,
  "access_right": "write",
  "is_open_for_organization": true,
  "is_public": false,
  "attachments": []
}

curl

curl -X PUT 'https://api.pyrus.com/v4/knowledgebase/{id}' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Title",
    "body": "# Hello\n\n- one\n- two\n",
    "parent_topic_id": "TOPIC123",
    "parent_topic_id_changed": true
  }'

Параметры

  • title (опциональный) — новый заголовок статьи или темы;
  • body (опциональный) — тело статьи в формате Markdown;
  • parent_topic_id (опциональный) — указывает, в какую тему переместить статью или тему;
    • null/omit = корень;
  • parent_topic_id_changed (опциональный) — флаг, показывает, что параметр parent_topic_id был изменен.

POST /knowledgebase

Создание статьи или темы в Базе знаний.

POST https://api.pyrus.com/v4/knowledgebase

Тело запроса

{
  "type": "article",
  "title": "Title",
  "parent_topic_id": "TOPIC123",
  "body": "# Hello\n\n- one\n- two\n"
}

Тело ответа

{
  "id": "OJHEAFQ26YT",
  "title": "Title",
  "type": "article",
  "body": "# Hello\n\n- one\n- two\n",
  "author": {
    "id": 1731,
    "first_name": "Bob",
    "last_name": "Smith",
    "email": "Bob.Smith@gmail.com",
    "type": "user"
  },
  "parent_topic_id": "OJHEAFQ26YT",
  "created_at": "2026-01-10T12:34:56Z",
  "updated_at": "2026-01-22T09:15:00Z",
  "last_edited_by": {
    "id": 1731,
    "first_name": "Bob",
    "last_name": "Smith",
    "email": "Bob.Smith@gmail.com",
    "type": "user"
  },
  "version": 4,
  "access_right": "write",
  "is_open_for_organization": true,
  "is_public": false
}

curl

curl -X POST 'https://api.pyrus.com/v4/knowledgebase' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "article",
    "title": "Title",
    "parent_topic_id": "TOPIC123",
    "body": "# Hello\n\n- one\n- two\n"
  }'

Параметры

  • type (опциональный) — показывает формат элемента Базы знаний — статья (article) или тема (topic);
  • title (обязательный) — заголовок статьи или название темы;
  • parent_topic_id (опциональный) — указывает, в какую тему переместить статью или тему;
    • null/omit = корень;
  • body (обязательный для article) — тело статьи в формате Markdown.

GET /knowledgebase/structure

Получение структуры Базы знаний.

GET https://api.pyrus.com/v4/knowledgebase/structure

Тело ответа

{
  "parent_topic_id": "TOPIC123",
  "depth": 3,
  "items": [
    {
      "id": "OJHEAFQ26YT",
      "type": "topic",
      "title": "Getting Started",
      "parent_topic_id": null,
      "access_right": "write",
      "is_open_for_organization": true,
      "children": [
        {
          "id": "ABC123",
          "type": "article",
          "title": "Introduction",
          "parent_topic_id": "OJHEAFQ26YT",
          "access_right": "read",
          "is_open_for_organization": true,
          "children": []
        }
      ]
    }
  ]
}

curl

curl -X GET 'https://api.pyrus.com/v4/knowledgebase/structure' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Параметры

  • parent_topic_id (опциональный, строка) — ID темы, от которого строится дерево структуры Базы знаний:

    • omit/null → строим от корня.

  • depth (опциональный, целое число) — глубина раскрытия дерева структуры, по умолчанию равно 2.

GET /knowledgebase/{id}/permissions

Получение прав доступа для статьи или темы Базы знаний по ID.

GET https://api.pyrus.com/v4/knowledgebase/{id}/permissions

Тело ответа

{
  "global_permission": "read",
  "inherit": true,
  "readers": [
    {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com",
      "type": "user"
    }
  ],
  "editors": [
    {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com",
      "type": "user"
    }
  ]
}

curl

curl -X GET 'https://api.pyrus.com/v4/knowledgebase/OJHEAFQ26YT/permissions' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

PUT /knowledgebase/{id}/permissions

Изменение прав доступа для статьи или темы по ID.

PUT https://api.pyrus.com/v4/knowledgebase/{id}/permissions

Тело запроса

{
  "inherit": true,
  "readers": [123, 456],
  "editors": [789]
}

Тело ответа

{
  "global_permission": "read",
  "inherit": true,
  "readers": [
    {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com",
      "type": "user"
    }
  ],
  "editors": [
    {
      "id": 1731,
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "Bob.Smith@gmail.com",
      "type": "user"
    }
  ]
}

curl

curl -X PUT 'https://api.pyrus.com/v4/knowledgebase/{id}/permissions' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "inherit": false,
    "readers": [123, 456],
    "editors": [789]
  }'

Параметры

  • inherit — параметр только для тем. Если значение равно true, права доступа переходят от родительской (parent) темы. Для статьи параметр не поддерживается.
  • readers, editors — массив пользователей.

DELETE /knowledgebase/{id}

Удаление статьи или темы Базы знаний по ID.

DELETE https://api.pyrus.com/v4/knowledgebase/{id}

Тело ответа

{
  "deleted": true,
}

curl

curl -X DELETE 'https://api.pyrus.com/v4/knowledgebase/{id}?delete_with_children=true' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Параметры

  • delete_with_children (опциональный, булев тип) — определяет, удалять ли вложенные статьи или темы.

Форматирование документов в Markdown

При работе с API Базы знаний содержимое документа возвращается в формате Markdown с расширениями.

Помимо стандартных средств форматирования текста Markdown, поддерживаются некоторые HTML-элементы и специальные кастомные узлы. Это позволяет передавать не только обычный текст, заголовки, списки и таблицы, но и встроенные изображения, вложения, раскрывающиеся блоки, элемент iframe, ссылки на статьи и другие элементы документа.

Внутристрочное форматирование

Полужирный текст

**text**

Курсив

*text*

Зачеркнутый текст

~~text~~

Встроенный код (строчный)

`text`

Ссылка

[text](href)

Подчеркнутый текст

<u>text</u>

Подсказка: в стандартном Markdown подчеркивание не поддерживается, поэтому используется HTML-формат.

Подсветка текста (выделение цветом)

<mark data-color="...">text</mark>

Подсказка: для выделения цветом используется HTML-тег mark с цветовым токеном.

Доступные цветовые токены: red, pink, orange, orangeYellow, yellow, green, greenBlue, blue, violet, purple, gray.

Стандартные элементы Markdown

Заголовки

Используются заголовки от первого до третьего уровня:

# Заголовок 1
## Заголовок 2
### Заголовок 3

Цитата

Каждая строка цитируемого блока текста начинается с символа >:

> Первая строка цитаты
> Вторая строка цитаты

Маркированный список

Для оформления списков используется стандартный синтаксис Markdown:

- первый пункт
- второй пункт

Для оформления вложенных списков используется отступ в 4 пробела от основного списка:

- Пункт
    - Вложенный пункт

Нумерованный список

Используется стандартный синтаксис Markdown для нумерации:

1. Первый пункт
2. Второй пункт

Блок кода

Для оформления блока кода используется следующий формат (обрамление тремя обратными кавычками):

```
code
```

Пример:

```json
{
  "name": "example"
}
```

Таблица

Для оформления таблиц используются стандартные средства форматирования Markdown:

| c1 | c2 |
|---|---|
| c3 | c4 |

Пример:

| Поле | Описание |
|---|---|
| title | Заголовок документа |
| content | Содержимое документа |

Кастомные узлы

Раскрывающийся блок (спойлер)

Для блока с раскрытием используется конструкция details:

<details>
  <summary>Summary</summary>

  content...

</details>

Пример:

<details>
  <summary>Подробнее</summary>

  Здесь находится скрытый текст, который показывается
  после раскрытия блока.

</details>

Изображение

Если у изображения явно заданы размеры, используется HTML-тег img:

<img src="guid" alt="image" width="150" height="200">

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

Пример:

![image](12345678-1234-1234-1234-1234567890ab) // для новых файлов нужен только guid
![image](https://files.pyrus.com/services/kb?Id=12345678-1234-1234-1234-1234567890ab) // ссылка на существующий файл в статье

Видео

Для встраивания видео используется тег video:

<video src="..."></video>

Пример:

<video src="https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=RDdQw4w9WgXcQ"></video>

Доступные для встраивания ресурсы: YouTube, Rutube, VK Video, Vimeo.

Схемы

Для встроенных схем используется специальный iframe-узел:

<iframe data-node="drawio" src="..." width="..."></iframe>

Пример:

<iframe data-node="drawio" src="https://files.pyrus.com/services/kb?Id=12345678-1234-1234-1234-1234567890ab" width="1000"></iframe>

Группа вложений

Для списка вложенных файлов используется контейнер attachmentsGroup:

<div data-node="attachmentsGroup">
  <a data-node="attachment" href="guid">File name</a>
  ...
</div>

Пример:

<div data-node="attachmentsGroup">
  <a data-node="attachment" href="11111111-1111-1111-1111-111111111111">Report</a>
  <a data-node="attachment" href="https://files.pyrus.com/services/kb?Id=12345678-1234-1234-1234-1234567890ab">Specification</a>
</div>

Информационный блок

Для выделенных блоков используется узел hintBlock с цветовым токеном:

<div data-node="hintBlock" data-color="...">

  ...content
</div>

Подсказка: доступные цветовые токены: red, pink, orange, orangeYellow, yellow, green, greenBlue, blue, violet, purple, gray.

Пример:

<div data-node="hintBlock" data-color="blue">
Обратите внимание: этот формат расширяет стандартный Markdown.
</div>

Ссылка на статью Базы знаний

Для внутренних ссылок на статьи используется специальный формат ссылок.

<a data-node="articleLink" data-article-id="...">...</a>

Подсказка: Используйте data-article-id или data-topic-id в зависимости от типа сущности бз.

Пример:

<a data-node="articleLink" data-article-id="AWTGbWIdMj1">Открыть связанную статью</a>
<a data-node="articleLink" data-topic-id="BWVGbWIdMj2">Открыть связанную тему</a>

Якорная ссылка

Для внутренних якорей используется специальный узел:

<a data-node="anchorLink" data-id="..."/>

Пример:

<a data-node="anchorLink" data-id="section-intro"/>

Загрузка файлов в контент

Для добавления guid в блоки изображений и файлов воспользуйтесь следующим методом.

Была ли эта статья полезной?