openapi: 3.0.3
info:
  title: Legacy Office Upgrade API
  version: 1.0.0
  description: >-
    Asynchronously converts valid Microsoft Office 97-2003 DOC, PPT, and XLS
    files to DOCX, PPTX, and XLSX. Only successful, structurally validated
    conversions are metered through AWS Marketplace.
  contact:
    name: CoreNova Support
    email: support@corenovacloud.com
  license:
    name: Standard Contract for AWS Marketplace 2022-07-14
    url: https://s3.amazonaws.com/aws-mp-standard-contracts/Standard-Contact-for-AWS-Marketplace-2022-07-14.pdf
servers:
  - url: https://api.corenovacloud.com
    description: Production
tags:
  - name: Conversions
    description: Submit one legacy Office file and retrieve its asynchronous task state.
security:
  - bearerAuth: []
paths:
  /v1/conversions:
    post:
      tags: [Conversions]
      summary: Submit one legacy Office file
      operationId: createConversion
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: Reuse only with the identical file to return the original task.
          schema:
            type: string
            minLength: 8
            maxLength: 128
            pattern: '^[A-Za-z0-9._:-]+$'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: A DOC, PPT, or XLS file no larger than 4 MiB.
            encoding:
              file:
                contentType: application/octet-stream
      responses:
        '202':
          description: File securely stored and task queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskSubmission'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '503':
          $ref: '#/components/responses/Unavailable'
  /v1/conversions/{task_id}:
    get:
      tags: [Conversions]
      summary: Get conversion task state
      operationId: getConversion
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{32}$'
      responses:
        '200':
          description: Current task state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Marketplace API key
  schemas:
    TaskStatus:
      type: string
      enum: [SUBMITTING, QUEUED, PROCESSING, SUCCEEDED, FAILED, EXPIRED]
    TaskSubmission:
      type: object
      required: [task_id, status, status_url, idempotent_replay]
      properties:
        task_id:
          type: string
          pattern: '^[0-9a-f]{32}$'
        status:
          $ref: '#/components/schemas/TaskStatus'
        status_url:
          type: string
          format: uri
        idempotent_replay:
          type: boolean
    Task:
      type: object
      required: [task_id, status]
      properties:
        task_id:
          type: string
        status:
          $ref: '#/components/schemas/TaskStatus'
        source_filename:
          type: string
        dimension:
          type: string
          enum: [DocConversion, PptConversion, XlsConversion]
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
        result_size:
          type: integer
          format: int64
        result_expires_at:
          type: integer
          format: int64
        download_url:
          type: string
          format: uri
        download_expires_in:
          type: integer
          example: 300
        error:
          $ref: '#/components/schemas/TaskError'
    TaskError:
      type: object
      required: [code, docs_url]
      properties:
        code:
          type: string
        docs_url:
          type: string
          format: uri
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, docs_url]
          properties:
            code:
              type: string
            message:
              type: string
            docs_url:
              type: string
              format: uri
  responses:
    BadRequest:
      description: The request or file metadata is invalid.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    Unauthorized:
      description: The API credential is missing or invalid.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    Forbidden:
      description: The Marketplace license is inactive or belongs to another product.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    NotFound:
      description: The task does not exist or belongs to another tenant.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    Conflict:
      description: The idempotency key was used for different content.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    PayloadTooLarge:
      description: The file is larger than 4 MiB.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    UnsupportedMediaType:
      description: The request is not multipart form data.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
    Unavailable:
      description: The task could not be stored or queued; retry safely.
      content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}
