openapi: 3.2.0 info: license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html title: Benchling Folder API version: 2.0.0 description: 'A hierarchical container for organizing entities, notebook entries, and other items within a Project. Folders support nested structures through parent-child relationships (see `parent`), enabling users to create logical groupings that mirror laboratory organization or experimental workflows. Folders belong to a Project (see `project`) and inherit access control through collaborations (see `Collaboration`). Items stored in folders implement the FolderItem interface. Folders can be starred for quick access (via `Starrable`) and archived with lineage tracking that affects contained items (via `ArchivableWithLineage`).' servers: - url: /api/v3 security: - oAuth: [] - basicApiKeyAuth: [] tags: - description: 'A hierarchical container for organizing entities, notebook entries, and other items within a Project. Folders support nested structures through parent-child relationships (see `parent`), enabling users to create logical groupings that mirror laboratory organization or experimental workflows. Folders belong to a Project (see `project`) and inherit access control through collaborations (see `Collaboration`). Items stored in folders implement the FolderItem interface. Folders can be starred for quick access (via `Starrable`) and archived with lineage tracking that affects contained items (via `ArchivableWithLineage`).' name: Folder x-bnch-organization: Benchling paths: /folder: post: description: Create Folder. operationId: Folder.Create parameters: - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateFolderInput' responses: '201': content: application/json: schema: $ref: '#/components/schemas/Folder' description: Created '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Create Folder tags: - Folder x-bnch-rate-limit-tier: 4 /folder/items: get: description: List Folder items. operationId: Folder.List parameters: - $ref: '#/components/parameters/archiveReason.anyOf' - $ref: '#/components/parameters/archived.anyOf' - $ref: '#/components/parameters/id.anyOf' - $ref: '#/components/parameters/modifiedAt.gt' - $ref: '#/components/parameters/modifiedAt.gte' - $ref: '#/components/parameters/modifiedAt.lt' - $ref: '#/components/parameters/modifiedAt.lte' - $ref: '#/components/parameters/name.anyOf' - $ref: '#/components/parameters/name.anyOf.caseSensitive' - $ref: '#/components/parameters/nextToken' - $ref: '#/components/parameters/omit' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/parent.eq' - $ref: '#/components/parameters/project.eq' - $ref: '#/components/parameters/returning' - description: 'Method by which to order results. Valid sorts are: modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.' in: query name: sort schema: default: modifiedAt:desc enum: - modifiedAt:asc - modifiedAt:desc type: string - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/FolderPaginatedList' description: OK headers: {} '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: List Folder items tags: - Folder x-bnch-rate-limit-tier: 4 /folder/{folder_id}: delete: description: Delete Folder. operationId: Folder.Delete parameters: - description: ID of the Folder. in: path name: folder_id required: true schema: type: string - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string responses: '204': description: No Content '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Delete Folder tags: - Folder x-bnch-rate-limit-tier: 4 get: description: Get a single Folder by ID. operationId: Folder.Get parameters: - description: ID of the Folder. in: path name: folder_id required: true schema: type: string - $ref: '#/components/parameters/returning' - $ref: '#/components/parameters/omit' - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Folder' description: OK headers: {} '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Get Folder by ID tags: - Folder x-bnch-rate-limit-tier: 5 patch: description: Update Folder. operationId: Folder.Update parameters: - description: ID of the Folder. in: path name: folder_id required: true schema: type: string - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateFolderInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Folder' description: OK '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Update Folder tags: - Folder x-bnch-rate-limit-tier: 4 /folder/{folder_id}/children/items: get: description: List Folder items. operationId: Folder.children.List parameters: - description: ID of the Folder. in: path name: folder_id required: true schema: type: string - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/FolderUnpaginatedList' description: OK headers: {} '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: List Folder items tags: - Folder x-bnch-rate-limit-tier: 4 /folder/{folder_id}:move: post: description: Move a Folder into another Folder operationId: Folder.Move parameters: - description: ID of the Folder. in: path name: folder_id required: true schema: type: string - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/MoveFolderInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Folder' description: OK '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Move a Folder into another Folder tags: - Folder x-bnch-rate-limit-tier: 4 /folder:batch-create: post: description: Batch create Folder synchronously in one transaction. Maximum 25 items per request. operationId: Folder.BatchCreate parameters: - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/CreateFolderInput' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '201': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/Folder' type: array required: - items type: object description: Created '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Batch create Folder tags: - Folder x-bnch-rate-limit-tier: 3 /folder:batch-delete: post: description: Batch delete Folder synchronously in one transaction. Maximum 25 items per request. operationId: Folder.BatchDelete parameters: - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/DeleteFolderInputWithPathParams' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '200': content: application/json: schema: additionalProperties: false properties: items: items: additionalProperties: false properties: id: type: string required: - id type: object type: array required: - items type: object description: OK '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Batch delete Folder tags: - Folder x-bnch-rate-limit-tier: 3 /folder:batch-update: patch: description: Batch update Folder synchronously in one transaction. Maximum 25 items per request. operationId: Folder.BatchUpdate parameters: - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/UpdateFolderInputWithPathParams' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '200': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/Folder' type: array required: - items type: object description: OK '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Batch update Folder tags: - Folder x-bnch-rate-limit-tier: 3 /folder:bulk-create: post: description: Bulk create Folder. operationId: Folder.BulkCreate parameters: - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkImport' responses: '202': content: application/json: schema: $ref: '#/components/schemas/AsyncTaskLink' description: Task started '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Bulk create Folder tags: - Folder x-bnch-rate-limit-tier: 2 /folder:bulk-update: patch: description: Bulk update Folder. operationId: Folder.BulkUpdate parameters: - description: Set to true to access beta operations via /api/v3. in: header name: EARLY-ACCESS required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkImport' responses: '202': content: application/json: schema: $ref: '#/components/schemas/AsyncTaskLink' description: Task started '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' summary: Bulk update Folder tags: - Folder x-bnch-rate-limit-tier: 2 components: parameters: parent.eq: description: ID of a folder. Restricts results to its direct children. in: query name: parent.eq schema: type: string pageSize: description: Number of results to return. Defaults to 50, maximum of 100. in: query name: pageSize schema: type: integer modifiedAt.gt: description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30. in: query name: modifiedAt.gt schema: format: datetime type: string modifiedAt.lte: description: 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. in: query name: modifiedAt.lte schema: format: datetime type: string id.anyOf: description: Restricts results to those matching any of the specified IDs. Comma-separated list. explode: false in: query name: id.anyOf schema: items: type: string maxItems: 100 type: array omit: description: Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning. explode: false in: query name: omit schema: items: type: string type: array modifiedAt.lt: description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. < 2017-04-30. in: query name: modifiedAt.lt schema: format: datetime type: string project.eq: description: ID of a project. Restricts results to those in the project. in: query name: project.eq schema: type: string archiveReason.anyOf: description: 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. explode: false in: query name: archiveReason.anyOf schema: items: type: string maxItems: 10 type: array returning: description: Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit. explode: false in: query name: returning schema: items: type: string type: array archived.anyOf: description: If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list. explode: false in: query name: archived.anyOf schema: items: type: boolean maxItems: 2 type: array nextToken: description: Token for pagination in: query name: nextToken schema: type: string name.anyOf: description: 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. explode: false in: query name: name.anyOf schema: items: type: string maxItems: 100 type: array name.anyOf.caseSensitive: description: 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. explode: false in: query name: name.anyOf.caseSensitive schema: items: type: string maxItems: 100 type: array modifiedAt.gte: description: 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. in: query name: modifiedAt.gte schema: format: datetime type: string schemas: UpdateFolderInputWithPathParams: additionalProperties: false properties: archiveReason: type: string archived: type: boolean description: type: - 'null' - string id: type: string name: type: string required: - id type: object ProjectRef: properties: __typename: type: string id: format: api_id type: string type: object Folder: description: 'A hierarchical container for organizing entities, notebook entries, and other items within a Project. Folders support nested structures through parent-child relationships (see `parent`), enabling users to create logical groupings that mirror laboratory organization or experimental workflows. Folders belong to a Project (see `project`) and inherit access control through collaborations (see `Collaboration`). Items stored in folders implement the FolderItem interface. Folders can be starred for quick access (via `Starrable`) and archived with lineage tracking that affects contained items (via `ArchivableWithLineage`).' properties: __typename: type: string archiveReason: type: - 'null' - string archived: type: boolean children: description: The folders directly nested under this folder. format: uri type: string createdAt: format: datetime type: string description: type: - 'null' - string id: type: string modifiedAt: format: datetime type: - 'null' - string name: type: - 'null' - string parent: description: The parent folder, if it exists. Root folders (one per Project) have no parent. oneOf: - $ref: '#/components/schemas/FolderRef' - type: 'null' project: description: ID of the containing project oneOf: - $ref: '#/components/schemas/ProjectRef' - type: 'null' type: object InternalServerError: properties: detail: type: - 'null' - string - object errorId: type: string instance: type: string status: type: integer title: type: - 'null' - string type: type: string required: - type - title - detail - status - instance type: object AsyncTaskLink: properties: pollingUri: format: uri type: string taskId: type: string type: object BulkImport: example: fileId: scrfile_jdf8BV24kLmN properties: fileId: description: The API ID of the scratch file (`scrfile_XXXXXXXX`) containing the items to import. The referenced file must be a scratch file whose upload has completed successfully. type: string required: - fileId type: object FolderPaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/Folder' type: array nextToken: type: string type: object DeleteFolderInputWithPathParams: additionalProperties: false properties: id: type: string required: - id type: object FolderRef: properties: __typename: type: string id: format: api_id type: string type: object UpdateFolderInput: additionalProperties: false properties: archiveReason: type: string archived: type: boolean description: type: - 'null' - string name: type: string type: object FolderUnpaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/Folder' type: array type: object CreateFolderInput: additionalProperties: false properties: description: type: string name: type: string parentId: type: string required: - name - parentId type: object MoveFolderInput: additionalProperties: false properties: parentId: type: string required: - parentId type: object GeneralError: properties: detail: type: - 'null' - string - object instance: type: string status: type: integer title: type: - 'null' - string type: type: string required: - type - title - detail - status - instance type: object responses: NotFound: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Not Found TooManyRequests: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Too Many Requests BadRequest: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Bad Request Forbidden: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Forbidden InternalServerError: content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerError' description: Internal Server Error securitySchemes: basicApiKeyAuth: description: Use issued API key for standard access to the API scheme: basic type: http basicClientIdSecretAuth: description: Auth used as part of client credentials OAuth flow prior to receiving a bearer token. scheme: basic type: http oAuth: description: OAuth2 Client Credentials flow intended for service access flows: clientCredentials: scopes: {} tokenUrl: /oauth/token type: oauth2