Rich text and comments

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

The API uses type for Database and app for Space. See Terminology.

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:

JavaScript

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();

Grab the secrets (cURL):

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

JavaScript

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();
  })
);

Result:

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

JavaScript

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();

Result:

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

JavaScript

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();

Grab the secret:

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

Update the document:

JavaScript

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.'
    })
  }
);

Update multiple documents in a single batch request:

JavaScript

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' }
      ]
    })
  }
);

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.

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:

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:

JavaScript

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();

Make sure the result looks good:

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

JavaScript

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!'
        }
      ]
    })
  }
);