> 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.

# Create an App Canvas

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

Create an App Canvas that a Benchling App can write to and read user interaction from.


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

## Authentication

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

## Request

### Body (application/json)

This endpoint expects an AppCanvasCreate.

- `appId` (string, optional) — 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.
- `blocks` (list of AppCanvasCreateBaseBlocksItems, 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

### 201

Created

- `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

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

### 403 Forbidden Error

Forbidden

- `error` (ForbiddenErrorError, optional)

## Types

### AppCanvasCreateBaseBlocksItems

- `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 SectionUiBlockCreateChildrenItems, 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.

### BadRequestErrorError

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

### ForbiddenErrorError

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

### SectionUiBlockCreateChildrenItems

- `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
{
  "appId": "string",
  "blocks": [
    {
      "type": "BUTTON",
      "id": "user_defined_id",
      "text": "Click me to submit"
    }
  ],
  "featureId": "string",
  "resourceId": "string"
}
```

**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"

payload = {
    "appId": "string",
    "blocks": [
        {
            "type": "BUTTON",
            "id": "user_defined_id",
            "text": "Click me to submit"
        }
    ],
    "featureId": "string",
    "resourceId": "string"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v2/app-canvases';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"appId":"string","blocks":[{"type":"BUTTON","id":"user_defined_id","text":"Click me to submit"}],"featureId":"string","resourceId":"string"}'
};

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