Working with Formatting

Document content can include visual formatting such as bold font weight, colors, links, and mentions. You can format text-like content and table cells, but the two APIs use different shapes. Text-like content includes text, headers, and list items.

Key properties about formatting:

Text-like content uses span-based formatting that applies to a range of characters.
Tables use cell-based formatting that applies to the entire cell.
The allowed formatting options for text and tables differ slightly. The API documentation details the supported formatting options for each type of content.

Formatting text

Text-like content exposes three parallel arrays:

formats: Applies styling to a character range.
links: Applies a link to a character range.
mentions: Inserts an item tag at a character position.

For formats and links, start is inclusive and end is exclusive.

PATCH /api/v3/entry/etr_8rVKW0g7

{
  "partsMutation": {
    "operationType": "insert",
    "version": "etrver_Ax7b2kR9",
    "coordinates": {
      "position": "end_of_document"
    },
    "parts": [
      {
        "contentType": "text",
        "text": "Sample A showed elevated concentration.",
        "formats": [
          {
            "start": 0,
            "end": 8,
            "properties": ["BOLD"]
          },
          {
            "start": 16,
            "end": 24,
            "properties": ["ITALIC"],
            "foregroundColor": "#0B6E4F"
          }
        ],
        "links": [
          {
            "start": 25,
            "end": 38,
            "url": "https://docs.benchling.com/"
          }
        ],
        "mentions": [
          {
            "position": 39,
            "itemId": "bfi_abc123"
          }
        ]
      }
    ]
  }
}

When reading text content from the parts listing, the content object returns the same fields:

GET /api/v3/entry/etr_8rVKW0g7/parts/items

{
  "items": [
    {
      "id": "docpart_Xt5bJ7z3",
      "versionId": "etrver_Ax7b2kR9",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "container": { "id": "etr_8rVKW0g7" },
      "content": {
        "__typename": "Benchling.TextDocumentContent",
        "text": "Sample A showed elevated concentration.",
        "formats": [
          {
            "start": 0,
            "end": 8,
            "properties": ["BOLD"],
            "foregroundColor": null,
            "backgroundColor": null
          }
        ],
        "links": [
          {
            "start": 25,
            "end": 38,
            "url": "https://docs.benchling.com/"
          }
        ],
        "mentions": [],
        "indentation": 0
      }
    }
  ],
  "nextToken": ""
}

Formatting tables

Table cells don't use character ranges. Instead, each cell might include a format object that styles the whole cell.

PATCH /api/v3/document-part-unstructured-table/docpart_XZuYFzO2t3

{
  "versionId": "etrver_YczTdvGdm6",
  "columnDefinitions": [
    { "name": "Sample ID" },
    { "name": "Value" }
  ],
  "rows": [
    {
      "cells": [
        {
          "inputValue": { "type": "text_value", "value": "SMPL_001" },
          "format": {
            "properties": ["BOLD"],
            "alignment": "LEFT"
          }
        },
        {
          "inputValue": { "type": "text_value", "value": "124.600" },
          "format": {
            "backgroundColor": "#FDC68A",
            "link": "https://benchling.com/"
          }
        }
      ]
    }
  ]
}

When reading table detail, each cell might include the resolved format object:

GET /api/v3/document-part-unstructured-table/docpart_XZuYFzO2t3

{
  "id": "docpart_XZuYFzO2t3",
  "versionId": "etrver_YczTdvGdm6",
  "content": {
    "__typename": "Benchling.UnstructuredTableDocumentContent",
    "name": "Concentration Measurements",
    "columnDefinitions": [
      { "name": "Sample ID" },
      { "name": "Value" }
    ],
    "rows": [
      {
        "cells": [
          {
            "inputValue": { "type": "text_value", "value": "SMPL_001" },
            "format": {
              "properties": ["BOLD"],
              "foregroundColor": null,
              "backgroundColor": null,
              "link": null,
              "alignment": "LEFT"
            }
          }
        ]
      }
    ],
    "isEvaluated": false
  }
}

To clear cell formatting, replace the table with cells that omit format or set format to null.