> 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 App Canvas

PATCH https://{tenant_name}.benchling.com/api/v2/app-canvases/{canvas_id}
Content-Type: application/json

Update App Canvas

Reference: https://docs.benchling.com/docs/api/v2/benchling-api/apps/update-app-canvas

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `canvas_id` (string, required)

### Body (application/json)

This endpoint expects an AppCanvasUpdate.

- `blocks` (list of AppCanvasUpdateBaseBlocksItems, optional)
- `data` (string, optional, nullable) — Additional data to associate with the canvas. Can be useful for persisting data associated with the canvas but won't be rendered to the user. If specified, it must be valid JSON in string format less than 5kb in total.
- `enabled` (boolean, optional) — Overall control for whether the canvas is interactable or not. If `false`, every block is disabled and will override the individual block's `enabled` property. If `true` or absent, the interactivity status will defer to the block's `enabled` property.
- `featureId` (string, optional) — Identifier of the feature defined in Benchling App Manifest this canvas corresponds to.
- `resourceId` (string, optional) — Identifier of the resource object to attach canvas to.
- `sessionId` (string, optional, nullable) — Identifier of a session. If specified, app status messages from the session will be reported in the canvas.

## Response

### 200

OK

- `blocks` (list of AppCanvasBlocksItems, optional)
- `archiveRecord` (AppCanvasArchiveRecord, optional, nullable)
- `data` (string, optional, nullable) — Additional data to associate with the canvas. Can be useful for persisting data associated with the canvas but won't be rendered to the user. If specified, it must be valid JSON in string format less than 5kb in total.
- `enabled` (boolean, optional) — Overall control for whether the canvas is interactable or not. If `false`, every block is disabled and will override the individual block's `enabled` property. If `true` or absent, the interactivity status will defer to the block's `enabled` property.
- `featureId` (string, optional) — Identifier of the feature defined in Benchling App Manifest this canvas corresponds to.
- `resourceId` (string, optional) — Identifier of the resource object to attach canvas to.
- `sessionId` (string, optional, nullable) — Identifier of a session. If specified, app status messages from the session will be reported in the canvas.
- `app` (AppCanvasApp, optional)
- `id` (string, optional)

## Errors

### 403 Forbidden Error

Forbidden

- `error` (ForbiddenErrorError, optional)

### 404 Not Found Error

Not Found

- `error` (NotFoundErrorError, optional)

## Types

### AppCanvasUpdateBaseBlocksItems

- `type`: `BUTTON` (BUTTON)
  - `id` (string, required)
  - `text` (string, required)
  - `enabled` (boolean, optional, nullable)
- `type`: `CHIP` (CHIP)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `DROPDOWN` (DROPDOWN)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `DROPDOWN_MULTIVALUE` (DROPDOWN_MULTIVALUE)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `FILE_UPLOAD` (FILE_UPLOAD)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `fileTypes` (list of string, optional)
  - `label` (string, optional, nullable)
  - `maxFiles` (integer, optional, default: 10)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `MARKDOWN` (MARKDOWN)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `SEARCH_INPUT` (SEARCH_INPUT)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SEARCH_INPUT_MULTIVALUE` (SEARCH_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SECTION` (SECTION)
  - `children` (list of SectionUiBlockUpdateChildrenItems, required)
  - `id` (string, optional)
- `type`: `SELECTOR_INPUT` (SELECTOR_INPUT)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SELECTOR_INPUT_MULTIVALUE` (SELECTOR_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `TABLE` (TABLE)
  - `id` (string, required)
  - `name` (string, required) — Display name for the table block, to be shown in the UI
  - `source` (TableUiBlockSource, required)
  - `enabled` (boolean, optional, nullable)
- `type`: `TEXT_INPUT` (TEXT_INPUT)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.

### AppCanvasBlocksItems

- `type`: `BUTTON` (BUTTON)
  - `id` (string, required)
  - `text` (string, required)
  - `enabled` (boolean, optional, nullable)
- `type`: `CHIP` (CHIP)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `DROPDOWN` (DROPDOWN)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `DROPDOWN_MULTIVALUE` (DROPDOWN_MULTIVALUE)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `FILE_UPLOAD` (FILE_UPLOAD)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `fileTypes` (list of string, optional)
  - `label` (string, optional, nullable)
  - `maxFiles` (integer, optional, default: 10)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `MARKDOWN` (MARKDOWN)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `SEARCH_INPUT` (SEARCH_INPUT)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SEARCH_INPUT_MULTIVALUE` (SEARCH_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SECTION` (SECTION)
  - `children` (list of SectionUiBlockChildrenItems, required)
  - `id` (string, optional)
- `type`: `SELECTOR_INPUT` (SELECTOR_INPUT)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SELECTOR_INPUT_MULTIVALUE` (SELECTOR_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `TABLE` (TABLE)
  - `id` (string, required)
  - `name` (string, required) — Display name for the table block, to be shown in the UI
  - `source` (TableUiBlockSource, required)
  - `enabled` (boolean, optional, nullable)
- `type`: `TEXT_INPUT` (TEXT_INPUT)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.

### AppCanvasArchiveRecord

- `reason` (enum, optional) — Reason that canvases are being archived. Actual reason enum varies by tenant.
  - Allowed values: `Other`

### AppCanvasApp

- `id` (string, optional) — The id of the Benchling app.

### ForbiddenErrorError

- `invalidId` (string, optional)
- `message` (string, optional)
- `type` (string, optional)
- `userMessage` (string, optional)

### NotFoundErrorError

- `message` (string, optional)
- `type` (enum, optional)
  - Allowed values: `invalid_request_error`
- `userMessage` (string, optional)
- `invalidId` (string, optional)

### SectionUiBlockUpdateChildrenItems

- `type`: `BUTTON` (BUTTON)
  - `id` (string, required)
  - `text` (string, required)
  - `enabled` (boolean, optional, nullable)
- `type`: `CHIP` (CHIP)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `DROPDOWN` (DROPDOWN)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `DROPDOWN_MULTIVALUE` (DROPDOWN_MULTIVALUE)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `FILE_UPLOAD` (FILE_UPLOAD)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `fileTypes` (list of string, optional)
  - `label` (string, optional, nullable)
  - `maxFiles` (integer, optional, default: 10)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `MARKDOWN` (MARKDOWN)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `SEARCH_INPUT` (SEARCH_INPUT)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SEARCH_INPUT_MULTIVALUE` (SEARCH_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SELECTOR_INPUT` (SELECTOR_INPUT)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SELECTOR_INPUT_MULTIVALUE` (SELECTOR_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `TEXT_INPUT` (TEXT_INPUT)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.

### TableUiBlockSource

- `type`: `DATASET` (DATASET)
  - `datasetId` (string, required, nullable, deprecated) — `datasetId` of an uploaded dataset (see [Create Data Frame endpoint](https://benchling.com/api/v2-beta/reference#/Data%20Frames)). Note: Canvas tables currently support only text-type columns. Datasets are currently undergoing re-work. datasetId will refer to a DataFrame until Dataset APIs are stable. Prefer `TableUiBlockDataFrameSource` meanwhile.
- `type`: `DATA_FRAME` (DATA_FRAME)
  - `dataFrameId` (string, required, nullable) — `dataFrameId` of an uploaded data frame (see [Create Data Frame endpoint](https://benchling.com/api/v2-beta/reference#/Data%20Frames)). Note: Canvas tables currently support only text-type columns.

### SectionUiBlockChildrenItems

- `type`: `BUTTON` (BUTTON)
  - `id` (string, required)
  - `text` (string, required)
  - `enabled` (boolean, optional, nullable)
- `type`: `CHIP` (CHIP)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `DROPDOWN` (DROPDOWN)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `DROPDOWN_MULTIVALUE` (DROPDOWN_MULTIVALUE)
  - `dropdownId` (string, required)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `FILE_UPLOAD` (FILE_UPLOAD)
  - `id` (string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `fileTypes` (list of string, optional)
  - `label` (string, optional, nullable)
  - `maxFiles` (integer, optional, default: 10)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `MARKDOWN` (MARKDOWN)
  - `value` (string, required)
  - `id` (string, optional)
- `type`: `SEARCH_INPUT` (SEARCH_INPUT)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SEARCH_INPUT_MULTIVALUE` (SEARCH_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `itemType` (enum, required)
    - Allowed values: `dna_sequence`, `dna_oligo`, `aa_sequence`, `custom_entity`, `mixture`, `box`, `container`, `location`, `plate`, `worklist`
  - `schemaId` (string, required, nullable)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SELECTOR_INPUT` (SELECTOR_INPUT)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `SELECTOR_INPUT_MULTIVALUE` (SELECTOR_INPUT_MULTIVALUE)
  - `id` (string, required)
  - `options` (list of string, required)
  - `value` (list of string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.
- `type`: `TEXT_INPUT` (TEXT_INPUT)
  - `id` (string, required)
  - `value` (string, required, nullable)
  - `enabled` (boolean, optional, nullable)
  - `label` (string, optional, nullable)
  - `placeholder` (string, optional, nullable)
  - `required` (boolean, optional, nullable) — When true, the user must provide a value before the app can proceed. Block must specify a label if required is set to true.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "blocks": [
    {
      "type": "BUTTON",
      "id": "user_defined_id",
      "text": "Click me to submit",
      "enabled": true
    }
  ],
  "archiveRecord": {
    "reason": "Other"
  },
  "data": "{\"key\": \"value\"}",
  "enabled": true,
  "featureId": "string",
  "resourceId": "string",
  "sessionId": "sesn_SwKtkgB5",
  "app": {
    "id": "string"
  },
  "id": "cnvs_Q4mPJ34a"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/app-canvases/cnvs_Q4mPJ34a"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v2/app-canvases/cnvs_Q4mPJ34a';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```