Cosuno Company API

openapi: 3.2.0
info:
  title: Cosuno Company API
  version: '1'
  description: '-'
  license:
    name: '-'
  contact:
    name: '-'
servers:
- url: https://api.cosuno.com/v1
- description: current
  url: /v1
tags:
- name: Company
paths:
  /company/file-tree/{nodeId}/contents:
    get:
      operationId: GetCompanyFileTreeNodeContents
      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 your company's internal file tree.
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - description: Use `root` to get the contents of the entire file tree.
        in: path
        name: nodeId
        required: true
        schema:
          type: string
      summary: Get company file tree node contents
      x-summary-source: derived
  /company/file-tree/{nodeId}/folders:
    post:
      operationId: CreateCompanyFileTreeNodeFolders
      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 your company's internal file tree.
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - 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 company file tree node folders
      x-summary-source: derived
  /company/file-tree/{nodeId}:
    put:
      operationId: UpdateCompanyFileTreeNode
      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 your company's internal file tree (e.g. rename or move it to a different folder).
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - in: path
        name: nodeId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileTreeItemInput'
      summary: Update company file tree node
      x-summary-source: derived
    delete:
      operationId: DeleteCompanyFileTreeNode
      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 your company's internal file tree. Folders are deleted along with all their contents.
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - in: path
        name: nodeId
        required: true
        schema:
          type: string
      summary: Delete company file tree node
      x-summary-source: derived
  /company/file-tree/{nodeId}/download:
    get:
      operationId: DownloadCompanyFileTreeNode
      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 your company's internal file tree. Responds with a redirect to a time-limited download URL.
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - description: Use `root` to download the contents of the entire file tree.
        in: path
        name: nodeId
        required: true
        schema:
          type: string
      summary: Download company file tree node
      x-summary-source: derived
  /company/file-tree/{nodeId}/upload:
    post:
      operationId: UploadCompanyFileTreeFiles
      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 your company's internal file tree. To preserve folder structure, include `/`-separated paths in each uploaded file's original filename (e.g. `docs/q1/report.pdf`).
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - 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 company file tree files
      x-summary-source: derived
  /company/custom-catalogues:
    get:
      operationId: GetCustomCatalogs
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomCatalogsResponse'
              examples:
                Example 1:
                  value:
                    customCostGroupCatalogs:
                    - id: 52907745-7672-470e-a803-a2f8feb52944
                      name: DIN 276 Modified
                      changedByUserId: 09f46d4e-b128-4f7e-ae8a-e955d6519c94
                      companyId: 32308724-2336-414c-b250-01ce9ff38000
                      status: active
                      createdAt: '2021-06-21T12:00:00.000Z'
                      updatedAt: '2021-06-21T12:00:00.000Z'
                      deletedAt: null
                    totalRecords: 1
        '401':
          description: Unauthorized
          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: List the custom cost group catalogs defined in your company.
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - description: Number of catalogs to skip before returning results; used together with `limit` to paginate.
        in: query
        name: offset
        required: true
        schema:
          format: int32
          type: integer
          minimum: 0
          maximum: 10000
      - description: Maximum number of catalogs to return in a single response.
        in: query
        name: limit
        required: true
        schema:
          format: int32
          type: integer
          minimum: 1
          maximum: 10000
      summary: Get custom catalogs
      x-summary-source: derived
    post:
      operationId: CreateCustomCatalog
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomCatalogWithGroupsResponse'
        '401':
          description: Unauthorized
          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 new custom cost group catalog in your company, including its hierarchical cost group tree.
      tags:
      - Company
      security:
      - accessKey: []
      parameters: []
      requestBody:
        description: Catalog details, including its display name and the hierarchical structure of cost groups it contains.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomCatalogInput'
              description: Catalog details, including its display name and the hierarchical structure of cost groups it contains.
      summary: Create custom catalog
      x-summary-source: derived
  /company/custom-catalogues/{id}:
    put:
      operationId: UpdateCustomCatalog
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomCatalogWithGroupsResponse'
        '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 an existing custom cost group catalog. Only provided fields are modified. Supplying `costGroups` replaces the entire cost group tree: cost groups with an `id` are updated in place, entries without an `id` are created, and any existing cost groups not present in the payload are deleted.'
      tags:
      - Company
      security:
      - accessKey: []
      parameters:
      - description: The ID of the custom cost group catalog to update.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        description: Fields to update on the catalog.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomCatalogInput'
              description: Fields to update on the catalog.
      summary: Update custom catalog
      x-summary-source: derived
components:
  schemas:
    CreateCustomCatalogInput:
      properties:
        name:
          type: string
          description: Display name of the catalog.
        costGroups:
          items:
            $ref: '#/components/schemas/CreateCustomCatalogCostGroupInput'
          type: array
          description: Hierarchical cost groups that make up the catalog.
      required:
      - name
      - costGroups
      type: object
      additionalProperties: false
    CUSTOM_COST_GROUP_CATALOG_STATUS:
      type: string
      enum:
      - active
      - deactivated
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    FileTreeItemResponse:
      anyOf:
      - $ref: '#/components/schemas/FileTreeFileResponse'
      - $ref: '#/components/schemas/FileTreeFolderResponse'
    CustomCatalogsResponse:
      properties:
        customCostGroupCatalogs:
          items:
            $ref: '#/components/schemas/CustomCatalog'
          type: array
          description: Custom cost group catalogs matching the request.
        totalRecords:
          type: number
          format: double
          description: Total number of custom cost group catalogs in your company, regardless of `offset` and `limit`.
      required:
      - customCostGroupCatalogs
      - totalRecords
      type: object
      additionalProperties: false
    CustomCatalog:
      properties:
        id:
          type: string
          description: ID of the custom cost group catalog.
        name:
          type: string
          description: Display name of the catalog.
        status:
          $ref: '#/components/schemas/CUSTOM_COST_GROUP_CATALOG_STATUS'
          description: Current status of the catalog. Deactivated catalogs can no longer be assigned to new projects.
        changedByUserId:
          type: string
          description: ID of the user who last changed the catalog.
        companyId:
          type: string
          description: ID of the company the catalog belongs to.
        createdAt:
          type: string
          format: date-time
          description: Timestamp at which the catalog was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp at which the catalog was last updated.
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp at which the catalog was deleted, or `null` if the catalog has not been deleted.
      required:
      - id
      - name
      - status
      - changedByUserId
      - companyId
      - createdAt
      - updatedAt
      - deletedAt
      type: object
      additionalProperties: false
    UpdateCustomCatalogInput:
      properties:
        name:
          type: string
          description: New display name for the catalog.
        status:
          $ref: '#/components/schemas/CUSTOM_COST_GROUP_CATALOG_STATUS'
          description: New status for the catalog. Use `deactivated` to retire the catalog so it can no longer be assigned to new projects.
        costGroups:
          items:
            $ref: '#/components/schemas/UpdateCustomCatalogCostGroupInput'
          type: array
          description: Replacement hierarchical cost groups for the catalog. Cost groups with an `id` are updated in place, entries without an `id` are created, and any existing cost groups not present in the payload are deleted.
      type: object
      additionalProperties: false
    USER_TYPE:
      type: string
      enum:
      - custom
      - administrator
      - employee
      - guest
      - collaborator
      - manager
    USER_STATUS:
      type: string
      enum:
      - approvalPending
      - adminApprovalPending
      - invited
      - inviteCanceled
      - inviteFailed
      - inviteRequested
      - active
      - inactive
    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
    ErrorResponse:
      properties:
        message:
          type: string
        meta:
          properties:
            fieldErrors:
              $ref: '#/components/schemas/FieldErrors'
          required:
          - fieldErrors
          type: object
      required:
      - message
      type: object
      additionalProperties: false
    UpdateCustomCatalogCostGroupInput:
      properties:
        id:
          type: string
          description: ID of an existing cost group to update. If omitted, a new cost group is created instead.
        localId:
          type: string
          description: Stable identifier for the cost group within the catalog (e.g. a cost group code like `300` or `310.1`). Must be unique within the catalog.
        name:
          type: string
          description: Display name of the cost group.
        childCostGroups:
          items:
            $ref: '#/components/schemas/UpdateCustomCatalogCostGroupInput'
          type: array
          description: Nested cost groups for a hierarchical catalog structure.
      required:
      - localId
      - name
      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
    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
    CustomCatalogWithGroupsResponse:
      properties:
        id:
          type: string
          description: ID of the custom cost group catalog.
        name:
          type: string
          description: Display name of the catalog.
        status:
          $ref: '#/components/schemas/CUSTOM_COST_GROUP_CATALOG_STATUS'
          description: Current status of the catalog.
        costGroups:
          items:
            $ref: '#/components/schemas/CustomCatalogCostGroupResponse'
          type: array
          description: Hierarchical cost groups that make up the catalog.
      required:
      - id
      - name
      - status
      - costGroups
      type: object
      additionalProperties: false
    CustomCatalogCostGroupResponse:
      properties:
        id:
          type: string
          description: ID of the cost group.
        localId:
          type: string
          description: Stable identifier of the cost group within the catalog (e.g. a cost group code like `300` or `310.1`).
        name:
          type: string
          description: Display name of the cost group.
        childCostGroups:
          items:
            $ref: '#/components/schemas/CustomCatalogCostGroupResponse'
          type: array
          description: Nested cost groups within this cost group.
      required:
      - id
      - localId
      - name
      type: object
      additionalProperties: false
    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
    CreateCustomCatalogCostGroupInput:
      properties:
        localId:
          type: string
          description: Stable identifier for the cost group within the catalog (e.g. a cost group code like `300` or `310.1`). Must be unique within the catalog.
        name:
          type: string
          description: Display name of the cost group.
        childCostGroups:
          items:
            $ref: '#/components/schemas/CreateCustomCatalogCostGroupInput'
          type: array
          description: Nested cost groups for a hierarchical catalog structure.
      required:
      - localId
      - name
      type: object
      additionalProperties: false
  securitySchemes:
    accessKey:
      type: http
      scheme: bearer
      bearerFormat: JWT