Benchling Scratch File API

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.

Operations 9

POST /scratch-file Create ScratchFile #
GET /scratch-file/items List ScratchFile items #
GET /scratch-file/{scratch_file_id} Get ScratchFile by ID #
PATCH /scratch-file/{scratch_file_id} Update ScratchFile #
POST /scratch-file:batch-create Batch create ScratchFile #
PATCH /scratch-file:batch-update Batch update ScratchFile #
POST /scratch-file:bulk-create Bulk create ScratchFile #
PATCH /scratch-file:bulk-update Bulk update ScratchFile #
POST /scratch-file:create-and-upload 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/j #

Documentation

Specifications

Other Resources

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/benchling-scratchfile-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

benchling-scratchfile-api-openapi.yml Raw ↑
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