---
title: "Batch update AppCanvas"
method: PATCH
path: "/api/v3/app-canvas:batch-update"
tags: ["App Canvas"]
---

# Batch update AppCanvas

`PATCH /api/v3/app-canvas:batch-update`

## Request

- Base URL: `https://{tenant_name}.benchling.com`
- URL: `https://{tenant_name}.benchling.com/api/v3/app-canvas:batch-update`
- Auth: HTTP bearer

Batch update AppCanvas synchronously in one transaction. Maximum 25 items per request.

## Headers

- `EARLY-ACCESS` string

## Request body

- object
  - `items` UpdateAppCanvasInputWithPathParams[], required
    - `archiveReason` string: Why it is being archived. Required when `archived` is `true`, and not allowed when unarchiving.
    - `archived` boolean: Set to `true` to archive or `false` to unarchive it. Archiving requires `archiveReason`.
    - `blocks` AppCanvasUiBlockInput[]: Replacement list of UI blocks for the canvas layout.
      - union
        - object: BUTTON variant
          - `type` 'BUTTON', required: Discriminator value: BUTTON
          - `enabled` boolean
          - `id` string, required
          - `text` string, required
        - object: CHIP variant
          - `type` 'CHIP', required: Discriminator value: CHIP
          - `id` string, required
          - `value` string, required
        - object: DROPDOWN variant
          - `type` 'DROPDOWN', required: Discriminator value: DROPDOWN
          - `dropdownId` string, required
          - `enabled` boolean
          - `id` string, required
          - `label` string
          - `placeholder` string
          - `required` boolean
          - `value` string
        - object: DROPDOWN_MULTIVALUE variant
          - `type` 'DROPDOWN_MULTIVALUE', required: Discriminator value: DROPDOWN_MULTIVALUE
          - `dropdownId` string, required
          - `enabled` boolean
          - `id` string, required
          - `label` string
          - `placeholder` string
          - `required` boolean
          - `value` string[]
        - object: FILE_UPLOAD variant
          - `type` 'FILE_UPLOAD', required: Discriminator value: FILE_UPLOAD
          - `enabled` boolean
          - `fileTypes` string[]
          - `id` string, required
          - `label` string
          - `maxFiles` integer
          - `required` boolean
          - `value` string[]
        - object: MARKDOWN variant
          - `type` 'MARKDOWN', required: Discriminator value: MARKDOWN
          - `id` string, required
          - `value` string, required
        - object: SEARCH_INPUT variant
          - `type` 'SEARCH_INPUT', required: Discriminator value: SEARCH_INPUT
          - `enabled` boolean
          - `id` string, required
          - `itemType` 'DNA_SEQUENCE' | 'DNA_OLIGO' | 'AA_SEQUENCE' | 'CUSTOM_ENTITY' | 'MIXTURE' | 'BOX' | 'CONTAINER' | 'LOCATION' | 'PLATE' | 'WORKLIST', required
          - `label` string
          - `placeholder` string
          - `required` boolean
          - `schemaId` string
          - `value` string
        - object: SEARCH_INPUT_MULTIVALUE variant
          - `type` 'SEARCH_INPUT_MULTIVALUE', required: Discriminator value: SEARCH_INPUT_MULTIVALUE
          - `enabled` boolean
          - `id` string, required
          - `itemType` 'DNA_SEQUENCE' | 'DNA_OLIGO' | 'AA_SEQUENCE' | 'CUSTOM_ENTITY' | 'MIXTURE' | 'BOX' | 'CONTAINER' | 'LOCATION' | 'PLATE' | 'WORKLIST', required
          - `label` string
          - `placeholder` string
          - `required` boolean
          - `schemaId` string
          - `value` string[]
        - object: SECTION variant
          - `type` 'SECTION', required
          - `children` UiBlockLeafNodeInput[], required
            - union
              - …
          - `id` string, required
        - object: SELECTOR_INPUT variant
          - `type` 'SELECTOR_INPUT', required: Discriminator value: SELECTOR_INPUT
          - `enabled` boolean
          - `id` string, required
          - `label` string
          - `options` string[], required
          - `placeholder` string
          - `required` boolean
          - `value` string
        - object: SELECTOR_INPUT_MULTIVALUE variant
          - `type` 'SELECTOR_INPUT_MULTIVALUE', required: Discriminator value: SELECTOR_INPUT_MULTIVALUE
          - `enabled` boolean
          - `id` string, required
          - `label` string
          - `options` string[], required
          - `placeholder` string
          - `required` boolean
          - `value` string[]
        - object: TABLE variant
          - `type` 'TABLE', required
          - `dataFrameId` string, required: Data frame ID backing the table.
          - `enabled` boolean
          - `id` string, required
          - `name` string, required
        - object: TEXT_INPUT variant
          - `type` 'TEXT_INPUT', required: Discriminator value: TEXT_INPUT
          - `enabled` boolean
          - `id` string, required
          - `label` string
          - `placeholder` string
          - `required` boolean
          - `value` string
    - `data` string, nullable: JSON string (max 5 KiB) of app-managed data not rendered in the canvas UI.
    - `enabled` boolean: Whether the canvas is interactable. When false, all blocks are disabled regardless of their individual enabled settings.
    - `id` string, required
    - `sessionId` string, nullable: App session ID whose status messages are shown in the canvas.

## Response `200`

OK

- AppCanvasBatchupdateResponse200
  - `items` AppCanvas[], required
    - `__typename` string
    - `app` IAppInstallationRef
      - `__typename` string
      - `id` string, api_id
    - `archiveReason` string, nullable
    - `archived` boolean
    - `blocks` AppCanvasUiBlock[]
      - union: A union of all UI block types that can appear on an app canvas. Each block type provides different interactive or display capabilities within the canvas surface.
        - object: A button block that triggers an app interaction when clicked.
          - `__typename` 'ButtonUiBlock', required: Discriminator value: ButtonUiBlock
          - `enabled` boolean, nullable
          - `id` string
          - `text` string
        - object: A chip block that displays a short piece of information.
          - `__typename` 'ChipUiBlock', required: Discriminator value: ChipUiBlock
          - `id` string
          - `value` string
        - object: A multi-select dropdown block backed by a Benchling dropdown registry.
          - `__typename` 'DropdownMultiValueUiBlock', required: Discriminator value: DropdownMultiValueUiBlock
          - `dropdownId` string
          - `enabled` boolean, nullable
          - `id` string
          - `label` string, nullable
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `value` string[], nullable
        - object: A dropdown block backed by a Benchling dropdown registry.
          - `__typename` 'DropdownUiBlock', required: Discriminator value: DropdownUiBlock
          - `dropdownId` string
          - `enabled` boolean, nullable
          - `id` string
          - `label` string, nullable
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `value` string, nullable
        - object: A file upload block that accepts one or more file attachments.
          - `__typename` 'FileUploadUiBlock', required: Discriminator value: FileUploadUiBlock
          - `enabled` boolean, nullable
          - `fileTypes` string[], nullable
          - `id` string
          - `label` string, nullable
          - `maxFiles` integer, nullable
          - `required` boolean, nullable
          - `value` string[], nullable
        - object: A block that renders Markdown content.
          - `__typename` 'MarkdownUiBlock', required: Discriminator value: MarkdownUiBlock
          - `id` string
          - `value` string
        - object: A multi-select search input block for selecting multiple Benchling entities.
          - `__typename` 'SearchInputMultiValueUiBlock', required: Discriminator value: SearchInputMultiValueUiBlock
          - `enabled` boolean, nullable
          - `id` string
          - `itemType` 'DNA_SEQUENCE' | 'DNA_OLIGO' | 'AA_SEQUENCE' | 'CUSTOM_ENTITY' | 'MIXTURE' | 'BOX' | 'CONTAINER' | 'LOCATION' | 'PLATE' | 'WORKLIST'
          - `label` string, nullable
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `schemaId` string, nullable
          - `value` string[], nullable
        - object: A search input block for selecting a single Benchling entity.
          - `__typename` 'SearchInputUiBlock', required: Discriminator value: SearchInputUiBlock
          - `enabled` boolean, nullable
          - `id` string
          - `itemType` 'DNA_SEQUENCE' | 'DNA_OLIGO' | 'AA_SEQUENCE' | 'CUSTOM_ENTITY' | 'MIXTURE' | 'BOX' | 'CONTAINER' | 'LOCATION' | 'PLATE' | 'WORKLIST'
          - `label` string, nullable
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `schemaId` string, nullable
          - `value` string, nullable
        - object: A section block that groups child blocks together. Children are leaf blocks only.
          - `__typename` string, required
          - `children` UiBlockLeafNode[]
            - union: A union of all UI block types that can appear in a section block. A subset of all blocks.
              - …
          - `id` string
        - object: A multi-select selector input block with predefined options.
          - `__typename` 'SelectorInputMultiValueUiBlock', required: Discriminator value: SelectorInputMultiValueUiBlock
          - `enabled` boolean, nullable
          - `id` string
          - `label` string, nullable
          - `options` string[]
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `value` string[], nullable
        - object: A selector input block with predefined options.
          - `__typename` 'SelectorInputUiBlock', required: Discriminator value: SelectorInputUiBlock
          - `enabled` boolean, nullable
          - `id` string
          - `label` string, nullable
          - `options` string[]
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `value` string, nullable
        - object: A table block that displays tabular data from a dataset or data frame.
          - `__typename` string, required
          - `dataFrameId` string
          - `enabled` boolean, nullable
          - `id` string
          - `name` string
        - object: A text input block that accepts freeform user text.
          - `__typename` 'TextInputUiBlock', required: Discriminator value: TextInputUiBlock
          - `enabled` boolean, nullable
          - `id` string
          - `label` string, nullable
          - `placeholder` string, nullable
          - `required` boolean, nullable
          - `value` string, nullable
    - `createdAt` string, datetime
    - `data` string, nullable
    - `enabled` boolean
    - `featureId` string, nullable
    - `id` string
    - `modifiedAt` string, datetime
    - `resourceId` string
    - `sessionId` string, nullable

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/c9f087b98b8b?raw)