--- title: "Create AppCanvas" method: POST path: "/api/v3/app-canvas" tags: ["App Canvas"] --- # Create AppCanvas `POST /api/v3/app-canvas` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/app-canvas` - Auth: HTTP bearer Create AppCanvas. ## Headers - `EARLY-ACCESS` string ## Request body - CreateAppCanvasInput - `appId` string, required: API ID of the Benchling App that owns this canvas. - `blocks` AppCanvasUiBlockInput[], required: UI blocks defining the canvas layout and interactivity. - 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 - object: BUTTON variant - … - object: CHIP variant - … - object: DROPDOWN variant - … - object: DROPDOWN_MULTIVALUE variant - … - object: FILE_UPLOAD variant - … - object: MARKDOWN variant - … - object: SEARCH_INPUT variant - … - object: SEARCH_INPUT_MULTIVALUE variant - … - object: SELECTOR_INPUT variant - … - object: SELECTOR_INPUT_MULTIVALUE variant - … - object: TEXT_INPUT variant - … - `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: Optional 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. - `featureId` string, required: Feature ID from the app manifest that this canvas corresponds to. - `resourceId` string, required: Identifier of the resource object to attach the canvas to. - `sessionId` string: Optional app session ID whose status messages are shown in the canvas. ## Response `201` Created - AppCanvas: Represents a Benchling App canvas, an embedded UI surface that apps use to render custom interactive content within notebook entries, entry templates, assay runs, or app homepages. Each canvas belongs to a single app and contains a list of UI blocks that define the canvas layout and interactivity. - `__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. - object: A button block that triggers an app interaction when clicked. - … - object: A chip block that displays a short piece of information. - … - object: A multi-select dropdown block backed by a Benchling dropdown registry. - … - object: A dropdown block backed by a Benchling dropdown registry. - … - object: A file upload block that accepts one or more file attachments. - … - object: A block that renders Markdown content. - … - object: A multi-select search input block for selecting multiple Benchling entities. - … - object: A search input block for selecting a single Benchling entity. - … - object: A multi-select selector input block with predefined options. - … - object: A selector input block with predefined options. - … - object: A text input block that accepts freeform user text. - … - `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)