openapi: 3.0.3
info:
  title: Integration Hub Managed File Transfer API
  version: 2.0.0
  description: |
    Thin API layer for Managed File Transfer uploads.

    Small files can use a single pre-signed S3 PUT.
    Large files automatically switch to a multipart upload flow so the client
    ingress path can support uploads larger than 5 GB.
servers:
  - url: /
    description: Same origin as the deployed Swagger UI or API hostname.
security:
  - basicAuth: []
  - bearerAuth: []
tags:
  - name: Transfer Tickets
    description: Create upload sessions for small and large files.
  - name: Multipart Uploads
    description: Continue, complete, or abort multipart transfers.
paths:
  /transfer-tickets:
    post:
      tags:
        - Transfer Tickets
      summary: Create an upload transfer ticket
      description: |
        Creates either:
        - a single PUT upload ticket for smaller files, or
        - a multipart upload session for larger files.

        The client supplies `sizeBytes` and the API decides which upload path to use.
      operationId: createTransferTicket
      security:
        - basicAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferTicketRequest'
      responses:
        '200':
          description: Upload session created
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SingleUploadTicketResponse'
                  - $ref: '#/components/schemas/MultipartUploadTicketResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /transfer-tickets/{transferTicket}/parts:
    post:
      tags:
        - Multipart Uploads
      summary: Generate pre-signed multipart part URLs
      operationId: presignMultipartParts
      security:
        - basicAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TransferTicket'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultipartPartRequest'
      responses:
        '200':
          description: Pre-signed part URLs generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipartPartResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
  /transfer-tickets/{transferTicket}/complete:
    post:
      tags:
        - Multipart Uploads
      summary: Complete a multipart upload
      operationId: completeMultipartUpload
      security:
        - basicAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TransferTicket'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultipartCompleteRequest'
      responses:
        '200':
          description: Multipart upload completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipartCompleteResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
  /transfer-tickets/{transferTicket}:
    delete:
      tags:
        - Multipart Uploads
      summary: Abort a multipart upload
      operationId: abortMultipartUpload
      security:
        - basicAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TransferTicket'
      responses:
        '200':
          description: Multipart upload aborted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipartAbortResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    TransferTicket:
      name: transferTicket
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    ErrorResponse:
      description: Request failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic auth using a Secrets Manager-managed username/password.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque token in the form tokenId.bearerToken
      description: Bearer token using a Secrets Manager-managed token pair.
  schemas:
    TransferTicketRequest:
      type: object
      required:
        - clientId
        - fileName
        - sizeBytes
      properties:
        clientId:
          type: string
          example: products-poc
        fileName:
          type: string
          example: example-upload.csv
        contentType:
          type: string
          example: text/csv
        sizeBytes:
          type: integer
          format: int64
          example: 12345
        requestedExpirySeconds:
          type: integer
          example: 900
        contentMd5:
          type: string
          description: Base64-encoded MD5 digest for single PUT uploads only
          example: CY9rzUYh03PK3k6DJie09g==
    ObjectReference:
      type: object
      required:
        - bucket
        - key
      properties:
        bucket:
          type: string
        key:
          type: string
    PresignedSingleUpload:
      type: object
      required:
        - method
        - url
        - headers
        - expiresInSeconds
      properties:
        method:
          type: string
          example: PUT
        url:
          type: string
          format: uri
        headers:
          type: object
          additionalProperties:
            type: string
        expiresInSeconds:
          type: integer
    SingleUploadTicketResponse:
      type: object
      required:
        - transferTicket
        - clientId
        - upload
        - object
      properties:
        transferTicket:
          type: string
          format: uuid
        clientId:
          type: string
        upload:
          $ref: '#/components/schemas/PresignedSingleUpload'
        object:
          $ref: '#/components/schemas/ObjectReference'
    MultipartOperationPaths:
      type: object
      required:
        - presignPartsPath
        - completePath
        - abortPath
      properties:
        presignPartsPath:
          type: string
        completePath:
          type: string
        abortPath:
          type: string
    MultipartPart:
      type: object
      required:
        - partNumber
        - method
        - url
        - headers
        - expiresInSeconds
      properties:
        partNumber:
          type: integer
        method:
          type: string
          example: PUT
        url:
          type: string
          format: uri
        headers:
          type: object
          additionalProperties:
            type: string
        expiresInSeconds:
          type: integer
    MultipartUploadSession:
      type: object
      required:
        - uploadId
        - partSizeBytes
        - maxParts
        - expiresInSeconds
        - initialParts
        - operations
      properties:
        uploadId:
          type: string
        partSizeBytes:
          type: integer
          format: int64
        totalParts:
          type: integer
          nullable: true
        maxParts:
          type: integer
        expiresInSeconds:
          type: integer
        initialParts:
          type: array
          items:
            $ref: '#/components/schemas/MultipartPart'
        operations:
          $ref: '#/components/schemas/MultipartOperationPaths'
    MultipartUploadTicketResponse:
      type: object
      required:
        - transferTicket
        - clientId
        - object
        - multipart
      properties:
        transferTicket:
          type: string
          format: uuid
        clientId:
          type: string
        object:
          $ref: '#/components/schemas/ObjectReference'
        multipart:
          $ref: '#/components/schemas/MultipartUploadSession'
    MultipartPartRequest:
      type: object
      description: Provide either `partNumbers` or `partNumberStart` and `partNumberEnd`.
      properties:
        partNumbers:
          type: array
          items:
            type: integer
        partNumberStart:
          type: integer
        partNumberEnd:
          type: integer
    MultipartPartResponse:
      type: object
      required:
        - transferTicket
        - clientId
        - uploadId
        - parts
      properties:
        transferTicket:
          type: string
          format: uuid
        clientId:
          type: string
        uploadId:
          type: string
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MultipartPart'
    MultipartCompletedPart:
      type: object
      required:
        - partNumber
        - eTag
      properties:
        partNumber:
          type: integer
        eTag:
          type: string
    MultipartCompleteRequest:
      type: object
      required:
        - parts
      properties:
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MultipartCompletedPart'
    MultipartCompleteResponse:
      type: object
      required:
        - transferTicket
        - clientId
        - status
        - object
        - result
      properties:
        transferTicket:
          type: string
          format: uuid
        clientId:
          type: string
        status:
          type: string
          enum: [completed]
        object:
          $ref: '#/components/schemas/ObjectReference'
        result:
          type: object
          properties:
            eTag:
              type: string
            location:
              type: string
            partCount:
              type: integer
    MultipartAbortResponse:
      type: object
      required:
        - transferTicket
        - clientId
        - status
      properties:
        transferTicket:
          type: string
          format: uuid
        clientId:
          type: string
        status:
          type: string
          enum: [aborted]
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string