openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling Collaboration API
  version: 2.0.0
  description: 'A Collaboration indicates that a Principal or Group is granted a Policy on a Resource.

    Some Collaborations represent Ownership, while others indicate that a Resource was shared with the Principal

    or Group.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Collaboration indicates that a Principal or Group is granted a Policy on a Resource.

    Some Collaborations represent Ownership, while others indicate that a Resource was shared with the Principal

    or Group.'
  name: Collaboration
  x-bnch-organization: Benchling
paths:
  /collaboration:
    post:
      description: Create Collaboration.
      operationId: Collaboration.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/CreateCollaborationInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collaboration'
          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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 4
  /collaboration/items:
    get:
      description: List Collaboration items.
      operationId: Collaboration.List
      parameters:
      - $ref: '#/components/parameters/collaboratorId.anyOf'
      - $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/nextToken'
      - $ref: '#/components/parameters/omit'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/resourceId.anyOf'
      - $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/CollaborationPaginatedList'
          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 Collaboration items
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 4
  /collaboration/{collaboration_id}:
    delete:
      description: Delete Collaboration.
      operationId: Collaboration.Delete
      parameters:
      - description: ID of the Collaboration.
        in: path
        name: collaboration_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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 4
    get:
      description: Get a single Collaboration by ID.
      operationId: Collaboration.Get
      parameters:
      - description: ID of the Collaboration.
        in: path
        name: collaboration_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/Collaboration'
          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 Collaboration by ID
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 5
    patch:
      description: Update Collaboration.
      operationId: Collaboration.Update
      parameters:
      - description: ID of the Collaboration.
        in: path
        name: collaboration_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/UpdateCollaborationInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collaboration'
          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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 4
  /collaboration:batch-create:
    post:
      description: Batch create Collaboration synchronously in one transaction. Maximum 25 items per request.
      operationId: Collaboration.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/CreateCollaborationInput'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Collaboration'
                    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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 3
  /collaboration:batch-delete:
    post:
      description: Batch delete Collaboration synchronously in one transaction. Maximum 25 items per request.
      operationId: Collaboration.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/DeleteCollaborationInputWithPathParams'
                  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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 3
  /collaboration:batch-update:
    patch:
      description: Batch update Collaboration synchronously in one transaction. Maximum 25 items per request.
      operationId: Collaboration.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/UpdateCollaborationInputWithPathParams'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Collaboration'
                    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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 3
  /collaboration:bulk-create:
    post:
      description: Bulk create Collaboration.
      operationId: Collaboration.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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 2
  /collaboration:bulk-update:
    patch:
      description: Bulk update Collaboration.
      operationId: Collaboration.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 Collaboration
      tags:
      - Collaboration
      x-bnch-rate-limit-tier: 2
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
    collaboratorId.anyOf:
      description: Restricts results to collaborations for any of the specified collaborator IDs. Comma-separated list.
      explode: false
      in: query
      name: collaboratorId.anyOf
      schema:
        items:
          type: string
        maxItems: 100
        type: array
    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
    resourceId.anyOf:
      description: Restricts results to collaborations on any of the specified resource IDs. Comma-separated list.
      explode: false
      in: query
      name: resourceId.anyOf
      schema:
        items:
          type: string
        maxItems: 100
        type: array
    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
    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
  schemas:
    GroupCollaboratorInfo:
      description: 'Represents a Group that is the subject of a Collaboration, along with sub-group information.

        In Group Collaborations, the Resource may be shared with a sub-group of the Group, e.g.

        the Admins of a Team.'
      properties:
        __typename:
          type: string
        collaborator:
          $ref: '#/components/schemas/Group'
        role:
          enum:
          - MEMBER
          - ADMIN
          type: string
      type: object
    CollaborationPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/Collaboration'
          type: array
        nextToken:
          type: string
      type: object
    PolicyRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    UpdateCollaborationInput:
      additionalProperties: false
      properties:
        accessPolicyId:
          type: string
        isAuditor:
          type: boolean
      type: object
    DeleteCollaborationInputWithPathParams:
      additionalProperties: false
      properties:
        id:
          type: string
      required:
      - id
      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
    Group:
      anyOf:
      - $ref: '#/components/schemas/Organization'
      - $ref: '#/components/schemas/Team'
      discriminator:
        propertyName: __typename
      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
    Team:
      description: 'Represents a subgroup of users within an `Organization`, enabling finer-grained user

        management and data sharing. Teams belong to exactly one organization, and users may

        only join a team if they are already members of that team''s parent organization. Each

        team member has either ADMIN or MEMBER role (see `GroupMembership`): admins can manage

        team membership, while members receive standard access. Unlike Organizations, teams

        cannot directly own Projects or Folders—they are used for collaboration and access

        control purposes. Teams can be configured with `provisionedCapabilities` to grant

        specific Benchling capabilities to members upon joining. The `membersAreAdministratorsOfSchemas`

        flag controls whether team members can create and modify certain schema types.'
      properties:
        __typename:
          type: string
        createdAt:
          format: datetime
          type: string
        description:
          type: string
        id:
          type: string
        membersAreAdministratorsOfSchemas:
          description: 'Indicates that members of the team are able to create and modify schemas that do not implement the

            Collaboratable interface.'
          type: boolean
        memberships:
          format: uri
          type: string
        modifiedAt:
          format: datetime
          type: string
        name:
          type: string
        organization:
          $ref: '#/components/schemas/OrganizationRef'
      type: object
    PrincipalRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    PrincipalCollaboratorInfo:
      description: Represents a Principal that is the subject for a Collaboration.
      properties:
        __typename:
          type: string
        collaborator:
          $ref: '#/components/schemas/PrincipalRef'
      type: object
    CreateCollaborationInput:
      additionalProperties: false
      properties:
        accessPolicyId:
          type: string
        collaborator:
          $ref: '#/components/schemas/CollaboratorReferenceInput'
        isAuditor:
          type: boolean
        itemId:
          type: string
      required:
      - itemId
      - collaborator
      - accessPolicyId
      type: object
    CollaboratorReferenceInput:
      additionalProperties: false
      properties:
        collaboratorId:
          type: string
        role:
          enum:
          - MEMBER
          - ADMIN
          type: string
      required:
      - collaboratorId
      type: object
    OrganizationRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    Organization:
      description: 'Represents a group of users within Benchling, typically corresponding to a company,

        department, or research group. Organizations provide a many-to-many relationship between

        users—each user can belong to multiple organizations, and each organization can have

        multiple users. Users are designated as either ADMIN (with management privileges) or

        MEMBER within the organization via `GroupMembership`. Organizations can own resources

        like Projects and Folders, and can contain Teams for finer-grained user grouping.

        Organizations also control access settings such as whether members can create personal

        ownables and what default policies apply to new resources. In the UI, organizations

        appear in user profiles and are used for sharing and access control throughout Benchling.'
      properties:
        __typename:
          type: string
        createdAt:
          format: datetime
          type: string
        handle:
          type: string
        id:
          type: string
        memberships:
          format: uri
          type: string
        modifiedAt:
          format: datetime
          type: string
        name:
          type:
          - 'null'
          - string
      type: object
    UpdateCollaborationInputWithPathParams:
      additionalProperties: false
      properties:
        accessPolicyId:
          type: string
        id:
          type: string
        isAuditor:
          type: boolean
      required:
      - id
      type: object
    Collaboration:
      description: 'A Collaboration indicates that a Principal or Group is granted a Policy on a Resource.

        Some Collaborations represent Ownership, while others indicate that a Resource was shared with the Principal

        or Group.'
      properties:
        __typename:
          type: string
        accessPolicy:
          $ref: '#/components/schemas/PolicyRef'
        collaboratorInfo:
          anyOf:
          - $ref: '#/components/schemas/PrincipalCollaboratorInfo'
          - $ref: '#/components/schemas/GroupCollaboratorInfo'
          description: Union of PrincipalCollaboratorInfo, GroupCollaboratorInfo
          discriminator:
            propertyName: __typename
        createdAt:
          format: datetime
          type: string
        fromOwnership:
          type: boolean
        id:
          type: string
        isAuditor:
          type: boolean
        modifiedAt:
          format: datetime
          type: string
        resource:
          $ref: '#/components/schemas/CollaboratableRef'
      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
    CollaboratableRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
  responses:
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Too Many Requests
    NotFound:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Not Found
    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