--- title: "Create an App Canvas" method: POST path: "/app-canvases" tags: ["apps"] --- # Create an App Canvas `POST /app-canvases` ## Request - Base URL: `https://{tenant_name}.benchling.com/api/v2` - URL: `https://{tenant_name}.benchling.com/api/v2/app-canvases` - Auth: HTTP bearer Create an App Canvas that a Benchling App can write to and read user interaction from. ## Request body - AppCanvasCreate - `blocks` AppCanvasCreateBaseBlocksItems[] - union - object: BUTTON variant - `type` 'BUTTON', required - `enabled` boolean, nullable - `id` string, required - `text` string, required - object: CHIP variant - `type` 'CHIP', required - `id` string - `value` string, required - object: DROPDOWN variant - `type` 'DROPDOWN', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `dropdownId` string, required - `placeholder` string, nullable - object: DROPDOWN_MULTIVALUE variant - `type` 'DROPDOWN_MULTIVALUE', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `dropdownId` string, required - `placeholder` string, nullable - object: FILE_UPLOAD variant - `type` 'FILE_UPLOAD', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `fileTypes` string[] - `maxFiles` integer - object: MARKDOWN variant - `type` 'MARKDOWN', required - `id` string - `value` string, required - object: SEARCH_INPUT variant - `type` 'SEARCH_INPUT', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `itemType` 'dna_sequence' | 'dna_oligo' | 'aa_sequence' | 'custom_entity' | 'mixture' | 'box' | 'container' | 'location' | 'plate' | 'worklist', required - `placeholder` string, nullable - `schemaId` string, nullable, required - object: SEARCH_INPUT_MULTIVALUE variant - `type` 'SEARCH_INPUT_MULTIVALUE', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `itemType` 'dna_sequence' | 'dna_oligo' | 'aa_sequence' | 'custom_entity' | 'mixture' | 'box' | 'container' | 'location' | 'plate' | 'worklist', required - `placeholder` string, nullable - `schemaId` string, nullable, required - object: SECTION variant - `type` 'SECTION', required - `children` SectionUiBlockCreateChildrenItems[], 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 - object: SELECTOR_INPUT variant - `type` 'SELECTOR_INPUT', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `options` string[], required - `placeholder` string, nullable - object: SELECTOR_INPUT_MULTIVALUE variant - `type` 'SELECTOR_INPUT_MULTIVALUE', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `options` string[], required - `placeholder` string, nullable - object: TABLE variant - `type` 'TABLE', required - `enabled` boolean, nullable - `id` string, required - `name` string, required: Display name for the table block, to be shown in the UI - `source` union, required - object: DATASET variant - `type` 'DATASET', required: Discriminator value: DATASET - `datasetId` string, nullable, required: `datasetId` of an uploaded dataset (see [Create Data Frame endpoint](https://docs.benchling.com/docs/api/v2/benchling-api/data-frames/create-data-frame)). 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. - object: DATA_FRAME variant - `type` 'DATA_FRAME', required: Discriminator value: DATA_FRAME - `dataFrameId` string, nullable, required: `dataFrameId` of an uploaded data frame (see [Create Data Frame endpoint](https://docs.benchling.com/docs/api/v2/benchling-api/data-frames/create-data-frame)). Note: Canvas tables currently support only text-type columns. - object: TEXT_INPUT variant - `type` 'TEXT_INPUT', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `placeholder` string, nullable - `data` string, 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: 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: Identifier of the feature defined in Benchling App Manifest this canvas corresponds to. - `resourceId` string: Identifier of the resource object to attach canvas to. - `sessionId` string, nullable: Identifier of a session. If specified, app status messages from the session will be reported in the canvas. - `appId` string: Identifier of the app owning this canvas. For backwards compatibility, this property will be temporarily optional until the requisite time window for breaking changes in beta endpoints has passed. ## Response `201` Created - AppCanvas - `blocks` AppCanvasBlocksItems[] - union - object: BUTTON variant - `type` 'BUTTON', required - `enabled` boolean, nullable - `id` string, required - `text` string, required - object: CHIP variant - `type` 'CHIP', required - `id` string - `value` string, required - object: DROPDOWN variant - `type` 'DROPDOWN', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `dropdownId` string, required - `placeholder` string, nullable - object: DROPDOWN_MULTIVALUE variant - `type` 'DROPDOWN_MULTIVALUE', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `dropdownId` string, required - `placeholder` string, nullable - object: FILE_UPLOAD variant - `type` 'FILE_UPLOAD', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `fileTypes` string[] - `maxFiles` integer - object: MARKDOWN variant - `type` 'MARKDOWN', required: Discriminator value: MARKDOWN - `id` string - `value` string, required - object: SEARCH_INPUT variant - `type` 'SEARCH_INPUT', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `itemType` 'dna_sequence' | 'dna_oligo' | 'aa_sequence' | 'custom_entity' | 'mixture' | 'box' | 'container' | 'location' | 'plate' | 'worklist', required - `placeholder` string, nullable - `schemaId` string, nullable, required - object: SEARCH_INPUT_MULTIVALUE variant - `type` 'SEARCH_INPUT_MULTIVALUE', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `itemType` 'dna_sequence' | 'dna_oligo' | 'aa_sequence' | 'custom_entity' | 'mixture' | 'box' | 'container' | 'location' | 'plate' | 'worklist', required - `placeholder` string, nullable - `schemaId` string, nullable, required - object: SECTION variant - `type` 'SECTION', required - `children` SectionUiBlockChildrenItems[], 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 - object: SELECTOR_INPUT variant - `type` 'SELECTOR_INPUT', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `options` string[], required - `placeholder` string, nullable - object: SELECTOR_INPUT_MULTIVALUE variant - `type` 'SELECTOR_INPUT_MULTIVALUE', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string[], nullable, required - `options` string[], required - `placeholder` string, nullable - object: TABLE variant - `type` 'TABLE', required - `enabled` boolean, nullable - `id` string, required - `name` string, required: Display name for the table block, to be shown in the UI - `source` union, required - object: DATASET variant - `type` 'DATASET', required: Discriminator value: DATASET - `datasetId` string, nullable, required: `datasetId` of an uploaded dataset (see [Create Data Frame endpoint](https://docs.benchling.com/docs/api/v2/benchling-api/data-frames/create-data-frame)). 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. - object: DATA_FRAME variant - `type` 'DATA_FRAME', required: Discriminator value: DATA_FRAME - `dataFrameId` string, nullable, required: `dataFrameId` of an uploaded data frame (see [Create Data Frame endpoint](https://docs.benchling.com/docs/api/v2/benchling-api/data-frames/create-data-frame)). Note: Canvas tables currently support only text-type columns. - object: TEXT_INPUT variant - `type` 'TEXT_INPUT', required - `enabled` boolean, nullable - `id` string, required - `label` string, nullable - `required` boolean, 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. - `value` string, nullable, required - `placeholder` string, nullable - `archiveRecord` AppCanvasArchiveRecord - `reason` 'Other': Reason that canvases are being archived. Actual reason enum varies by tenant. - `data` string, 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: 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: Identifier of the feature defined in Benchling App Manifest this canvas corresponds to. - `resourceId` string: Identifier of the resource object to attach canvas to. - `sessionId` string, nullable: Identifier of a session. If specified, app status messages from the session will be reported in the canvas. - `app` AppCanvasApp - `id` string: The id of the Benchling app. - `id` string ## Other responses - `400`: Bad Request - `403`: Forbidden --- [API](https://skmtc.dev/benchling/apis/benchling-api-2.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api-2/revisions/01d2fa8523cd?raw)