openapi: 3.2.0 info: license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html title: Benchling Scratch File API version: 2.0.0 description: 'A ScratchFile represents raw file content used as intermediate input or output of pipeline steps (see PipelineStepData). Unlike File, ScratchFiles are not surfaced in the Data Catalog because they typically represent transient processing artifacts rather than standalone valuable data. ScratchFiles track upload state via uploadStatus and provide uploadUrl/downloadUrl for content transfer. When a ScratchFile is promoted to user-visible status, it is linked to a File object that appears in the Data Catalog. The originPipelineStepData field tracks which pipeline step produced this file.' servers: - url: /api/v3 security: - oAuth: [] - basicApiKeyAuth: [] tags: - description: 'A ScratchFile represents raw file content used as intermediate input or output of pipeline steps (see PipelineStepData). Unlike File, ScratchFiles are not surfaced in the Data Catalog because they typically represent transient processing artifacts rather than standalone valuable data. ScratchFiles track upload state via uploadStatus and provide uploadUrl/downloadUrl for content transfer. When a ScratchFile is promoted to user-visible status, it is linked to a File object that appears in the Data Catalog. The originPipelineStepData field tracks which pipeline step produced this file.' name: ScratchFile x-bnch-organization: Benchling paths: /scratch-file: post: description: Create ScratchFile. operationId: ScratchFile.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/CreateScratchFileInput' responses: '201': content: application/json: schema: $ref: '#/components/schemas/ScratchFile' 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 ScratchFile tags: - ScratchFile x-bnch-rate-limit-tier: 4 /scratch-file/items: get: description: List ScratchFile items. operationId: ScratchFile.List parameters: - $ref: '#/components/parameters/createdAt.gt' - $ref: '#/components/parameters/createdAt.gte' - $ref: '#/components/parameters/createdAt.lt' - $ref: '#/components/parameters/createdAt.lte' - $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/returning' - description: '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.' in: query name: sort schema: default: modifiedAt:desc enum: - createdAt:asc - createdAt:desc - 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/ScratchFilePaginatedList' 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 ScratchFile items tags: - ScratchFile x-bnch-rate-limit-tier: 4 /scratch-file/{scratch_file_id}: get: description: Get a single ScratchFile by ID. operationId: ScratchFile.Get parameters: - description: ID of the ScratchFile. in: path name: scratch_file_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/ScratchFile' 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 ScratchFile by ID tags: - ScratchFile x-bnch-rate-limit-tier: 5 patch: description: Update ScratchFile. operationId: ScratchFile.Update parameters: - description: ID of the ScratchFile. in: path name: scratch_file_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/UpdateScratchFileInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScratchFile' 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 ScratchFile tags: - ScratchFile x-bnch-rate-limit-tier: 4 /scratch-file:batch-create: post: description: Batch create ScratchFile synchronously in one transaction. Maximum 25 items per request. operationId: ScratchFile.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/CreateScratchFileInput' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '201': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/ScratchFile' 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 ScratchFile tags: - ScratchFile x-bnch-rate-limit-tier: 3 /scratch-file:batch-update: patch: description: Batch update ScratchFile synchronously in one transaction. Maximum 25 items per request. operationId: ScratchFile.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/UpdateScratchFileInputWithPathParams' maxItems: 25 minItems: 1 type: array required: - items type: object responses: '200': content: application/json: schema: additionalProperties: false properties: items: items: $ref: '#/components/schemas/ScratchFile' 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 ScratchFile tags: - ScratchFile x-bnch-rate-limit-tier: 3 /scratch-file:bulk-create: post: description: Bulk create ScratchFile. operationId: ScratchFile.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 ScratchFile tags: - ScratchFile x-bnch-rate-limit-tier: 2 /scratch-file:bulk-update: patch: description: Bulk update ScratchFile. operationId: ScratchFile.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 ScratchFile tags: - ScratchFile x-bnch-rate-limit-tier: 2 /scratch-file:create-and-upload: post: description: Create a ScratchFile from either uploaded contents or an existing S3 location. Provide exactly one of `contents` (with a `filename`, up to 10 MiB of UTF-8 sent as an `application/json` body) or `s3Location` (the filename is derived from the location when omitted). operationId: ScratchFile.CreateAndUpload 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/CreateAndUploadScratchFileInput' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScratchFile' 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: Create a ScratchFile from either uploaded contents or an existing S3 location. Provide exactly one of `contents` (with a `filename`, up to 10 MiB of UTF-8 sent as an `application/json` body) or `s3Location` (the filename is derived from the location when omitted). tags: - ScratchFile x-bnch-rate-limit-tier: 4 components: parameters: pageSize: description: Number of results to return. Defaults to 50, maximum of 100. in: query name: pageSize schema: type: integer createdAt.gte: description: 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. in: query name: createdAt.gte schema: format: datetime type: string 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 createdAt.gt: description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30. in: query name: createdAt.gt schema: format: datetime type: string createdAt.lt: description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. < 2017-04-30. in: query name: createdAt.lt schema: format: datetime type: string 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 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 createdAt.lte: description: 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. in: query name: createdAt.lte schema: format: datetime type: string 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 schemas: UpdateScratchFileInput: additionalProperties: false properties: errorMessage: type: - 'null' - string uploadStatus: enum: - SUCCEEDED - FAILED_VALIDATION - IN_PROGRESS - NOT_UPLOADED type: string required: - uploadStatus type: object CreateAndUploadScratchFileInput: additionalProperties: false properties: contents: type: string filename: type: string s3Location: type: string 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 ScratchFilePaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/ScratchFile' type: array nextToken: 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 ScratchFile: description: 'A ScratchFile represents raw file content used as intermediate input or output of pipeline steps (see PipelineStepData). Unlike File, ScratchFiles are not surfaced in the Data Catalog because they typically represent transient processing artifacts rather than standalone valuable data. ScratchFiles track upload state via uploadStatus and provide uploadUrl/downloadUrl for content transfer. When a ScratchFile is promoted to user-visible status, it is linked to a File object that appears in the Data Catalog. The originPipelineStepData field tracks which pipeline step produced this file.' properties: __typename: type: string createdAt: format: datetime type: - 'null' - string creator: $ref: '#/components/schemas/PrincipalRef' downloadUrl: type: - 'null' - string errorMessage: type: - 'null' - string externalFileId: type: - 'null' - string file: oneOf: - $ref: '#/components/schemas/FileRef' - type: 'null' filename: type: string id: type: string mimeType: type: - 'null' - string modifiedAt: format: datetime type: - 'null' - string name: type: string originPipelineStepData: oneOf: - $ref: '#/components/schemas/PipelineStepDataRef' - type: 'null' size: type: - 'null' - integer uploadStatus: enum: - SUCCEEDED - FAILED_VALIDATION - IN_PROGRESS - NOT_UPLOADED type: string uploadUrl: type: - 'null' - string type: object CreateScratchFileInput: additionalProperties: false properties: filename: type: string name: type: string required: - filename type: object PrincipalRef: properties: __typename: type: string id: format: api_id type: string type: object FileRef: properties: __typename: type: string id: format: api_id type: string type: object PipelineStepDataRef: properties: __typename: type: string id: format: api_id type: string type: object UpdateScratchFileInputWithPathParams: additionalProperties: false properties: errorMessage: type: - 'null' - string id: type: string uploadStatus: enum: - SUCCEEDED - FAILED_VALIDATION - IN_PROGRESS - NOT_UPLOADED type: string required: - id - uploadStatus 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 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