Phasio Manufacturer Part Revision Controller API

openapi: 3.2.0
info:
  title: Phasio Manufacturer Part Revision Controller API
  description: This is the API documentation for the Phasio application.
  version: '1.0'
servers:
- url: https://m-api.eu.phas.io
  description: Generated server url
security:
- Phasio API Bearer Token: []
tags:
- name: Manufacturer Part Revision Controller
  description: Endpoints for managing part geometry revisions and 3D file analysis
paths:
  /api/manufacturer/v1/part-revision/{partRevisionId}/version-name:
    put:
      tags:
      - Manufacturer Part Revision Controller
      summary: Set part revision version name
      description: Sets a custom revision name (e.g. the customer's own revision reference) shown in place of the version number
      operationId: updateVersionName
      parameters:
      - name: partRevisionId
        in: path
        description: ID of the part revision to update
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePartRevisionVersionNameDto'
        required: true
      responses:
        '200':
          description: Version name updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartRevisionDto'
        '400':
          description: Version name exceeds 64 characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'Part revision not found (error code: PART_REVISION_NOT_FOUND)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/upload:
    put:
      tags:
      - Manufacturer Part Revision Controller
      summary: Upload part revision
      description: Uploads a 3D model file for analysis and creates a new part revision
      operationId: uploadPartRevision
      parameters:
      - name: designId
        in: query
        description: ID of the design to associate with this revision (optional)
        required: false
        schema:
          type: string
          format: uuid
      - name: customerOrganisationId
        in: query
        description: ID of the customer organization (optional)
        required: false
        schema:
          type: integer
          format: int64
      - name: X-Filename
        in: header
        description: Original filename of the file
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 3D model file to upload
              required:
              - file
      responses:
        '200':
          description: File upload and analysis started
          content:
            application/json:
              schema:
                type: string
                format: uuid
        '400':
          description: Invalid file or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/recognize:
    post:
      tags:
      - Manufacturer Part Revision Controller
      summary: Recognize a single part from a camera image
      description: Analyses an image and returns the top-N most visually similar part revisions. This is a simpler, 'raw' alternative to the /detect-and-embed endpoint
      operationId: recognizeByImage
      parameters:
      - name: count
        in: query
        description: Maximum number of results to return (1-100)
        required: false
        schema:
          type: integer
          format: int64
          maximum: 100
          minimum: 1
        example: 5
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: byte
        required: true
      responses:
        '200':
          description: Top-N matching part revisions with their similarity scores
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Empty or invalid image body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/detect-and-embed:
    post:
      tags:
      - Manufacturer Part Revision Controller
      summary: Detect parts in an image and find similar part revisions per detection
      description: Detect parts in the image and, for each detected part, returns the top-N visually similar part revisions. Bounding boxes are in original-image pixel coordinates ([x, y, width, height]) so the consumer can overlay them on the uploaded image.
      operationId: detectAndEmbed
      parameters:
      - name: count
        in: query
        description: Maximum number of similar part revisions per detection (1-100)
        required: false
        schema:
          type: integer
          format: int64
          maximum: 100
          minimum: 1
        example: 10
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: byte
        required: true
      responses:
        '200':
          description: Per-detection bounding boxes with their top-N matching part revisions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartImageDetectionResponseDto'
        '400':
          description: Empty or invalid image body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/bulk:
    post:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get multiple part revisions by IDs
      description: Retrieves multiple part revisions by their IDs
      operationId: getBulk
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: Set of part revision IDs to retrieve
              items:
                type: string
                format: uuid
              uniqueItems: true
        required: true
      responses:
        '200':
          description: Part revisions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartRevisionDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get part revisions with filtering
      description: Retrieves a paginated list of part revisions with optional filtering and search
      operationId: get_8
      parameters:
      - name: filter
        in: query
        description: filter specification
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Zero-based page index (0..N)
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: size
        in: query
        description: The size of the page to be returned
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
      - name: sort
        in: query
        description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        required: false
        schema:
          type: array
          default:
          - createdAt,DESC
          items:
            type: string
      - name: search
        in: query
        description: Optional search term
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved part revisions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated'
        '400':
          description: 'Invalid filter specification (error code: INVALID_FILTER)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/{partRevisionId}:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get part revision by ID
      description: Retrieves a specific part revision by its ID
      operationId: getById_4
      parameters:
      - name: partRevisionId
        in: path
        description: ID of the part revision to retrieve
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Part revision found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartRevisionDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'Part revision not found (error code: PART_REVISION_NOT_FOUND)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/{partRevisionId}/thumbnail:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Retrieve a thumbnail image of a part revision
      description: Retrieves a PNG format thumbnail image for a part revision
      operationId: downloadThumbnail
      parameters:
      - name: partRevisionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Thumbnail retrieved successfully
          content:
            image/png: {}
        '404':
          description: Thumbnail not found (error code REQUISITION_THUMBNAIL_NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/{partRevisionId}/download/{type}:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Download part revision file
      description: Downloads a specific file type associated with a part revision
      operationId: downloadFile
      parameters:
      - name: partRevisionId
        in: path
        description: ID of the part revision
        required: true
        schema:
          type: string
          format: uuid
      - name: type
        in: path
        description: Type of file to download
        required: true
        schema:
          type: string
          enum:
          - ORIGINAL_CAD_FILE
          - CORE_GEOMETRY
          - THUMBNAIL
          - PDF_DESIGN_FILE
          - WALL_THICKNESS_ANALYSIS
      responses:
        '200':
          description: File downloaded successfully
          content:
            application/octet-stream: {}
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: File not found (error code PART_REVISION_FILE_NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/upload/{analysisId}/results:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get file analysis results
      description: Retrieves the results and processed file for a completed analysis as a MessagePack payload
      operationId: getUploadResults
      parameters:
      - name: analysisId
        in: path
        description: ID of the analysis to retrieve results for
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Analysis results retrieved
          content:
            application/msgpack: {}
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Analysis results not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/upload/status:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get file analysis status
      description: Checks the processing status of uploaded 3D model files
      operationId: getUploadStatus
      parameters:
      - name: analysisIds
        in: query
        description: Set of analysis IDs to check status for
        required: true
        schema:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
      responses:
        '200':
          description: File analysis status retrieved
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/requisition/{requisitionId}:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get part revisions by requisition ID
      description: Retrieves all part revisions associated with a specific requisition
      operationId: getByRequisition
      parameters:
      - name: requisitionId
        in: path
        description: ID of the requisition to get part revisions for
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Part revisions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartRevisionDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/order/{orderId}:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get part revisions by order ID
      description: Retrieves all part revisions associated with a specific order
      operationId: getByOrder_1
      parameters:
      - name: orderId
        in: path
        description: ID of the order to get part revisions for
        required: true
        schema:
          type: integer
          format: int64
      - name: includeHistory
        in: query
        description: Whether to include historical revisions
        required: false
        schema:
          type: boolean
        example: false
      responses:
        '200':
          description: Part revisions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartRevisionDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/part-revision/design/{designId}:
    get:
      tags:
      - Manufacturer Part Revision Controller
      summary: Get part revisions by design ID
      description: Retrieves all part revisions associated with a specific design
      operationId: getByDesign
      parameters:
      - name: designId
        in: path
        description: ID of the design to get part revisions for
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Part revisions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartRevisionDto'
        '401':
          description: Unauthorized - operator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    BendDetailDto:
      type: object
      properties:
        radiusInner:
          type: number
        sweepDeg:
          type: number
        length:
          type: number
        axisStart:
          type: array
          items:
            type: number
        axisEnd:
          type: array
          items:
            type: number
        axisDir:
          type: array
          items:
            type: number
        arcStartDir:
          type: array
          items:
            type: number
      required:
      - arcStartDir
      - axisDir
      - axisEnd
      - axisStart
      - length
      - radiusInner
      - sweepDeg
    MachiningSetupsDto:
      type: object
      properties:
        threeAxis:
          $ref: '#/components/schemas/AxisSetupsDto'
        fiveAxis:
          $ref: '#/components/schemas/FiveAxisSetupsDto'
        accessibleAreaFraction:
          $ref: '#/components/schemas/ObbAccessibilityDto'
        sampleCount:
          type: integer
      required:
      - accessibleAreaFraction
      - fiveAxis
      - sampleCount
      - threeAxis
    SetupDirectionDto:
      type: object
      properties:
        direction:
          type: array
          items:
            type: number
        assignedAreaFraction:
          type: number
        holeCount:
          type: integer
      required:
      - assignedAreaFraction
      - direction
      - holeCount
    HoleGroupDto:
      type: object
      properties:
        diameter:
          type: number
        depth:
          type: number
        through:
          type: boolean
        flatBottom:
          type: boolean
        counterboreDiameter:
          type: number
        counterboreDepth:
          type: number
        countersinkDiameter:
          type: number
        axis:
          type: array
          items:
            type: number
        entryPoint:
          type: array
          items:
            type: number
        count:
          type: integer
        entryPoints:
          type: array
          items:
            type: array
            items:
              type: number
      required:
      - axis
      - count
      - depth
      - diameter
      - entryPoint
      - entryPoints
      - flatBottom
      - through
    PartImageDetectionDto:
      type: object
      properties:
        bbox:
          type: array
          items:
            type: integer
            format: int32
        matches:
          type: object
          additionalProperties:
            type: number
            format: double
      required:
      - bbox
      - matches
    Paginated:
      type: object
      properties:
        content:
          type: array
          items: {}
        totalElements:
          type: integer
        totalPages:
          type: integer
        pageNumber:
          type: integer
        pageSize:
          type: integer
        isEmpty:
          type: boolean
        isFirst:
          type: boolean
        isLast:
          type: boolean
      required:
      - content
      - isEmpty
      - isFirst
      - isLast
      - pageNumber
      - pageSize
      - totalElements
      - totalPages
    MachiningDetailsDto:
      type: object
      properties:
        schemaVersion:
          type: integer
          format: int32
        holes:
          type: array
          items:
            $ref: '#/components/schemas/HoleGroupDto'
        pockets:
          type: array
          items:
            $ref: '#/components/schemas/PocketGroupDto'
        totalFaceArea:
          type: number
        setups:
          $ref: '#/components/schemas/MachiningSetupsDto'
        finishing:
          $ref: '#/components/schemas/MachiningFinishingDto'
        warnings:
          type: array
          items:
            type: string
      required:
      - schemaVersion
      - totalFaceArea
      - warnings
    MachiningFinishingDto:
      type: object
      properties:
        floorArea:
          type: number
        wallArea:
          type: number
        ballEndArea:
          type: number
        unreachableArea:
          type: number
      required:
      - ballEndArea
      - floorArea
      - unreachableArea
      - wallArea
    UpdatePartRevisionVersionNameDto:
      type: object
      properties:
        versionName:
          type: string
          maxLength: 64
          minLength: 0
    FiveAxisSetupsDto:
      type: object
      properties:
        count:
          type: integer
        tiltLimitDeg:
          type: number
        setups:
          type: array
          items:
            $ref: '#/components/schemas/SetupDirectionDto'
        unreachableAreaFraction:
          type: number
      required:
      - count
      - setups
      - tiltLimitDeg
      - unreachableAreaFraction
    PocketGroupDto:
      type: object
      properties:
        depth:
          type: number
        mouthArea:
          type: number
        volume:
          type: number
        volumeExact:
          type: boolean
        minCornerRadius:
          type: number
        minWidth:
          type: number
        through:
          type: boolean
        direction:
          type: array
          items:
            type: number
        count:
          type: integer
        mouthCenters:
          type: array
          items:
            type: array
            items:
              type: number
      required:
      - count
      - depth
      - direction
      - mouthArea
      - mouthCenters
      - through
      - volume
      - volumeExact
    AxisSetupsDto:
      type: object
      properties:
        count:
          type: integer
        setups:
          type: array
          items:
            $ref: '#/components/schemas/SetupDirectionDto'
        unreachableAreaFraction:
          type: number
      required:
      - count
      - setups
      - unreachableAreaFraction
    ApiError:
      type: object
      additionalProperties: true
      description: Stable error contract. `error` is a SCREAMING_SNAKE code that clients match on; `message` is a human-readable sentence. Some errors add extra string fields (for example organisationId).
      properties:
        error:
          type: string
          example: ORDER_NOT_FOUND
        message:
          type: string
          example: Order not found
      required:
      - error
      - message
    PartImageDetectionResponseDto:
      type: object
      properties:
        detections:
          type: array
          items:
            $ref: '#/components/schemas/PartImageDetectionDto'
      required:
      - detections
    ObbAccessibilityDto:
      type: object
      properties:
        xPlus:
          type: number
        xMinus:
          type: number
        yPlus:
          type: number
        yMinus:
          type: number
        zPlus:
          type: number
        zMinus:
          type: number
      required:
      - xMinus
      - xPlus
      - yMinus
      - yPlus
      - zMinus
      - zPlus
    PartRevisionDto:
      type: object
      properties:
        partRevisionId:
          type: string
          format: uuid
        designName:
          type: string
        designId:
          type: string
          format: uuid
        availableAccessories:
          type: array
          items:
            type: string
            enum:
            - ORIGINAL_CAD_FILE
            - CORE_GEOMETRY
            - THUMBNAIL
            - PDF_DESIGN_FILE
            - WALL_THICKNESS_ANALYSIS
        volume:
          type: number
        area:
          type: number
        height:
          type: number
        width:
          type: number
        depth:
          type: number
        minimumWallThickness:
          type: number
        minBoundingBoxVolume:
          type: number
        convexHullVolume:
          type: number
        shrinkWrapVolume:
          type: number
        bendCount:
          type: integer
        sheetThickness:
          type: number
        blankArea:
          type: number
        bendDetails:
          type: array
          items:
            $ref: '#/components/schemas/BendDetailDto'
        holeCount:
          type: integer
        pocketCount:
          type: integer
        threeAxisSetupCount:
          type: integer
        fiveAxisSetupCount:
          type: integer
        minInternalCornerRadius:
          type: number
        unrecognizedConcaveArea:
          type: number
        machiningDetails:
          $ref: '#/components/schemas/MachiningDetailsDto'
        createdAt:
          type: string
          format: date-time
        versionNumber:
          type: integer
          format: int64
        versionName:
          type: string
        isLatestRevision:
          type: boolean
        repaired:
          type: boolean
        watertight:
          type: boolean
        originalCADFileType:
          type: string
          enum:
          - STL
          - OBJ
          - WRL
          - STEP
          - STP
          - IGES
          - IGS
          - THREEMF
          - DXF
          - ZIP
          - THREEDS
          - BLEND
          - DAE
          - FBX
          - BREP
          - BDF
          - MSH
          - INP
          - DIFF
          - MESH
          - CTM
          - PLY
          - 'OFF'
          - COLLADA
          - GLTF
          - XAML
          - THREEDXML
          - XYZ
          - X_T
          - SLDPRT
        conflictOnHash:
          type: string
        baseRotationMatrix:
          type: array
          items:
            type: number
        deleted:
          type: boolean
      required:
      - availableAccessories
      - deleted
      - designName
  securitySchemes:
    Phasio_API_Bearer_Token:
      type: http
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: JWT