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

# List LegacyAppInstallation items

GET https://{tenant_name}.benchling.com/api/v3/legacy-app-installation/items

List LegacyAppInstallation items.

Reference: https://docs.benchling.com/docs/api/benchling-api/legacy-app-installation/list

## Authentication

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

## Request

### Query parameters

- `archiveReason.anyOf` (string, optional) — Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
- `archived.anyOf` (boolean, optional) — If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
- `createdAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
- `createdAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
- `createdAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. \< 2017-04-30.
- `createdAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. \<= 2017-04-30.
- `creator.anyOf` (string, optional) — Restricts results to those created by any of the specified user IDs. Comma-separated list.
- `id.anyOf` (string, optional) — Restricts results to those matching any of the specified IDs. Comma-separated list.
- `modifiedAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
- `modifiedAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
- `modifiedAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. \< 2017-04-30.
- `modifiedAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. \<= 2017-04-30.
- `name.anyOf` (string, optional) — Restricts results to those that match any of the specified names. Case insensitive. Warning - this filter can be non-performant due to case insensitivity. Ensure only one name filter is used at a time. Comma-separated list.
- `name.anyOf.caseSensitive` (string, optional) — Restricts results to those that match any of the specified names. Case sensitive. Ensure only one name filter is used at a time. Comma-separated list.
- `nextToken` (string, optional) — Token for pagination
- `omit` (string, optional) — Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
- `pageSize` (integer, optional) — Number of results to return. Defaults to 50, maximum of 100.
- `returning` (string, optional) — Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
- `sort` (enum, optional, default: modifiedAt:desc) — Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.
  - Allowed values: `createdAt:asc`, `createdAt:desc`, `modifiedAt:asc`, `modifiedAt:desc`

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

## Response

### 200

OK

- `items` (list of LegacyAppInstallation, optional)
- `nextToken` (string, optional)

## Errors

### 400 Legacy App Installation List Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Legacy App Installation List Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Legacy App Installation List Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Legacy App Installation List Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Legacy App Installation List Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### LegacyAppInstallation

Represents a legacy (pre-App Store) Benchling App installation on a tenant. Legacy apps are configured directly with webhook URLs and configuration specs rather than through app definition versions. This type is maintained for backward compatibility with older app integrations. For new apps, see `AppInstallation`.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `configurationSpecs` (list of AppConfigOption, optional)
- `configurationValues` (string, optional)
- `createdAt` (string, optional, nullable)
- `creator` (PrincipalRef, optional, nullable)
- `description` (string, optional, nullable)
- `featureSpecs` (list of LegacyAppInstallationFeatureSpecsItem, optional)
- `featureValues` (list of AssayRunFeatureValue, optional)
- `id` (string, optional)
- `messageSubscriptions` (list of AppMessageSubscription, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional)
- `publicKey` (string, optional, nullable)
- `versionNumber` (string, optional, nullable)
- `webhookUrl` (string, optional, nullable)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### AppConfigOption

Defines a configuration option in an app's configuration schema. Each option has a name, optional description, and a configSpec defining the expected value type and validation.

- `__typename` (string, optional)
- `configSpec` (AppConfigOptionConfigSpec, optional) — Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, ArrayAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec
- `description` (string, optional, nullable)
- `name` (string, optional)

### PrincipalRef

- `__typename` (string, optional)
- `id` (string, optional)

### LegacyAppInstallationFeatureSpecsItem

Union of CanvasFeatureSpec, AssayRunFeatureSpec, AppHomepageFeatureSpec

### AssayRunFeatureValue

Links an app's assay run feature to a specific resource (typically a run schema) on a tenant. The featureId identifies the feature from the app definition, and resourceId references the tenant-specific resource it's bound to.

- `__typename` (string, optional)
- `featureId` (string, optional) — Developer-specified feature ID as defined in the app manifest / app definition version
- `resourceId` (string, optional, nullable)

### AppMessageSubscription

Represents an app's subscription to a specific event type, specifying the event type and how notifications should be delivered (see `DeliveryMethod`).

- `__typename` (string, optional)
- `deliveryMethod` (enum, optional)
  - Allowed values: `WEBHOOK`, `WEBHOOK_INTERNAL`
- `type` (enum, optional)
  - Allowed values: `V2_BETA_CANVAS_CREATED`, `V2_CANVAS_CREATED`, `V2_CANVAS_USER_INTERACTED`, `V2_CANVAS_INITIALIZED`, `V2_APP_ACTIVATE_REQUESTED`, `V2_APP_DEACTIVATED`, `V2_APP_INSTALLED`, `V2_BETA_APP_CONFIGURATION_UPDATED`, `V2_ASSAY_RUN_CREATED`, `V2_ASSAY_RUN_UPDATED_FIELDS`, `V2_ENTITY_REGISTERED`, `V2_ENTRY_CREATED`, `V2_ENTRY_UPDATED_FIELDS`, `V2_ENTRY_UPDATED_REVIEW_RECORD`, `V2_REQUEST_CREATED`, `V2_REQUEST_UPDATED_FIELDS`, `V2_REQUEST_UPDATED_STATUS`, `V2_WORKFLOW_TASK_GROUP_CREATED`, `V2_WORKFLOW_TASK_GROUP_MAPPING_COMPLETED`, `V2_WORKFLOW_TASK_GROUP_UPDATED_WATCHERS`, `V2_WORKFLOW_TASK_CREATED`, `V2_WORKFLOW_TASK_UPDATED_ASSIGNEE`, `V2_WORKFLOW_TASK_UPDATED_SCHEDULED_ON`, `V2_WORKFLOW_TASK_UPDATED_STATUS`, `V2_WORKFLOW_TASK_UPDATED_FIELDS`, `V2_WORKFLOW_OUTPUT_CREATED`, `V2_WORKFLOW_OUTPUT_UPDATED_FIELDS`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_RUNNING`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_PENDING`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_SUCCEEDED`, `V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_FAILED`, `V3_CUSTOM_ENTITY_CREATED`, `V3_CUSTOM_ENTITY_UPDATED`, `V3_DNA_OLIGO_CREATED`, `V3_DNA_OLIGO_UPDATED`, `V3_DNA_SEQUENCE_CREATED`, `V3_DNA_SEQUENCE_UPDATED`, `V3_ENTRY_CREATED`, `V3_PROJECT_CREATED`, `V3_PROJECT_UPDATED`, `V3_RNA_OLIGO_CREATED`, `V3_RNA_OLIGO_UPDATED`, `V3_RNA_SEQUENCE_CREATED`, `V3_RNA_SEQUENCE_UPDATED`, `V3_RUN_CREATED`

### AppConfigOptionConfigSpec

Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, ArrayAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec

### CanvasFeatureSpec

Defines a canvas feature for a Benchling App, which provides an embedded UI surface within entries or templates. Canvases allow apps to render custom interactive content.

- `__typename` (string, optional)
- `featureId` (string, optional)
- `locations` (list of enum, optional, nullable)
  - Allowed values: `ENTRY`, `ENTRY_TEMPLATE`, `APP_HOME`
- `name` (string, optional)

### AssayRunFeatureSpec

Defines an assay run feature for a Benchling App, allowing the app to process or generate lab automation run data.

- `__typename` (string, optional)
- `featureId` (string, optional)
- `name` (string, optional)

### AppHomepageFeatureSpec

Defines a homepage feature for a Benchling App, providing a dedicated landing page within the Benchling application for the app's functionality.

- `__typename` (string, optional)
- `featureId` (string, optional)
- `name` (string, optional)

### BooleanAppConfigSpec

Specifies that an app configuration field should accept a boolean value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### IntegerAppConfigSpec

Specifies that an app configuration field should accept an integer value.

- `__typename` (string, optional)
- `enum` (list of integer, optional, nullable) — Optional enum constraint — if present, the value must be one of these integers.
- `requiredConfig` (boolean, optional, nullable)

### FloatAppConfigSpec

Specifies that an app configuration field should accept a floating-point number.

- `__typename` (string, optional)
- `enum` (list of double, optional, nullable) — Optional enum constraint — if present, the value must be one of these floats.
- `requiredConfig` (boolean, optional, nullable)

### TextAppConfigSpec

Specifies that an app configuration field should accept a text string.

- `__typename` (string, optional)
- `enum` (list of string, optional, nullable) — Optional enum constraint — if present, the value must be one of these strings.
- `requiredConfig` (boolean, optional, nullable)

### SecureTextAppConfigSpec

Specifies that an app configuration field should accept secure (encrypted) text. Used for sensitive data like API keys or credentials.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### DateAppConfigSpec

Specifies that an app configuration field should accept a date value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### DateTimeAppConfigSpec

Specifies that an app configuration field should accept a datetime value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### JsonAppConfigSpec

Specifies that an app configuration field should accept a JSON value.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### ArrayAppConfigSpec

Specifies that an app configuration field should accept an array of values.

- `__typename` (string, optional)
- `elementDefinition` (list of ArrayAppConfigOption, optional) — Defines the named config options allowed within this array and their type constraints.
- `maxElements` (integer, optional, nullable) — Maximum number of elements allowed in the array (1-500); null means no maximum.
- `minElements` (integer, optional, nullable) — Minimum number of elements allowed in the array (0-500); null means no minimum.
- `requiredConfig` (boolean, optional, nullable)

### DropdownAppConfigSpec

Specifies that an app configuration field should be a dropdown with predefined options.

- `__typename` (string, optional)
- `options` (list of AppConfigDropdownOption, optional, nullable)
- `requiredConfig` (boolean, optional, nullable)

### EntitySchemaAppConfigSpec

Specifies that an app configuration field should reference an entity schema. Kept separate from SchemaAppConfigSpec because it carries a subtype constraint.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)
- `requiredConfig` (boolean, optional, nullable)
- `subtype` (enum, optional, nullable) — Optional subtype constraint — if present, the referenced schema must be of this entity type (e.g. DNA_SEQUENCE, AA_SEQUENCE).
  - Allowed values: `AA_SEQUENCE`, `CUSTOM_ENTITY`, `DNA_OLIGO`, `DNA_SEQUENCE`, `MIXTURE`, `MOLECULE`, `RNA_OLIGO`, `RNA_SEQUENCE`

### WorkflowTaskSchemaAppConfigSpec

Specifies that an app configuration field should reference a workflow task schema. Kept separate from SchemaAppConfigSpec because it supports output field definitions.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)
- `output` (AppConfigWorkflowTaskSchemaOutput, optional, nullable) — Output field definitions for the workflow task schema.
- `requiredConfig` (boolean, optional, nullable)

### SchemaAppConfigSpec

Specifies that an app configuration field should reference one of the schema types that share a common structure: container_schema, plate_schema, location_schema, box_schema, run_schema, result_schema, legacy_request_schema, or entry_schema. The type field identifies which schema kind is required. For entity_schema use EntitySchemaAppConfigSpec; for workflow_task_schema use WorkflowTaskSchemaAppConfigSpec.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)
- `requiredConfig` (boolean, optional, nullable)
- `type` (enum, optional, nullable)
  - Allowed values: `BOX_SCHEMA`, `CONTAINER_SCHEMA`, `ENTRY_SCHEMA`, `LEGACY_REQUEST_SCHEMA`, `LOCATION_SCHEMA`, `PLATE_SCHEMA`, `RESULT_SCHEMA`, `RUN_SCHEMA`, `WORKFLOW_TASK_SCHEMA`, `AA_SEQUENCE`, `ASSAY_RESULT`, `ASSAY_RUN`, `AUTOMATION_INPUT_GENERATOR`, `AUTOMATION_OUTPUT_PROCESSOR`, `BLOB`, `BOX`, `CONTAINER`, `CUSTOM_ENTITY`, `DNA_ALIGNMENT`, `DNA_OLIGO`, `DNA_SEQUENCE`, `DROPDOWN`, `DROPDOWN_OPTION`, `ENTRY`, `FIELD`, `FOLDER`, `LEGACY_REQUEST`, `LOCATION`, `MIXTURE`, `MOLECULE`, `PLATE`, `PROJECT`, `REGISTRY`, `RNA_OLIGO`, `RNA_SEQUENCE`, `WORKFLOW_TASK_STATUS`, `WORKLIST`

### ResourceAppConfigSpec

Specifies that an app configuration field should reference a Benchling object instance. The type field identifies the kind of object required, matching the BenchlingAppType values used in app manifests (e.g. dna_sequence, folder, registry). Covers all instance reference types with no additional spec constraints beyond requiredConfig. For schema references use SchemaAppConfigSpec or EntitySchemaAppConfigSpec.

- `__typename` (string, optional)
- `requiredConfig` (boolean, optional, nullable)
- `type` (enum, optional, nullable)
  - Allowed values: `BOX_SCHEMA`, `CONTAINER_SCHEMA`, `ENTRY_SCHEMA`, `LEGACY_REQUEST_SCHEMA`, `LOCATION_SCHEMA`, `PLATE_SCHEMA`, `RESULT_SCHEMA`, `RUN_SCHEMA`, `WORKFLOW_TASK_SCHEMA`, `AA_SEQUENCE`, `ASSAY_RESULT`, `ASSAY_RUN`, `AUTOMATION_INPUT_GENERATOR`, `AUTOMATION_OUTPUT_PROCESSOR`, `BLOB`, `BOX`, `CONTAINER`, `CUSTOM_ENTITY`, `DNA_ALIGNMENT`, `DNA_OLIGO`, `DNA_SEQUENCE`, `DROPDOWN`, `DROPDOWN_OPTION`, `ENTRY`, `FIELD`, `FOLDER`, `LEGACY_REQUEST`, `LOCATION`, `MIXTURE`, `MOLECULE`, `PLATE`, `PROJECT`, `REGISTRY`, `RNA_OLIGO`, `RNA_SEQUENCE`, `WORKFLOW_TASK_STATUS`, `WORKLIST`

### ArrayAppConfigOption

A config option nested within an array-type app configuration field. Structurally identical to AppConfigOption — it has a name and a configSpec — but its configSpec accepts the same config types as the top level except nested arrays (see ArrayAppConfigElementSpec).

- `__typename` (string, optional)
- `configSpec` (ArrayAppConfigOptionConfigSpec, optional) — Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec
- `description` (string, optional, nullable)
- `name` (string, optional)

### AppConfigDropdownOption

Defines an option within a dropdown-type app configuration field.

- `__typename` (string, optional)
- `description` (string, optional, nullable)
- `name` (string, optional)
- `requiredConfig` (boolean, optional, nullable)

### AppConfigFieldDefinition

Defines a field within an app configuration that references schema fields. Specifies the field name, type, whether it accepts multiple values, and whether it is required.

- `__typename` (string, optional)
- `description` (string, optional, nullable)
- `isMulti` (boolean, optional, nullable) — Whether the field must be multi-valued — null means either true or false is acceptable.
- `isRequired` (boolean, optional, nullable) — Whether the field must be required — null means either true or false is acceptable.
- `name` (string, optional)
- `requiredConfig` (boolean, optional, nullable)
- `type` (enum, optional, nullable) — Type constraint for the field — null means any type is acceptable.
  - Allowed values: `DNA_SEQUENCE_LINK`, `AA_SEQUENCE_LINK`, `CUSTOM_ENTITY_LINK`, `ENTITY_LINK`, `MIXTURE_LINK`, `MOLECULE_LINK`, `DROPDOWN`, `PART_LINK`, `AA_PART_LINK`, `TRANSLATION_LINK`, `BLOB_LINK`, `TEXT`, `LONG_TEXT`, `BATCH_LINK`, `STORAGE_LINK`, `ENTRY_LINK`, `ASSAY_REQUEST_LINK`, `ASSAY_RESULT_LINK`, `ASSAY_RUN_LINK`, `BOOLEAN`, `FLOAT`, `INTEGER`, `DATETIME`, `DATE`, `JSON`

### AppConfigWorkflowTaskSchemaOutput

Defines the output field structure for a workflow task schema configuration.

- `__typename` (string, optional)
- `fieldDefinitions` (list of AppConfigFieldDefinition, optional, nullable)

### ArrayAppConfigOptionConfigSpec

Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec

## Examples

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "configurationSpecs": [
        {}
      ],
      "configurationValues": "configurationValues",
      "createdAt": "createdAt",
      "description": "description",
      "featureSpecs": [
        {}
      ],
      "featureValues": [
        {}
      ],
      "id": "id",
      "messageSubscriptions": [
        {}
      ],
      "modifiedAt": "modifiedAt",
      "name": "name",
      "publicKey": "publicKey",
      "versionNumber": "versionNumber",
      "webhookUrl": "webhookUrl"
    }
  ],
  "nextToken": "nextToken"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/legacy-app-installation/items"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/legacy-app-installation/items';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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