openapi: 3.2.0
info:
  title: Graphiant Software API
  version: 1.0.0
  description: Graphiant API documentation.
servers:
- url: https://api.graphiant.com
security:
- jwtAuth: []
tags:
- name: Software
paths:
  /v1/software/rollouts:
    post:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1SoftwareRolloutsPostRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRolloutsPostResponse'
      description: Create upgrade rollout and returns rollout identifier
      tags:
      - Software
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRolloutsGetResponse'
      description: Returns all the configured upgrade rollouts
      tags:
      - Software
    put:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1SoftwareRolloutsPutRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRolloutsPutResponse'
      description: Modify update rollout
      tags:
      - Software
  /v1/software/rollouts/{id}:
    delete:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      - name: id
        in: path
        required: true
        description: Rollout identifier to delete.
        schema:
          type: integer
          format: int64
          example: 1234567891011
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRolloutsIdDeleteResponse'
      description: Delete given upgrade rollout
      tags:
      - Software
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      - name: id
        in: path
        required: true
        description: Rollout identifier to fetch.
        schema:
          type: integer
          format: int64
          example: 1234567891011
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRolloutsIdGetResponse'
      description: Returns details about given upgrade rollout
      tags:
      - Software
  /v1/software/auto-upgrade/default:
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareAutoUpgradeDefaultGetResponse'
      tags:
      - Software
    put:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1SoftwareAutoUpgradeDefaultPutRequest'
      responses:
        '204':
          description: No Content
      tags:
      - Software
  /v1/software/releases/download:
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      - name: imageExt
        in: query
        description: GNOS Image type (qcow2 or ova)
        required: true
        schema:
          type: string
          example: example string
        example: qcow2
      - name: version
        in: query
        description: GNOS Image version
        required: true
        schema:
          type: string
          example: example string
        example: 9999.202406130322
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareReleasesDownloadGetResponse'
      tags:
      - Software
  /v1/software/releases/summary:
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareReleasesSummaryGetResponse'
      tags:
      - Software
  /v1/software/running/details:
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      - name: runningVersion
        in: query
        description: ''
        required: false
        schema:
          type: string
          example: example string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRunningDetailsGetResponse'
      tags:
      - Software
  /v1/software/running/summary:
    get:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRunningSummaryGetResponse'
      tags:
      - Software
  /v1/software/rollouts/schedule:
    post:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1SoftwareRolloutsSchedulePostRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareRolloutsSchedulePostResponse'
      description: Schedule rollout to upgrade now, later or user-triggered
      tags:
      - Software
  /v1/software/gcsrelease/upload/notes:
    post:
      security:
      - jwtAuth: []
      parameters:
      - in: header
        name: Authorization
        required: true
        schema:
          type: string
        description: 'Bearer token. Format: Bearer <your_token_here>'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1SoftwareGcsreleaseUploadNotesPostRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SoftwareGcsreleaseUploadNotesPostResponse'
      tags:
      - Software
components:
  schemas:
    v1SoftwareRunningSummaryGetResponse:
      type: object
      properties:
        versions:
          type: array
          items:
            $ref: '#/components/schemas/v1SoftwareRunningSummaryGetResponseVersionSummary'
      additionalProperties: false
    v1SoftwareRunningSummaryGetResponseVersionSummary:
      type: object
      properties:
        count:
          type: integer
          format: int32
          example: 123
          minimum: 0
        name:
          type: string
          example: example string
        version:
          type: string
          example: example string
      additionalProperties: false
    v1SoftwareRolloutsSchedulePostRequest:
      type: object
      properties:
        failedOnly:
          type: boolean
          example: true
          description: When true, only devices previously marked failed are rescheduled.
        id:
          type: integer
          format: int64
          example: 42
          description: Rollout identifier to schedule. (required)
        ts:
          $ref: '#/components/schemas/googleProtobufTimestamp'
      additionalProperties: false
      required:
      - id
    upgradeRecurringSchedule:
      type: object
      properties:
        monthly:
          $ref: '#/components/schemas/upgradeMonthlyRecurrence'
        startsAtTs:
          $ref: '#/components/schemas/googleProtobufTimestamp'
        weekly:
          $ref: '#/components/schemas/upgradeWeeklyRecurrence'
        yearly:
          $ref: '#/components/schemas/upgradeYearlyRecurrence'
      additionalProperties: false
      required:
      - startsAtTs
    upgradeRolloutDevice:
      type: object
      properties:
        deviceId:
          type: integer
          format: int64
          example: 1001
          description: Device identifier. (required)
        hostname:
          type: string
          example: edge-site-01
          description: Device hostname for display.
      additionalProperties: false
    v1SoftwareRolloutsIdGetResponse:
      type: object
      properties:
        rollout:
          $ref: '#/components/schemas/upgradeRollout'
      additionalProperties: false
    upgradeRollout:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/upgradeRolloutDevice'
        hasFailed:
          type: boolean
          example: true
          description: True if any device in the rollout has a failed upgrade state.
        id:
          type: integer
          format: int64
          example: 42
          description: Server-assigned rollout identifier.
        lastRunTs:
          $ref: '#/components/schemas/googleProtobufTimestamp'
        nextRunTs:
          $ref: '#/components/schemas/googleProtobufTimestamp'
        numDevices:
          type: integer
          format: int32
          example: 3
          description: Count of devices associated with the rollout.
        rolloutConfig:
          $ref: '#/components/schemas/upgradeRolloutConfig'
        status:
          type: string
          example: idle
          description: Status of the upgrade rollout group
      additionalProperties: false
    upgradeUpgradeOccurrence:
      type: object
      properties:
        dayOfWeek:
          type: string
          example: ENUM_VALUE
        hour:
          type: integer
          format: int32
          example: 123
        minute:
          type: integer
          format: int32
          example: 123
        occurrenceInMonth:
          type: integer
          format: int32
          example: 123
        ordinal:
          type: string
          example: ENUM_VALUE
        weekday:
          type: string
          example: ENUM_VALUE
      additionalProperties: false
    upgradeRolloutConfig:
      type: object
      properties:
        action:
          type: string
          example: InstallActivate
          description: Upgrade action to perform (e.g. install+activate, install only, activate, auto-upgrade). (required)
        description:
          type: string
          example: Upgrade branch sites to release 25.4
          description: Optional longer description of the rollout.
        deviceIds:
          type: array
          items:
            type: integer
            format: int64
            example: 1001,1002,1003
            description: Device IDs included in the rollout (field name retained for API compatibility).
        name:
          type: string
          example: Q2 edge upgrade
          description: Human-readable rollout name unique within the enterprise. (required)
        release:
          type: string
          example: Recommended
          description: Target software release for devices in this rollout. (required)
        schedule:
          $ref: '#/components/schemas/upgradeRecurringSchedule'
      additionalProperties: false
      required:
      - action
      - name
      - release
    v1SoftwareRolloutsPostRequest:
      type: object
      properties:
        rolloutConfig:
          $ref: '#/components/schemas/upgradeRolloutConfig'
      additionalProperties: false
      required:
      - rolloutConfig
    v1SoftwareRunningDetailsGetResponse:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/v1SoftwareRunningDetailsGetResponseDevice'
      additionalProperties: false
    upgradeWeeklyRecurrence:
      type: object
      properties:
        interval:
          type: integer
          format: int32
          example: 2
          minimum: 0
          description: Which occurrence of the weekday in the month applies for weekly-style recurrence (1–52, aligned with schedule validation). (required)
        weekday:
          type: string
          example: Monday
          description: Day of week for the weekly recurrence. (required)
      additionalProperties: false
      required:
      - interval
      - weekday
    v1SoftwareRolloutsGetResponse:
      type: object
      properties:
        rollouts:
          type: array
          items:
            $ref: '#/components/schemas/upgradeRollout'
      additionalProperties: false
    googleProtobufTimestamp:
      type: object
      properties:
        nanos:
          type: integer
          format: int32
          example: 123
        seconds:
          type: integer
          format: int64
          example: 1234567891011
      additionalProperties: false
    upgradeInventoryKey:
      type: object
      properties:
        model:
          type: integer
          format: int32
          example: 123
          minimum: 0
        version:
          type: string
          example: example string
      additionalProperties: false
    v1SoftwareAutoUpgradeDefaultGetResponse:
      type: object
      properties:
        profile:
          $ref: '#/components/schemas/upgradeUpgradeCanaryProfile'
        release:
          type: string
          example: ENUM_VALUE
      additionalProperties: false
    upgradeUpgradeCanaryProfile:
      type: object
      properties:
        action:
          type: string
          example: ENUM_VALUE
        name:
          type: string
          example: example string
        occurrence:
          $ref: '#/components/schemas/upgradeUpgradeOccurrence'
        release:
          type: string
          example: ENUM_VALUE
      additionalProperties: false
    upgradeReleaseSummary:
      type: object
      properties:
        eosTs:
          $ref: '#/components/schemas/googleProtobufTimestamp'
        key:
          $ref: '#/components/schemas/upgradeInventoryKey'
        name:
          type: string
          example: example string
        release:
          type: string
          example: ENUM_VALUE
        releaseTs:
          $ref: '#/components/schemas/googleProtobufTimestamp'
      additionalProperties: false
    upgradeGcsReleaseCategory:
      type: object
      properties:
        content:
          type: string
          example: example string
        title:
          type: string
          example: ENUM_VALUE
      additionalProperties: false
    v1SoftwareReleasesDownloadGetResponse:
      type: object
      properties:
        imageLink:
          type: string
          example: example string
      additionalProperties: false
    v1SoftwareRolloutsPutResponse:
      type: object
      properties: {}
      additionalProperties: false
    v1SoftwareGcsreleaseUploadNotesPostRequest:
      type: object
      properties:
        details:
          $ref: '#/components/schemas/upgradeGcsReleaseDetails'
      additionalProperties: false
    v1SoftwareReleasesSummaryGetResponse:
      type: object
      properties:
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/upgradeReleaseSummary'
      additionalProperties: false
    v1SoftwareRolloutsIdDeleteResponse:
      type: object
      properties: {}
      additionalProperties: false
    upgradeGcsReleaseDetails:
      type: object
      properties:
        category:
          type: array
          items:
            $ref: '#/components/schemas/upgradeGcsReleaseCategory'
        major:
          type: boolean
          example: true
        releaseTs:
          $ref: '#/components/schemas/googleProtobufTimestamp'
      additionalProperties: false
    v1SoftwareRolloutsPutRequest:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 42
          description: Rollout identifier to update. (required)
        rolloutConfig:
          $ref: '#/components/schemas/upgradeRolloutConfig'
      additionalProperties: false
      required:
      - id
      - rolloutConfig
    v1SoftwareGcsreleaseUploadNotesPostResponse:
      type: object
      properties: {}
      additionalProperties: false
    v1SoftwareRunningDetailsGetResponseDevice:
      type: object
      properties:
        deviceId:
          type: integer
          format: int64
          example: 1234567891011
        enterpriseId:
          type: integer
          format: int64
          example: 1234567891011
        enterpriseName:
          type: string
          example: example string
        hostname:
          type: string
          example: example string
      additionalProperties: false
    v1SoftwareRolloutsPostResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 42
          description: Identifier of the created rollout. (required)
      additionalProperties: false
    v1SoftwareAutoUpgradeDefaultPutRequest:
      type: object
      properties:
        profile:
          $ref: '#/components/schemas/upgradeUpgradeCanaryProfile'
        release:
          type: string
          example: ENUM_VALUE
      additionalProperties: false
    v1SoftwareRolloutsSchedulePostResponse:
      type: object
      properties: {}
      additionalProperties: false
    upgradeMonthlyRecurrence:
      type: object
      properties:
        date:
          type: integer
          format: int32
          example: 15
          minimum: 0
          description: Calendar day of month (1–31) for fixed-date monthly recurrence; optional if ordinal and weekday are set.
        ordinal:
          type: string
          example: Second
          description: For nth-weekday-of-month style recurrence; use together with weekday, or use date instead.
        weekday:
          type: string
          example: Tuesday
          description: Weekday paired with ordinal for monthly nth-weekday recurrence; optional if date is set.
      additionalProperties: false
    upgradeYearlyRecurrence:
      type: object
      properties:
        date:
          type: integer
          format: int32
          example: 1
          minimum: 0
          description: Calendar day (1–31) for fixed month+date yearly recurrence.
        month:
          type: integer
          format: int32
          example: 3
          minimum: 0
          description: Month of year (1–12) for yearly recurrence. (required)
        ordinal:
          type: string
          example: First
          description: For nth-weekday-in-month yearly recurrence; use with weekday, or use month + date.
        weekday:
          type: string
          example: Wednesday
          description: Weekday paired with ordinal for yearly recurrence.
      additionalProperties: false
      required:
      - month
  securitySchemes:
    jwtAuth:
      type: apiKey
      in: header
      name: authorization
      description: Use `Bearer <token>`