> 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. # Update an unstructured table PATCH https://{tenant_name}.benchling.com/api/v3/document-part-unstructured-table/{doc_part_id} Content-Type: application/json Deprecated. Use the document `partsMutation` operations instead: - To edit cell content, use the `update_table_cells` operation. - To append rows, use the `insert_table_rows` operation. - To change columns or merged cells, delete the table with the `delete` operation and re-create it with the updated data using the `insert` operation. Update an unstructured table's column definitions and cell content. All row and column indices in this endpoint are 0-based. Both columnDefinitions and rows are optional; omitting either preserves the existing values. When provided, they fully replace the existing values with no per-field carry-forward. Cells in locked columns cannot be modified; lock enforcement uses the post-mutation column state, so unlocking a column and editing its cells can be done in a single request. When adding rows to a table with locked columns, the new rows' locked-column cells must be empty. Requires versionId for optimistic concurrency; returns 409 on stale version. Returns 400 if the document part is not an unstructured table or validation fails. Reference: https://docs.benchling.com/docs/api/benchling-api/document-part/document-part-unstructured-table-update ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `doc_part_id` (string, required) ### Headers - `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3. ### Body (application/json) This endpoint expects an object. - `versionId` (string, required) — The document's current version ID from versionMetadata.versionId in the last GET response. Required for optimistic concurrency. - `caption` (DocumentPartUnstructuredTableUpdateRequestCaption, optional, nullable) — The table's caption. Omit to preserve the existing caption. Set to null to clear the caption. - `columnDefinitions` (list of DocumentPartUnstructuredTableUpdateRequestColumnDefinitionsItem, optional) — Column definitions for the table. Omit to preserve existing columns. When provided, fully replaces all column definitions; omitted fields on each column definition default to null (not the existing value). - `name` (string, optional) — Display name of the table. Must be non-empty, at most 100 characters, and unique within the document. Omit to preserve the existing name. - `rows` (list of DocumentPartUnstructuredTableUpdateRequestRowsItem, optional) — Row data for the table. Omit to preserve existing rows. When provided, fully replaces all rows with no per-cell carry-forward of format, selectorId, or other fields from the existing table. ## Response ### 200 Updated unstructured table content - `__typename` (string, optional) - `caption` (Caption, optional, nullable) — Specifies the rich text caption displayed with the table. Null if the table has no caption. - `columnDefinitions` (list of TableColumnDefinition, optional) — Lists column definitions for the table. - `createdAt` (string, optional) — Timestamp inherited from the document content backing this part. For entry and document content, this can reflect when the containing document was created, not when the DocumentPart identifier was created. - `documentParent` (ObjectRef, optional) - `id` (string, optional) — Identifies the document part. - `indentation` (integer, optional) — Specifies the indentation level for this content within the document. - `isEvaluated` (boolean, optional) — Specifies whether formula evaluation has been applied to the table. - `modifiedAt` (string, optional) — Specifies when this document part was last modified. - `modifier` (PrincipalRef, optional, nullable) — Identifies who last modified this document part. - `name` (string, optional) — Specifies the display name of the table. - `rowCount` (integer, optional) — Specifies the number of rows in the table. - `rows` (list of TableRow, optional) — Lists rows in the table, each containing an ordered array of cells. - `versionMetadata` (DocumentLikeVersionMetadata, optional) — Specifies version metadata for the parent document. ## Errors ### 400 Document Part Unstructured Table Update Request Bad Request Error Bad Request - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 403 Document Part Unstructured Table Update Request Forbidden Error Forbidden - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 404 Document Part Unstructured Table Update Request Not Found Error Not Found - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 409 Document Part Unstructured Table Update Request Conflict Error Conflict - `detail` (GeneralErrorDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) ### 429 Document Part Unstructured Table Update Request Too Many Requests Error Too Many Requests - `detail` (TooManyRequestsErrorBodyDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `invalidId` (string, optional) - `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`. - Allowed values: `user`, `integration`, `tenant` ### 500 Document Part Unstructured Table Update Request Internal Server Error Internal Server Error - `detail` (InternalServerErrorBodyDetail, required, nullable) - `instance` (string, required) - `status` (integer, required) - `title` (string, required, nullable) - `type` (string, required) - `errorId` (string, optional) ## Types ### DocumentPartUnstructuredTableUpdateRequestCaption The table's caption. Omit to preserve the existing caption. Set to null to clear the caption. - `text` (string, required) - `formats` (list of DocumentPartUnstructuredTableUpdateRequestCaptionFormatsItem, optional) - `links` (list of DocumentPartUnstructuredTableUpdateRequestCaptionLinksItem, optional) - `mentions` (list of DocumentPartUnstructuredTableUpdateRequestCaptionMentionsItem, optional) ### DocumentPartUnstructuredTableUpdateRequestColumnDefinitionsItem - `isLocked` (boolean, optional) - `name` (string, optional, nullable) - `width` (double, optional, nullable) ### DocumentPartUnstructuredTableUpdateRequestRowsItem - `cells` (list of DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItem, required) ### Caption A rich text caption attached to a piece of document content, such as a table or an attachment. - `__typename` (string, optional) - `formats` (list of TextFormat, optional) - `links` (list of LinkSpan, optional) - `mentions` (list of Mention, optional) - `text` (string, optional) ### TableColumnDefinition Specifies a column definition within an unstructured table. - `__typename` (string, optional) - `isLocked` (boolean, optional) — Specifies whether the column width is locked against resizing. - `name` (string, optional) — Specifies the column display name. - `width` (double, optional, nullable) — Specifies the column width in pixels. Defaults to 100 when unset. ### ObjectRef - `__typename` (string, optional) - `id` (string, optional) ### PrincipalRef - `__typename` (string, optional) - `id` (string, optional) ### TableRow Specifies a row within an unstructured table. - `__typename` (string, optional) - `cells` (list of TableCell, optional) — Lists cells in the row in column order. - `rowIndex` (integer, optional) — Specifies the row's absolute position within the table, zero-based. ### DocumentLikeVersionMetadata Version metadata for a document such as an entry, template, or subtemplate. Identifies a specific content revision and records when that revision was produced. Use this to detect changes, pin a revision, or reference a particular version without loading the full version record. - `__typename` (string, optional) - `createdAt` (string, optional, nullable) — Specifies when this version was created. Versions are immutable; this is the time the parent document was last edited to produce this revision. - `versionId` (string, optional) — Identifies this version of the document. ### GeneralErrorDetail ### TooManyRequestsErrorBodyDetail ### InternalServerErrorBodyDetail ### DocumentPartUnstructuredTableUpdateRequestCaptionFormatsItem - `backgroundColor` (string, optional, nullable) - `end` (integer, optional) - `foregroundColor` (string, optional, nullable) - `properties` (list of enum, optional) - Allowed values: `BOLD`, `ITALIC`, `UNDERLINE`, `STRIKETHROUGH`, `SUBSCRIPT`, `SUPERSCRIPT`, `MONOSPACE` - `start` (integer, optional) ### DocumentPartUnstructuredTableUpdateRequestCaptionLinksItem - `end` (integer, optional) - `start` (integer, optional) - `url` (string, optional) ### DocumentPartUnstructuredTableUpdateRequestCaptionMentionsItem - `itemId` (string, optional) - `position` (integer, optional) ### DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItem A cell is one of three variants: - Value cell: inputValue object; mergeRange and mergeRangeParent both null or omitted. - Anchor cell: inputValue object and mergeRange object; mergeRangeParent null or omitted. Defines the top-left of a merged region. - Child cell: mergeRangeParent object; mergeRange null or omitted and inputValue empty. References the anchor cell that owns this position. mergeRange and mergeRangeParent are optional; omitting either field is equivalent to sending null (clears the value). - `inputValue` (DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemInputValue, required) — The cell's input value. For unstructured tables this is always a TextValue. - `format` (DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemFormat, optional, nullable) — Cell formatting. If provided, fully replaces any existing format. Set to null, an empty object, or omit to clear all formatting. - `mergeRange` (DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemMergeRange, optional, nullable) — Defines this cell as the anchor of a merged region with the given row and column span. Send null to clear any existing merge anchor. Omitting is equivalent to null. - `mergeRangeParent` (DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemMergeRangeParent, optional, nullable) — Marks this cell as a merge child belonging to the anchor at the given (row, col). Send null to clear any existing merge parent. Omitting is equivalent to null. - `selectorId` (string, optional, nullable) — Id of a TableCellSelector on the parent entry or template. Set to assign a dropdown selector to this cell. Set to null or omit to clear the selector reference. ### TextFormat Specifies inline styling applied to a character range within rich text. - `__typename` (string, optional) - `backgroundColor` (string, optional, nullable) — Specifies the background color applied to the character range, when set. - `end` (integer, optional) — Specifies the exclusive end index of the character range within the plain-text body. - `foregroundColor` (string, optional, nullable) — Specifies the text color applied to the character range, when set. - `properties` (list of enum, optional) — Specifies the character style properties applied to the range: bold, italic, underline, strikethrough, subscript, superscript, and monospace. - Allowed values: `BOLD`, `ITALIC`, `UNDERLINE`, `STRIKETHROUGH`, `SUBSCRIPT`, `SUPERSCRIPT`, `MONOSPACE` - `start` (integer, optional) — Specifies the inclusive start index of the character range within the plain-text body. ### LinkSpan Specifies a hyperlink applied to a character range within rich text content. - `__typename` (string, optional) - `end` (integer, optional) — Specifies the exclusive end index of the character range within the plain-text body. - `start` (integer, optional) — Specifies the inclusive start index of the character range within the plain-text body. - `url` (string, optional) — Specifies the URL of the hyperlink. ### Mention Represents an inline mention of another Benchling item within text content. - `__typename` (string, optional) - `itemId` (string, optional) — Identifies the referenced Benchling item. - `position` (integer, optional) — Specifies the zero-based insertion index within the plain-text body where this mention appears. Mentions do not occupy characters in the plain-text body for purposes of format range start and end positions. ### TableCell Specifies a cell within an unstructured table row. Cells may be standalone or participate in a merged region. The anchor cell holds the merged region span; other cells in the region reference the anchor cell coordinates. - `__typename` (string, optional) - `errors` (list of CellError, optional) — Lists evaluation and validation errors present on the cell. Inspect the error type on each error to distinguish evaluation failures from validation failures. - `evaluationValue` (TableCellEvaluationValue, optional, nullable) — Specifies the evaluated value computed by formula evaluation, when present. Read-only. - `format` (TableCellFormat, optional, nullable) — Specifies formatting properties applied to the cell. Null when the cell has no formatting. - `inputValue` (TableCellInputValue, optional) — Specifies the cell input value. For unstructured tables this is always a text value. - `mergeRange` (TableMergeRange, optional, nullable) — Specifies the merged region span on the anchor cell. Present only on anchor cells. - `mergeRangeParent` (MergedCellAnchor, optional, nullable) — Specifies coordinates of the anchor cell. Present on cells within a merged region that are not the anchor. - `selectorId` (string, optional, nullable) — Specifies the dropdown selector identifier for this cell, when present. Match this value to selectorId on dropdown selectors defined on the document. ### DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemInputValue The cell's input value. For unstructured tables this is always a TextValue. - `type` (enum, required) - Allowed values: `text_value` - `value` (string, required) ### DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemFormat Cell formatting. If provided, fully replaces any existing format. Set to null, an empty object, or omit to clear all formatting. - `alignment` (enum, optional, nullable) - Allowed values: `LEFT`, `CENTER`, `RIGHT` - `backgroundColor` (string, optional, nullable) — Hex color code (#RGB or #RRGGBB). - `foregroundColor` (string, optional, nullable) — Hex color code (#RGB or #RRGGBB). - `link` (string, optional, nullable) - `properties` (list of enum, optional) - Allowed values: `BOLD`, `ITALIC`, `UNDERLINE`, `STRIKETHROUGH`, `IMPORTANT` ### DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemMergeRange Defines this cell as the anchor of a merged region with the given row and column span. Send null to clear any existing merge anchor. Omitting is equivalent to null. - `mergeColSpan` (integer, required) - `mergeRowSpan` (integer, required) ### DocumentPartUnstructuredTableUpdateRequestRowsItemCellsItemMergeRangeParent Marks this cell as a merge child belonging to the anchor at the given (row, col). Send null to clear any existing merge parent. Omitting is equivalent to null. - `col` (integer, required) - `row` (integer, required) ### CellError Specifies a single error present on a table cell. The error type field distinguishes evaluation failures from validation failures; message is the error description. - `__typename` (string, optional) - `errorType` (enum, optional) — Specifies whether the error is an evaluation failure or a validation failure. - Allowed values: `EVALUATION`, `VALIDATION` - `message` (string, optional) — Specifies the error message. - `type` (string, optional, nullable) — Specifies the display name for the specific error, such as reference error or value error. Populated for evaluation errors; null for validation errors. ### TableCellEvaluationValue ### TableCellFormat Specifies formatting properties applied to an entire table cell. - `__typename` (string, optional) - `alignment` (enum, optional, nullable) — Specifies horizontal text alignment for the cell, when set. - Allowed values: `LEFT`, `CENTER`, `RIGHT` - `backgroundColor` (string, optional, nullable) — Specifies the background color applied to the cell, when set. - `foregroundColor` (string, optional, nullable) — Specifies the text color applied to the cell, when set. - `link` (string, optional, nullable) — Specifies a hyperlink URL applied to the cell, when set. - `precision` (integer, optional, nullable) — Specifies the decimal precision used to display a numeric cell. - `properties` (list of enum, optional) — Lists character style properties applied to the cell. - Allowed values: `BOLD`, `ITALIC`, `UNDERLINE`, `STRIKETHROUGH`, `IMPORTANT` - `scientificNotation` (boolean, optional, nullable) — Specifies whether a numeric cell is displayed in scientific notation. ### TableCellInputValue Specifies the cell input value. For unstructured tables this is always a text value. ### TableMergeRange Specifies the extent of a merged cell region, set on the anchor cell. - `__typename` (string, optional) - `mergeColSpan` (integer, optional) — Specifies the number of columns in the merged region, including the anchor cell. - `mergeRowSpan` (integer, optional) — Specifies the number of rows in the merged region, including the anchor cell. ### MergedCellAnchor Specifies coordinates of the anchor cell for a cell within a merged region. - `__typename` (string, optional) - `col` (integer, optional) — Specifies the zero-based column index of the anchor cell. - `row` (integer, optional) — Specifies the zero-based row index of the anchor cell. ### StringCellEvaluationValue Specifies a string evaluation value. - `__typename` (string, optional) - `value` (string, optional) — Specifies the evaluated string value. ### NumberCellEvaluationValue Specifies a numeric evaluation value. Display formatting lives on TableCell.format. - `__typename` (string, optional) - `value` (string, optional) — Specifies the evaluated numeric value, carrying the most precise representation available for the cell's typed value. Serialized as a string and never pre-formatted; use TableCell.format for display formatting. ### BooleanCellEvaluationValue Specifies a boolean evaluation value. - `__typename` (string, optional) - `value` (boolean, optional) — Specifies the evaluated boolean value. ### DateCellEvaluationValue Specifies a date evaluation value. - `__typename` (string, optional) - `value` (date, optional) — Specifies the evaluated date value. ### DateTimeCellEvaluationValue Specifies a datetime evaluation value. - `__typename` (string, optional) - `value` (string, optional) — Specifies the evaluated datetime value. ### ObjectLinkCellEvaluationValue The evaluation-value counterpart of ObjectLinkValue: a flat id/name pair for any LinkableDomainObject a cell links to, which includes non-entity targets such as users, teams, studies, inventory items, attachments, and dropdown options. Resolve inputValue to get the concrete type. - `__typename` (string, optional) - `id` (string, optional) — Identifies the linked object. - `name` (string, optional) — Specifies the display name of the linked entity. ### ArrayCellEvaluationValue Specifies an array evaluation value containing multiple cell evaluation values. - `__typename` (string, optional) - `value` (list of ArrayCellEvaluationValueValueItem, optional) — Lists the evaluated values in the array. ### UnsupportedCellEvaluationValue Specifies an evaluation value for types that cannot be represented in the current API. Use the cell input value as a fallback. - `__typename` (string, optional) - `errorReason` (string, optional) — Specifies the reason the evaluation value could not be represented. ### BooleanValue A type that represents boolean values. - `__typename` (string, optional) - `value` (boolean, optional) — The boolean value. ### DateTimeValue A type that represents datetime values. - `__typename` (string, optional) - `value` (string, optional) — The datetime value with UTC as the timezone. ### DateValue A type that represents date values. - `__typename` (string, optional) - `value` (date, optional) — The date value. ### DecimalValue A type that represents decimal value as strings. - `__typename` (string, optional) - `value` (string, optional, nullable) — The decimal value in a string representation - `numericValue` (double, optional, nullable, deprecated) — Deprecated. The float representation of the decimal value. ### IntegerValue A type that represents integer values. - `__typename` (string, optional) - `value` (integer, optional) — The integer value. ### JsonValue A type that represents JSON values. - `__typename` (string, optional) - `value` (map from string to any, optional) — The JSON value. ### ObjectLinkValue A type that represents links to other objects. - `__typename` (string, optional) - `value` (ObjectRef, optional) — The object that this value links to, or an Inaccessible object if not found with the current permission set. ### ObjectLinkListValue A type that represents a list of links to other objects. - `__typename` (string, optional) - `value` (list of ObjectRef, optional) — The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set. ### TextAndUrlValue A type that represents text (string) values with an associated URL. - `__typename` (string, optional) - `url` (string, optional) — The URL associated with the value. Please use `TextValue` if you don't want a URL. - `value` (string, optional) — The text value. It may or may not be an empty string. ### TextValue A type that represents text (string) values. - `__typename` (string, optional) - `value` (string, optional) — The text value. It may or may not be an empty string. ### ArrayValue A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns). - `__typename` (string, optional) - `value` (list of ArrayValueValueItem, optional) ### ArrayCellEvaluationValueValueItem Union of StringCellEvaluationValue, NumberCellEvaluationValue, BooleanCellEvaluationValue, DateCellEvaluationValue, DateTimeCellEvaluationValue, ObjectLinkCellEvaluationValue, ArrayCellEvaluationValue, UnsupportedCellEvaluationValue ### ArrayValueValueItem Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue ## Examples **Request** ```json { "versionId": "etrver_Ax7b2kR9", "columnDefinitions": [ { "name": "Sample ID" }, { "name": "Value" } ], "rows": [ { "cells": [ { "inputValue": { "type": "text_value", "value": "SMPL_001" } }, { "inputValue": { "type": "text_value", "value": "='DataTable'!A1 * 100" }, "format": { "backgroundColor": "#FDC68A" } } ] }, { "cells": [ { "inputValue": { "type": "text_value", "value": "SMPL_002" }, "format": { "link": "https://benchling.com/" } }, { "inputValue": { "type": "text_value", "value": "124.600" } } ] } ] } ``` **Response** ```json { "__typename": "__typename", "caption": { "__typename": "__typename", "formats": [ {} ], "links": [ {} ], "mentions": [ {} ], "text": "text" }, "columnDefinitions": [ { "__typename": "__typename", "isLocked": true, "name": "name", "width": 1.1 } ], "createdAt": "createdAt", "documentParent": { "__typename": "__typename", "id": "id" }, "id": "id", "indentation": 1, "isEvaluated": true, "modifiedAt": "modifiedAt", "modifier": { "__typename": "__typename", "id": "id" }, "name": "name", "rowCount": 1, "rows": [ { "__typename": "__typename", "cells": [ {} ], "rowIndex": 1 } ], "versionMetadata": { "__typename": "__typename", "createdAt": "createdAt", "versionId": "versionId" } } ``` **SDK Code** ```python import requests url = "https://{tenant_name}.benchling.com/api/v3/document-part-unstructured-table/doc_part_id" payload = { "versionId": "etrver_Ax7b2kR9", "columnDefinitions": [{ "name": "Sample ID" }, { "name": "Value" }], "rows": [{ "cells": [ { "inputValue": { "type": "text_value", "value": "SMPL_001" } }, { "inputValue": { "type": "text_value", "value": "='DataTable'!A1 * 100" }, "format": { "backgroundColor": "#FDC68A" } } ] }, { "cells": [{ "inputValue": { "type": "text_value", "value": "SMPL_002" }, "format": { "link": "https://benchling.com/" } }, { "inputValue": { "type": "text_value", "value": "124.600" } }] }] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://{tenant_name}.benchling.com/api/v3/document-part-unstructured-table/doc_part_id'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"versionId":"etrver_Ax7b2kR9","columnDefinitions":[{"name":"Sample ID"},{"name":"Value"}],"rows":[{"cells":[{"inputValue":{"type":"text_value","value":"SMPL_001"}},{"inputValue":{"type":"text_value","value":"=\'DataTable\'!A1 * 100"},"format":{"backgroundColor":"#FDC68A"}}]},{"cells":[{"inputValue":{"type":"text_value","value":"SMPL_002"},"format":{"link":"https://benchling.com/"}},{"inputValue":{"type":"text_value","value":"124.600"}}]}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```