> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fibery.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rich text and comments

> Learn how to read and write rich-text Fields and comments using the Fibery API.

<Note>
  The API uses `type` for Database and `app` for Space. See [Terminology](/guides/general/terminology#api-naming).
</Note>

## Select rich text Field

Take a look how rich text Fields work in Fibery, if you haven't yet.

To select a rich text Field we should:

1. Get `fibery/secret` of the corresponding collaborative document.
2. Get the document via `api/documents` endpoint using this `fibery/secret`.

Supported document formats:

* Markdown (`md`) — default
* HTML (`html`)
* JSON of a particular structure (`json`)
* Plain-text (`plain-text`)

`Cricket/Player` Database used as an example

| Field name    | Field type                                     |
| ------------- | ---------------------------------------------- |
| `Cricket/Bio` | rich text (`Collaboration~Documents/Document`) |

Get the related collaborative document's `fibery/secret`:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'fibery.entity/query',
      args: {
        query: {
          'q/from': 'Cricket/Player',
          'q/select': [
            'Cricket/Name',
            { 'Cricket/Bio': ['Collaboration~Documents/secret'] }
          ],
          'q/limit': 2
        }
      }
    })
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '
     {
       "command": "fibery.entity/query",
       "args": {
         "query": {
           "q/from": "Cricket/Player",
           "q/select": [
             "Cricket/Name",
             {"Cricket/Bio": ["Collaboration~Documents/secret"]}
           ],
           "q/limit": 2
         }
       }
     }
    '
  ```
</CodeGroup>

Grab the secrets (cURL):

```json theme={null}
{
  "success": true,
  "result": [
    {
      "Cricket/Name": "Joe Root",
      "Cricket/Bio": {
        "Collaboration~Documents/secret": "e15e0f75-5e02-4e72-b3f3-98462dd86e45"
      }
    },
    {
      "Cricket/Name": "Harry Brook",
      "Cricket/Bio": {
        "Collaboration~Documents/secret": "629b492e-d9be-444a-a6b4-ec70f3a57dd9"
      }
    }
  ]
}
```

Get the documents one-by-one:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const secrets = [
    'e15e0f75-5e02-4e72-b3f3-98462dd86e45',
    '629b492e-d9be-444a-a6b4-ec70f3a57dd9'
  ];

  const documents = await Promise.all(
    secrets.map(async (secret) => {
      const response = await fetch(
        `https://YOUR_ACCOUNT.fibery.io/api/documents/${secret}?format=html`,
        { headers: { 'Authorization': 'Token YOUR_TOKEN' } }
      );
      return response.json();
    })
  );
  ```

  ```bash cURL theme={null}
  curl -X GET https://YOUR_ACCOUNT.fibery.io/api/documents/e15e0f75-5e02-4e72-b3f3-98462dd86e45?format=html \
    -H 'Authorization: Token YOUR_TOKEN'

  curl -X GET https://YOUR_ACCOUNT.fibery.io/api/documents/629b492e-d9be-444a-a6b4-ec70f3a57dd9?format=html \
    -H 'Authorization: Token YOUR_TOKEN'
  ```
</CodeGroup>

Result:

```json theme={null}
{
  "secret": "e15e0f75-5e02-4e72-b3f3-98462dd86e45",
  "content": "<p>Joe Root is an English cricketer and former Test captain, widely regarded as one of the finest batsmen of his generation. He has accumulated more than 12,000 Test runs and over 30 centuries, ranking among England's all-time greats.</p>"
}

{
  "secret": "629b492e-d9be-444a-a6b4-ec70f3a57dd9",
  "content": "<p>Harry Brook is an English right-handed batsman known for his aggressive stroke play and rapid Test debut century in 2022. He plays domestic cricket for Yorkshire and has become a key fixture in England's white-ball setup.</p>"
}
```

Get multiple documents in a single batch request:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/documents/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'get-documents',
      args: [
        { secret: 'e15e0f75-5e02-4e72-b3f3-98462dd86e45' },
        { secret: '629b492e-d9be-444a-a6b4-ec70f3a57dd9' }
      ]
    })
  });
  const documents = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/documents/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "command": "get-documents",
      "args": [
        { "secret": "e15e0f75-5e02-4e72-b3f3-98462dd86e45" },
        { "secret": "629b492e-d9be-444a-a6b4-ec70f3a57dd9" }
      ]
    }'
  ```
</CodeGroup>

Result:

```json theme={null}
[
  {
    "secret": "e15e0f75-5e02-4e72-b3f3-98462dd86e45",
    "content": "Joe Root is an English cricketer and former Test captain, widely regarded as one of the finest batsmen of his generation. He has accumulated more than 12,000 Test runs and over 30 centuries, ranking among England's all-time greats."
  },
  {
    "secret": "629b492e-d9be-444a-a6b4-ec70f3a57dd9",
    "content": "Harry Brook is an English right-handed batsman known for his aggressive stroke play and rapid Test debut century in 2022. He plays domestic cricket for Yorkshire and has become a key fixture in England's white-ball setup."
  }
]
```

## Update rich text Field

To update a rich text Field we should:

1. Get `fibery/secret` of the corresponding collaborative document.
2. Update the document via `api/documents` endpoint using this `fibery/secret`.

Supported document formats:

* Markdown (md) — default
* HTML (html)
* JSON of a particular structure (json)

`Cricket/Player` Database used as an example

| Field name    | Field type                                     |
| ------------- | ---------------------------------------------- |
| `Cricket/Bio` | rich text (`Collaboration~Documents/Document`) |

Get collaborative document's `fibery/secret`:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'fibery.entity/query',
      args: {
        query: {
          'q/from': 'Cricket/Player',
          'q/select': [
            'fibery/id',
            { 'Cricket/Bio': ['Collaboration~Documents/secret'] }
          ],
          'q/where': ['=', ['fibery/id'], '$id'],
          'q/limit': 1
        },
        params: { '$id': '20f9b920-9752-11e9-81b9-4363f716f666' }
      }
    })
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '
      {
        "command": "fibery.entity/query",
        "args": {
          "query": {
            "q/from": "Cricket/Player",
            "q/select": [
              "fibery/id",
              {"Cricket/Bio": ["Collaboration~Documents/secret"]}
            ],
            "q/where": ["=", ["fibery/id"], "$id"],
            "q/limit": 1
          },
          "params": {"$id": "20f9b920-9752-11e9-81b9-4363f716f666"}
        }
      }
    '
  ```
</CodeGroup>

Grab the secret:

```json theme={null}
{
  "success": true,
  "result": [
    {
      "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
      "Cricket/Bio": {
        "Collaboration~Documents/secret": "b33a25d1-99ba-11e9-8c59-09d0cb6f3aeb"
      }
    }
  ]
}
```

Update the document:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://YOUR_ACCOUNT.fibery.io/api/documents/b33a25d1-99ba-11e9-8c59-09d0cb6f3aeb?format=md',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Token YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        content: 'Virat Kohli (born 5 November 1988) is an Indian [cricketer](https://en.wikipedia.org/wiki/Cricket) who currently captains the India national team.\nHe plays for Royal Challengers Bangalore in the Indian Premier League.'
      })
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X PUT https://YOUR_ACCOUNT.fibery.io/api/documents/b33a25d1-99ba-11e9-8c59-09d0cb6f3aeb?format=md \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "content": "Virat Kohli (born 5 November 1988) is an Indian [cricketer](https://en.wikipedia.org/wiki/Cricket) who currently captains the India national team.\nHe plays for Royal Challengers Bangalore in the Indian Premier League."
    }'
  ```
</CodeGroup>

Update multiple documents in a single batch request:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://YOUR_ACCOUNT.fibery.io/api/documents/commands?format=md',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Token YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        command: 'create-or-update-documents',
        args: [
          { secret: 'b33a25d1-99ba-11e9-8c59-09d0cb6f3aeb', content: 'my md content 1' },
          { secret: 'b33a25d3-99ba-11e9-8c59-09d0cb6f3aeb', content: 'my md content 2' }
        ]
      })
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://YOUR_ACCOUNT.fibery.io/api/documents/commands?format=md' \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
       "command": "create-or-update-documents",
       "args": [
         {
           "secret": "b33a25d1-99ba-11e9-8c59-09d0cb6f3aeb",
           "content": "my md content 1"
         },
         {
           "secret": "b33a25d3-99ba-11e9-8c59-09d0cb6f3aeb",
           "content": "my md content 2"
         }
       ]
     }
    '
  ```
</CodeGroup>

Status code 200 means that the update has been successful.

## Add comment

Once you install the Comments extension on a Database, you are free to add comments to the Database's Entities – both via UI and API.

Comments are assembled from pre-existing basic building blocks:

* Comment (`comments/comment`) is a Database with Fields like Author (`fibery/created-by`) and Creation Date (`fibery/creation-date`).
* The `Comments` extension connects a parent Database with the Comment Database via a one-to-many relation.
* Each individual comment is an Entity of the Comment Database.
* The content of a comment is stored in a collaborative document just like [rich-text Fields](/guides/http-api/fields).

To add a comment:

1. Create an Entity of the Comment Database.
2. Connect this comment to a proper parent Entity.
3. Set the comment's content.

Generate two UUIDs – for the comment ID and the document secret ID:

```plaintext theme={null}
a88626cb-2f08-4821-9d5f-3edb9b624c26
9f18d395-05da-44dc-9f21-602b2e744b14
```

Create an Entity of the auxiliary Comment Database and link it to the parent Entity:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const PARENT_ENTITY_ID = '216c2a00-9752-11e9-81b9-4363f716f666';
  const COMMENT_AUTHOR_ID = 'fe1db100-3779-11e9-9162-04d77e8d50cb';
  const COMMENT_ID = 'a88626cb-2f08-4821-9d5f-3edb9b624c26';
  const DOCUMENT_SECRET_ID = '9f18d395-05da-44dc-9f21-602b2e744b14';

  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'fibery.command/batch',
      args: {
        commands: [
          {
            command: 'fibery.entity/create',
            args: {
              type: 'comments/comment',
              entity: {
                'fibery/id': COMMENT_ID,
                'comment/document-secret': DOCUMENT_SECRET_ID,
                'fibery/created-by': { 'fibery/id': COMMENT_AUTHOR_ID }
              }
            }
          },
          {
            command: 'fibery.entity/add-collection-items',
            args: {
              type: 'Cricket/Player',
              entity: { 'fibery/id': PARENT_ENTITY_ID },
              field: 'comments/comments',
              items: [{ 'fibery/id': COMMENT_ID }]
            }
          }
        ]
      }
    })
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '
     {
       "command":"fibery.command/batch",
       "args":{
         "commands":[
           {
             "command":"fibery.entity/create",
             "args":{
               "type":"comments/comment",
               "entity":{
                 "fibery/id":"a88626cb-2f08-4821-9d5f-3edb9b624c26",
                 "comment/document-secret":"9f18d395-05da-44dc-9f21-602b2e744b14",
                 "fibery/created-by": {"fibery/id": "fe1db100-3779-11e9-9162-04d77e8d50cb"}
               }
             }
           },
           {
             "command":"fibery.entity/add-collection-items",
             "args":{
               "type":"Cricket/Player",
               "entity":{
                 "fibery/id":"20f9b920-9752-11e9-81b9-4363f716f666"
               },
               "field":"comments/comments",
               "items":[
                 {
                   "fibery/id": "a88626cb-2f08-4821-9d5f-3edb9b624c26"
                 }
               ]
             }
           }
         ]
       }
     }
    '
  ```
</CodeGroup>

Make sure the result looks good:

```json theme={null}
{
  "success": true,
  "result": [
    {
      "success": true,
      "result": {
        "comment/document-secret": "9f18d395-05da-44dc-9f21-602b2e744b14",
        "fibery/id": "a88626cb-2f08-4821-9d5f-3edb9b624c26",
        "fibery/public-id": "139",
        "fibery/creation-date": "2021-05-05T17:37:21.933Z",
        "comments/parent": null,
        "fibery/created-by": {
          "fibery/id": "fe1db100-3779-11e9-9162-04d77e8d50cb"
        },
        "comment/author": {
          "fibery/id": "fe1db100-3779-11e9-9162-04d77e8d50cb"
        }
      }
    },
    {
      "success": true,
      "result": "ok"
    }
  ]
}
```

Set the comment's content:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://YOUR_ACCOUNT.fibery.io/api/documents/commands?format=md',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Token YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        command: 'create-or-update-documents',
        args: [
          {
            secret: '9f18d395-05da-44dc-9f21-602b2e744b14',
            content: 'He is the [G.O.A.T.](https://en.wikipedia.org/wiki/Greatest_of_All_Time) batsman!'
          }
        ]
      })
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/documents/commands?format=md \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
       "command": "create-or-update-documents",
       "args": [
         {
           "secret": "9f18d395-05da-44dc-9f21-602b2e744b14",
           "content": "He is the [G.O.A.T.](https://en.wikipedia.org/wiki/Greatest_of_All_Time) batsman!"
         }
       ]
     }
    '
  ```
</CodeGroup>