Knowledge Base

Cloud Pyrus

The Pyrus Knowledge Base is designed for storing documents and collaborating on them. It is an organized information repository and a full-featured text editor in one package. It has everything for collaborative editing and commenting on documents online.

Public API methods for the Knowledge Base enable working with articles and topics within it: reading, creating, updating, deleting content, obtaining the structure tree, and managing access rights to materials.

GET/knowledgebase/{id}Get an article/topic
PUT/knowledgebase/{id}Update an article/topic
POST/knowledgebaseCreate an article/topic
GET/knowledgebase/structureGet the Knowledge Base structure
GET/knowledgebase/{id}/permissionsGet access rights to an article/topic
PUT/knowledgebase/{id}/permissionsChange access rights to an article/topic
DELETE/knowledgebase/{id}Delete an article/topic

GET /knowledgebase/{id}

Getting an article or topic by ID. The method returns the content of the article or topic in Markdown format.

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

Response body

{
    "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}

Update the content of an article or parameters of the topic by ID.

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

Request body

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

Response body

{
  "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
  }'

Parameters

title (optional) — new article or topic headline;
body (optional) — article body in Markdown format;
parent_topic_id (optional) — specifies what topic to move an article or topic to;
- null/omit = root;
parent_topic_id_changed (optional) — a flag that shows that the parent_topic_id parameter has been changed.

POST /knowledgebase

Create an article or topic in Knowledge Base.

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

Request body

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

Response body

{
  "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"
  }'

Parameters

type (optional) — shows the format of the Knowledge Base element — article or topic;
title (required) — title of the article or name of the topic;
parent_topic_id (optional) — indicates which topic to move the article or topic to;
- null/omit = root;
body (required for article) — body of the article in Markdown format.

GET /knowledgebase/structure

Getting the structure of Knowledge Base.

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

Response body

{
  "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>'

Parameters

parent_topic_id (optional, line) — ID of the topic from which the Knowledge Base structure tree is built:
- omit/null → build from the root.
depth (optional, integer) — depth of tree structure disclosure, default is 2.

GET /knowledgebase/{id}/permissions

Get access rights to a Knowledge Base article/topic by ID.

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

Response body

{
  "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

Change access rights to a Knowledge Base article/topic by ID.

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

Request body

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

Response body

{
  "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]
  }'

Parameters

inherit — parameter only for themes. If the value is true, access rights are inherited from the parent theme. The parameter is not supported for articles;
readers, editors — array of users.

DELETE /knowledgebase/{id}

Deleting a Knowledge Base article or topic by ID.

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

Response body

{
  "deleted": true,
}

curl

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

Parameters

delete_with_children (optional, boolean type) — determines whether to delete nested articles or topics.

Formatting documents in Markdown

When working with the Knowledge Base API, the document content is returned in Markdown format with extensions.

In addition to standard Markdown text formatting tools, some HTML elements and special custom nodes are supported. This allows for the transmission of not only plain text, headings, lists, and tables, but also embedded images, attachments, expandable blocks, the iframe element, links to articles, and other document elements.

Inline formatting

Bold text

**text**

Italic

*text*

Strikethrough

~~text~~

Embedded code (inline)

`text`

Link

[text](href)

Underlined text

<u>text</u>

Pyrus Tip: underlining is not supported in standard Markdown, so HTML format is used.

Text highlighting (color)

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

Pyrus Tip: To highlight with color, a HTML tag mark with a color token is used.

Available color tokens: red, pink, orange, orangeYellow, yellow, green, greenBlue, blue, violet, purple, gray.

Standards elements of Markdown

Titles

Three tiers of titles are used:

# Title 1
## Title 2
### Title 3

Quote

Each line of a quoted text begins with a >:

> First line of quote
> Second line of quote

Bullet list

Standard Markdown syntax is used for lists:

- item one
- item two

To format nested lists, a 4-space indent from the main list is used:

- Item
    - Sub-item

Numbered list

Standard Markdown syntax is used for numeration:

1. Item one
2. Item two

Block of code

The following format (framed with three backticks) is used to format a block of code:

```
code
```

Example:

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

Table

Standard Markdown formatting tools are used to format tables:

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

Example:

| Field | Description |
|---|---|
| title | Document header |
| content | Body of document |

Custom nodes

Expanding block (spoiler)

The details structure is used for expanding blocks:

<details>
  <summary>Summary</summary>

  content...

</details>

Example:

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

  Here is the hidden text that is shown 
  after expanding the block.

</details>

Image

If the image has explicitly defined dimensions, the HTML tag img is used:

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

If the dimensions are not indicated, standard Markdown format can be used for formatting an image.

Example:

![image](12345678-1234-1234-1234-1234567890ab) // only a guid is needed for new files
![image](https://files.pyrus.com/services/kb?Id=12345678-1234-1234-1234-1234567890ab) // link to an existing image in the article

Video

The video tag is used for embedding a video:

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

Example:

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

Embeddable video resources: YouTube, Rutube, VK Video, Vimeo.

Schemas

A special iframe node is used for embedded schemas:

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

Example:

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

Group of attachments

The attachmentsGroup container used for attached files:

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

Example:

<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>

Information block

For selected blocks, a hintBlock node is used with a color token:

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

  ...content
</div>

Pyrus Tip: available color tokens: red, pink, orange, orangeYellow, yellow, green, greenBlue, blue, violet, purple, gray.

Example:

<div data-node="hintBlock" data-color="blue">
Note: this format expands standard Markdown.
</div>

Link to a Knowledge Base article

A special link format is used for internal links to articles.

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

Pyrus Tip: Use data-article-id or data-topic-id depending on the entity of Knowledge Base.

Example:

<a data-node="articleLink" data-article-id="AWTGbWIdMj1">Open linked article</a>
<a data-node="articleLink" data-topic-id="BWVGbWIdMj2">Open linked topic</a>

Anchor links

A special node is used for internal anchors:

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

Example:

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

Uploading files to content

To add guid to blocks of images and files, use this method.

Knowledge Base

GET /knowledgebase/{id}

Response body

curl

PUT /knowledgebase/{id}

Request body

Response body

curl

Parameters

POST /knowledgebase

Request body

Response body

curl

Parameters

GET /knowledgebase/structure

Response body

curl

Parameters

GET /knowledgebase/{id}/permissions

Response body

curl

PUT /knowledgebase/{id}/permissions

Request body

Response body

curl

Parameters

DELETE /knowledgebase/{id}

Response body

curl

Parameters

Formatting documents in Markdown

Inline formatting

Bold text

Italic

Strikethrough

Embedded code (inline)

Link

Underlined text

Text highlighting (color)

Standards elements of Markdown

Titles

Quote

Bullet list

Numbered list

Block of code

Table

Custom nodes

Expanding block (spoiler)

Image

Video

Schemas

Group of attachments

Information block

Link to a Knowledge Base article

Anchor links

Uploading files to content

Was this article helpful?