openapi: 3.0.3
info:
  title: JAGGAER ASO Quay Optimization API
  description: >
    The Quay API provides REST endpoints for submitting, managing, and tracking
    optimization jobs within the JAGGAER Advanced Sourcing Optimizer platform.
    It supports job submission for sourcing optimization scenarios, job
    cancellation, and status monitoring. Customer-specific daily and absolute
    rate limits are enforced via HTTP 429 responses. Authentication is performed
    using API key headers for all operations.
  version: '1.0'
  contact:
    name: JAGGAER Support
    url: https://www.jaggaer.com/support
  x-api-id: jaggaer-aso-quay
servers:
  - url: https://quay.aso-api.jaggaer.com
    description: JAGGAER ASO Quay Production Server
tags:
  - name: Jobs
    description: Optimization job management operations
security:
  - apiKeyHeader: []
paths:
  /submitJob:
    post:
      operationId: submitJob
      summary: Submit Job
      description: >
        Submits an optimization job to the Quay service for processing by the
        JAGGAER Advanced Sourcing Optimizer. The consumer, customer, and event
        identifiers are required, along with the location of the input file on
        the ASO filesystem. Customers have both daily and absolute rate limits
        enforced at this endpoint.
      tags:
        - Jobs
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.sciquest.com.quay+json
          description: >
            Must be set to application/vnd.sciquest.com.quay+json.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.sciquest.com.quay+json
          description: >
            Must be set to application/vnd.sciquest.com.quay+json.
      requestBody:
        required: true
        content:
          application/vnd.sciquest.com.quay+json:
            schema:
              $ref: '#/components/schemas/SubmitJobRequest'
            example:
              consumer: JCS
              customerId: 999
              customerName: QA
              eventId: 999999
              inputFilename: /dgsq/drm/JCS_Input/tester.txt.gz
      responses:
        '200':
          description: >
            Success; the optimization job was successfully submitted to the Quay
            service.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/SubmitJobResponse'
              example:
                statuses:
                  SUCCESS:
                    - jobId: 414
        '422':
          description: >
            Unprocessable Entity; the job submission could not be validated.
            Reasons include invalid enum values, missing required fields,
            exceeded character limits, or input file not found on the ASO
            filesystem.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/QuayErrorResponse'
        '429':
          description: >
            Too Many Requests; the customer has exceeded their configured daily
            or absolute optimization job limit.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/QuayRateLimitResponse'
  /cancelJob/{job-id}:
    post:
      operationId: cancelJob
      summary: Cancel Job
      description: >
        Cancels the specified optimization job. A 201 response indicates the
        job was successfully cancelled. If the job cannot be found or has
        already terminated, an appropriate error is returned.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/jobId'
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.sciquest.com.quay+json
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.sciquest.com.quay+json
      responses:
        '201':
          description: >
            Success; the job was successfully cancelled.
        '404':
          description: No job found with the specified job ID.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/QuayErrorResponse'
        '422':
          description: >
            Unprocessable Entity; the job could not be cancelled. It may have
            already terminated.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/QuayErrorResponse'
  /jobStatus/{job-id}:
    get:
      operationId: getJobStatus
      summary: Job Status
      description: >
        Retrieves the current status of the specified optimization job. Status
        values indicate the progression of the job through the Quay processing
        pipeline.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/jobId'
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.sciquest.com.quay+json
      responses:
        '200':
          description: Success; returns the current status of the job.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              example:
                status: Optimizing
        '404':
          description: No job found with the specified job ID.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/QuayErrorResponse'
  /job/{job-id}:
    get:
      operationId: getJob
      summary: Job
      description: >
        Retrieves full details for the specified optimization job, including
        submission metadata, processing times, CPU usage, and working directory
        information.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/jobId'
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.sciquest.com.quay+json
      responses:
        '200':
          description: Success; returns full job details.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              example:
                jobId: 414
                consumer: JCS
                customerId: 999
                customerName: QA
                eventId: 999999
                inputFilename: /dgsq/drm/JCS_Input/tester.txt.gz
                status: Completed
                jobType: Short
                optSetType: Long
                submitTime: 1584979461000
                inprocAtSubmit: 0
                runClient: clearbox-01.exp.dev.combinenet.com
                workingDirectory: /dgsq/drm/QUAY_Service/2020/2/23/414
                processStartTime: 1584979460846
                processStopTime: 1584979462117
                cpuTime: 1271
        '404':
          description: No job found with the specified job ID.
          content:
            application/vnd.sciquest.com.quay+json:
              schema:
                $ref: '#/components/schemas/QuayErrorResponse'
components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authenticating requests to the Quay service.
  parameters:
    jobId:
      name: job-id
      in: path
      required: true
      description: Identifier for the Quay optimization job.
      schema:
        type: integer
      example: 414
  schemas:
    SubmitJobRequest:
      type: object
      required:
        - consumer
        - customerId
        - customerName
        - eventId
        - inputFilename
      description: Request body for submitting an optimization job to Quay.
      properties:
        consumer:
          type: string
          description: Consumer name identifying the system submitting the job.
          enum:
            - ASO
            - JCS
            - USDA
          example: JCS
        customerId:
          type: integer
          description: Customer identifier.
          example: 999
        customerName:
          type: string
          description: Customer name. (Max length 100)
          maxLength: 100
          example: QA
        eventId:
          type: integer
          description: Event identifier linking the job to a sourcing event.
          example: 999999
        inputFilename:
          type: string
          description: >
            Fully qualified location of the input file on the ASO filesystem.
            (Max length 100)
          maxLength: 100
          example: /dgsq/drm/JCS_Input/tester.txt.gz
        notificationHostname:
          type: string
          description: >
            ASO Clearsuite notification server hostname or VIP. Optional;
            used only within a dev environment to allow a developer to specify
            their locally configured clearsuite hostname. (Max length 250)
          maxLength: 250
          example: aso-csweb.jaggaer.com
        notificationPort:
          type: integer
          description: >
            ASO Clearsuite notification server port. Optional; used only
            within a dev environment.
          example: 80
    SubmitJobResponse:
      type: object
      description: Response for a successful job submission.
      properties:
        statuses:
          type: object
          description: >
            Map of status codes to arrays of status detail objects.
            On success, contains a SUCCESS key with the jobId.
          additionalProperties:
            type: array
            items:
              type: object
              additionalProperties:
                type: string
    JobStatusResponse:
      type: object
      description: Current status of an optimization job.
      required:
        - status
      properties:
        status:
          type: string
          description: Current processing status of the optimization job.
          enum:
            - Received
            - Queued
            - Requeued
            - Optimizing
            - Completed
            - Failed
            - Cancelled
            - Cancelling
            - Expired
            - Limited
          example: Optimizing
    JobResponse:
      type: object
      description: Full details for an optimization job.
      required:
        - jobId
        - consumer
        - customerId
        - customerName
        - eventId
        - inputFilename
        - status
        - jobType
        - optSetType
        - submitTime
        - inprocAtSubmit
        - runClient
        - workingDirectory
        - processStartTime
        - processStopTime
        - cpuTime
      properties:
        jobId:
          type: integer
          description: Quay job identifier.
          example: 414
        consumer:
          type: string
          description: Consumer name.
          enum:
            - ASO
            - JCS
            - USDA
          example: JCS
        customerId:
          type: integer
          description: Customer identifier.
          example: 999
        customerName:
          type: string
          description: Customer name.
          maxLength: 100
          example: QA
        eventId:
          type: integer
          description: Event identifier.
          example: 999999
        inputFilename:
          type: string
          description: Fully qualified input file location on ASO filesystem.
          maxLength: 100
          example: /dgsq/drm/JCS_Input/tester.txt.gz
        status:
          type: string
          description: Current status of the job.
          enum:
            - Received
            - Queued
            - Requeued
            - Optimizing
            - Completed
            - Failed
            - Cancelled
            - Cancelling
            - Expired
            - Limited
          example: Completed
        jobType:
          type: string
          description: Type of optimization job.
          enum:
            - Short
            - Long
          example: Short
        optSetType:
          type: string
          description: Type of optimization set used.
          enum:
            - Short
            - Long
          example: Long
        submitTime:
          type: integer
          description: Time the job was submitted as 13-digit Unix/epoch time.
          example: 1584979461000
        inprocAtSubmit:
          type: integer
          description: Number of jobs in process at the time this job was submitted.
          example: 0
        runClient:
          type: string
          description: Hostname of the Quay client that ran this job.
          example: clearbox-01.exp.dev.combinenet.com
        workingDirectory:
          type: string
          description: Quay working directory on the ASO filesystem.
          example: /dgsq/drm/QUAY_Service/2020/2/23/414
        processStartTime:
          type: integer
          description: Time the job started running as 13-digit Unix/epoch time.
          example: 1584979460846
        processStopTime:
          type: integer
          description: Time the job completed as 13-digit Unix/epoch time.
          example: 1584979462117
        cpuTime:
          type: integer
          description: Elapsed job runtime in milliseconds.
          example: 1271
    QuayErrorResponse:
      type: object
      description: Error response from the Quay service.
      properties:
        statuses:
          type: object
          description: >
            Map of status codes to arrays of detail objects. Common codes
            include INVALID_ENUM_VALUE, MISSING_REQUIRED_FIELD,
            EXCEEDED_CHARACTER_LIMIT, FILE_NOT_FOUND, and
            COULD_NOT_BE_CANCELLED.
          additionalProperties:
            type: array
            items:
              type: object
              additionalProperties:
                type: string
    QuayRateLimitResponse:
      type: object
      description: >
        Rate limit error response returned when a customer exceeds their
        configured optimization job limits.
      properties:
        statuses:
          type: object
          description: >
            Map of status codes to arrays of detail objects. Codes include
            EXCEEDED_DAILY_LIMIT and EXCEEDED_ABSOLUTE_LIMIT, each containing
            the customer-specific limit value.
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                limit:
                  type: integer
                  description: The customer-specific limit value that was exceeded.