Cosuno Bids API

openapi: 3.2.0
info:
  title: Cosuno Bids API
  version: '1'
  description: '-'
  license:
    name: '-'
  contact:
    name: '-'
servers:
- url: https://api.cosuno.com/v1
- description: current
  url: /v1
tags:
- name: Bids
paths:
  /bids/{id}/file-tree/{nodeId}/contents:
    get:
      operationId: GetBidFileTreeNodeContents
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FileTreeItemResponse'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: List the contents of a folder in the file tree attached to a bid.
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: Use `root` to get the contents of the entire file tree.
        in: path
        name: nodeId
        required: true
        schema:
          type: string
      summary: Get bid file tree node contents
      x-summary-source: derived
  /bids/{id}/file-tree/{nodeId}/folders:
    post:
      operationId: CreateBidFileTreeNodeFolders
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileTreeItemResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Create a folder in the file tree attached to a bid.
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: Use `root` to create folders in the root of the file tree.
        in: path
        name: nodeId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileTreeFolderInput'
      summary: Create bid file tree node folders
      x-summary-source: derived
  /bids/{id}/file-tree/{nodeId}:
    put:
      operationId: UpdateBidFileTreeNode
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileTreeItemResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Update a file or folder in the file tree attached to a bid (e.g. rename or move it to a different folder).
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: nodeId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileTreeItemInput'
      summary: Update bid file tree node
      x-summary-source: derived
    delete:
      operationId: DeleteBidFileTreeNode
      responses:
        '204':
          description: No content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Delete a file or folder from the file tree attached to a bid. Folders are deleted along with all their contents.
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: nodeId
        required: true
        schema:
          type: string
      summary: Delete bid file tree node
      x-summary-source: derived
  /bids/{id}/file-tree/{nodeId}/download:
    get:
      operationId: DownloadBidFileTreeNode
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Download a file, or a folder and its contents as a ZIP archive, from the file tree attached to a bid. Responds with a redirect to a time-limited download URL.
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: Use `root` to download the contents of the entire file tree.
        in: path
        name: nodeId
        required: true
        schema:
          type: string
      summary: Download bid file tree node
      x-summary-source: derived
  /bids/{id}/file-tree/{nodeId}/upload:
    post:
      operationId: UploadBidFileTreeFiles
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FileTreeItemResponse'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Upload one or more files into a folder in the file tree attached to a bid. To preserve folder structure, include `/`-separated paths in each uploaded file's original filename (e.g. `docs/q1/report.pdf`).
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: Use `root` to upload the files to the root of the file tree.
        in: path
        name: nodeId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  items:
                    type: string
                    format: binary
                  type: array
              required:
              - files
      summary: Upload bid file tree files
      x-summary-source: derived
  /bids/{id}:
    get:
      operationId: GetBid
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmittedBidResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Retrieve a submitted bid by its ID, including its pricing totals and metadata.
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - description: The ID of the bid.
        in: path
        name: id
        required: true
        schema:
          type: string
      summary: Get bid
      x-summary-source: derived
  /bids/{id}/boq/{fileType}:
    get:
      operationId: DownloadBidBoQFile
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Download the priced bill of quantities submitted with a bid in the requested file format. Responds with a redirect to a time-limited download URL.
      tags:
      - Bids
      security:
      - accessKey: []
      parameters:
      - description: The ID of the bid.
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: File format to download the priced bill of quantities in.
        in: path
        name: fileType
        required: true
        schema:
          $ref: '#/components/schemas/BOQ_FILE_TYPE_DOWNLOADABLE_FOR_BID'
      summary: Download bid bo QFile
      x-summary-source: derived
  /bids/{id}/documents:
    get:
      operationId: GetBidDocuments
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DocumentResponse'
                type: array
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: 'Use File Tree API endpoint instead: `GET /bids/{id}/file-tree/root/contents`'
      tags:
      - Bids
      deprecated: true
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      summary: Get bid documents
      x-summary-source: derived
  /bids/{id}/documents/{documentId}/download:
    get:
      operationId: DownloadBidDocument
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: 'Use File Tree API endpoint instead: `GET /bids/{id}/file-tree/{nodeId}/download`'
      tags:
      - Bids
      deprecated: true
      security:
      - accessKey: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: documentId
        required: true
        schema:
          type: string
      summary: Download bid document
      x-summary-source: derived
components:
  schemas:
    UserResponse:
      properties:
        id:
          type: string
          description: ID of the user.
        email:
          type: string
          description: Email address of the user. Also used as their login identifier.
        status:
          $ref: '#/components/schemas/USER_STATUS'
          description: Current status of the user.
        firstName:
          type: string
          description: Given name of the user.
        lastName:
          type: string
          description: Family name of the user.
        type:
          $ref: '#/components/schemas/USER_TYPE'
          description: Account type of the user. Values starting with `custom` indicate a custom user role (see `customUserRoleId`).
        customUserRoleId:
          type: string
          description: ID of the custom user role assigned to the user. Present only when `type` refers to a custom user role.
      required:
      - id
      - email
      - status
      - type
      type: object
      additionalProperties: false
    DocumentResponse:
      properties:
        id:
          type: string
          description: ID of the document.
        fileName:
          type: string
          description: Original file name of the document (including extension).
        fileSize:
          type: number
          format: double
          description: Size of the document in bytes.
        uploadedAt:
          type: string
          description: 'Timestamp at which the document was uploaded.

            The date-time notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)'
          format: date-time
        uploadedBy:
          $ref: '#/components/schemas/UserResponse'
          description: User who uploaded the document, if known.
        path:
          items:
            type: string
          type: array
          description: Path to the document expressed as an array of folder names from the root of the file tree down to (but not including) the document itself.
      required:
      - id
      - fileName
      - fileSize
      - uploadedAt
      - path
      type: object
      additionalProperties: false
    FileTreeFolderResponse:
      properties:
        id:
          type: string
          description: ID of the folder node.
        type:
          type: string
          enum:
          - folder
          description: Discriminator indicating that this item is a folder.
        name:
          type: string
          description: Folder name.
        path:
          items:
            type: string
          type: array
          description: Path to the folder expressed as an array of folder names from the root of the file tree down to (but not including) the folder itself.
        parentId:
          type: string
          description: ID of the parent folder. Equal to `root` when the folder sits at the top of the tree.
      required:
      - id
      - type
      - name
      - path
      - parentId
      type: object
      additionalProperties: false
    USER_TYPE:
      type: string
      enum:
      - custom
      - administrator
      - employee
      - guest
      - collaborator
      - manager
    BOQ_FILE_TYPE_DOWNLOADABLE_FOR_BID:
      enum:
      - x84
      - x84_33
      - p84
      - d84
      - onlv
      - xlsxProposal
      type: string
    USER_STATUS:
      type: string
      enum:
      - approvalPending
      - adminApprovalPending
      - invited
      - inviteCanceled
      - inviteFailed
      - inviteRequested
      - active
      - inactive
    FileTreeItemResponse:
      anyOf:
      - $ref: '#/components/schemas/FileTreeFileResponse'
      - $ref: '#/components/schemas/FileTreeFolderResponse'
    SubmittedBidResponse:
      properties:
        id:
          type: string
          description: ID of the bid.
        message:
          type:
          - string
          - 'null'
          description: Free-form message submitted by the subcontractor alongside the bid.
        totalNet:
          type: number
          format: double
          description: Net total of the bid before discount and tax, in the bid package's currency.
        discountRate:
          type: number
          format: double
          description: Discount rate offered by the subcontractor, expressed as a fraction between 0 and 1 (e.g. 0.05 for 5%).
        taxRate:
          type: number
          format: double
          description: Value-added tax rate applied to the bid, expressed as a fraction between 0 and 1.
        skontoRate:
          type: number
          format: double
          description: Early-payment discount (skonto) rate offered by the subcontractor, expressed as a fraction between 0 and 1.
        skontoDeadline:
          type: number
          format: double
          description: Number of days within which the early-payment discount (skonto) applies.
        revision:
          type: number
          format: double
          description: Revision number of the bid. Increments each time the subcontractor submits a revised bid.
        hasBillOfQuantities:
          type: boolean
          description: Whether the bid includes a priced bill of quantities.
        absoluteDiscount:
          type: number
          format: double
          description: Fixed absolute discount applied on top of the bid total, in the bid package's currency.
        additionalCosts:
          type: number
          format: double
          description: Additional costs included in the bid beyond the priced bill of quantities, in the bid package's currency.
        skontoValue:
          type: number
          format: double
          description: Monetary amount corresponding to `skontoRate` applied to the net total with discount.
        totalNetWithDiscount:
          type: number
          format: double
          description: Net total after applying discount, in the bid package's currency.
        taxValue:
          type: number
          format: double
          description: Monetary amount of VAT applied to the bid.
        totalGross:
          type: number
          format: double
          description: Gross total of the bid (net with discount plus tax), in the bid package's currency.
        totalGrossWithSkonto:
          type: number
          format: double
          description: Gross total after applying the early-payment discount (skonto), in the bid package's currency.
        submittedAt:
          type: string
          description: Timestamp at which the bid was submitted.
          format: date
        version:
          type: number
          format: double
          description: Monotonic version number of the submitted bid. Increments with each new submission.
      required:
      - id
      - message
      - totalNet
      - discountRate
      - taxRate
      - skontoRate
      - skontoDeadline
      - revision
      - hasBillOfQuantities
      - absoluteDiscount
      - additionalCosts
      - skontoValue
      - totalNetWithDiscount
      - taxValue
      - totalGross
      - totalGrossWithSkonto
      - submittedAt
      - version
      type: object
      additionalProperties: false
    UpdateFileTreeItemInput:
      properties:
        name:
          type: string
          description: New name for the file or folder. Cannot be empty or whitespace-only.
          pattern: \S
        parentId:
          type: string
          description: ID of the folder to move the item into. Use `root` to move the item to the top of the file tree.
      type: object
      additionalProperties: false
    CreateFileTreeFolderInput:
      properties:
        name:
          type: string
          description: Name of the folder to create. Cannot be empty or whitespace-only.
          pattern: \S
      required:
      - name
      type: object
      additionalProperties: false
    FileTreeFileResponse:
      properties:
        id:
          type: string
          description: ID of the file node.
        type:
          type: string
          enum:
          - file
          description: Discriminator indicating that this item is a file.
        name:
          type: string
          description: File name (including extension).
        path:
          items:
            type: string
          type: array
          description: Path to the file expressed as an array of folder names from the root of the file tree down to (but not including) the file itself.
        parentId:
          type: string
          description: ID of the folder containing this file. Equal to `root` when the file sits at the top of the tree.
        size:
          type: number
          format: double
          description: Size of the file in bytes.
        uploadedAt:
          type: string
          description: ISO 8601 timestamp at which the file was uploaded.
        uploadedBy:
          $ref: '#/components/schemas/UserResponse'
          description: User who uploaded the file, if known.
      required:
      - id
      - type
      - name
      - path
      - parentId
      - size
      - uploadedAt
      type: object
      additionalProperties: false
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    ErrorResponse:
      properties:
        message:
          type: string
        meta:
          properties:
            fieldErrors:
              $ref: '#/components/schemas/FieldErrors'
          required:
          - fieldErrors
          type: object
      required:
      - message
      type: object
      additionalProperties: false
  securitySchemes:
    accessKey:
      type: http
      scheme: bearer
      bearerFormat: JWT