> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Working with Formatting

> **Info**
>
> ### Beta APIs
>
> The Document APIs are beta. Send the `EARLY-ACCESS: true` header on every request shown here; without it these endpoints are unavailable. See [Introduction to Documents](/docs/introduction-to-documents) and the [Stability Guidelines](/docs/stability-guidelines).

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.

**`Endpoint`**

```text title="Endpoint"
PATCH /api/v3/entry/etr_8rVKW0g7
```

**`Example Request`**

```json title="Example Request"
{
  "partsMutation": {
    "operationType": "insert",
    "version": "etrver_Ax7b2kR9",
    "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, each text part returns the same fields:

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/entry/etr_8rVKW0g7/parts/items
```

**`Example Response`**

```json title="Example Response"
{
  "items": [
    {
      "__typename": "DocumentPartText",
      "id": "docpart_Xt5bJ7z3",
      "modifiedAt": "2025-01-15T14:22:00Z",
      "versionMetadata": { "versionId": "etrver_Ax7b2kR9", "createdAt": "2025-01-15T14:22:00Z" },
      "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.

To format cells, submit an `update_table_cells` operation in a `partsMutation` on the document that contains the table. Each cell update targets one cell by `rowIndex` and `columnIndex`, both counted from 0. Include `inputValue` to change the cell's value as well, or leave it out to keep the existing value. In `properties`, any style the list leaves out is removed from the cell.

**`Endpoint`**

```text title="Endpoint"
PATCH /api/v3/entry/etr_8rVKW0g7
```

**`Example Request`**

```json title="Example Request"
{
  "partsMutation": {
    "operationType": "update_table_cells",
    "version": "etrver_YczTdvGdm6",
    "documentPartId": "docpart_XZuYFzO2t3",
    "cellUpdates": [
      {
        "rowIndex": 0,
        "columnIndex": 0,
        "format": {
          "properties": ["BOLD"],
          "alignment": "LEFT"
        }
      },
      {
        "rowIndex": 0,
        "columnIndex": 1,
        "inputValue": { "type": "text_value", "value": "124.600" },
        "format": {
          "backgroundColor": "#FDC68A",
          "link": "https://benchling.com/"
        }
      }
    ]
  }
}
```

For more on editing tables, including inserting rows, see [Working with Tables](/docs/working-with-tables).

When reading the table's rows, each cell might include the resolved `format` object:

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/document-part-unstructured-table/docpart_XZuYFzO2t3/rows/items
```

**`Example Response`**

```json title="Example Response"
{
  "items": [
    {
      "rowIndex": 0,
      "documentPart": { "id": "docpart_XZuYFzO2t3", "__typename": "DocumentPartUnstructuredTable" },
      "cells": [
        {
          "inputValue": { "value": "SMPL_001", "__typename": "TextValue" },
          "format": {
            "properties": ["BOLD"],
            "foregroundColor": null,
            "backgroundColor": null,
            "link": null,
            "alignment": "LEFT",
            "precision": null,
            "scientificNotation": null,
            "__typename": "TableCellFormat"
          },
          "__typename": "TableCell"
        },
        ...
      ],
      "__typename": "UnstructuredTableRow"
    }
  ],
  "nextToken": ""
}
```

To clear a cell's formatting, send a cell update with `format` set to `null`.