Citra Space Updates API

openapi: 3.2.0
info:
  title: SOICAT Updates API
  version: 0.1.0
tags:
- name: Updates
paths:
  /admin/ota/channels:
    get:
      operationId: list_ota_channels
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ChannelRollout'
                type: array
          description: By product, then channel
        '502':
          description: The update repository could not be read
        '503':
          description: No update repository is configured
      summary: List every product's update channels
      tags:
      - Updates
  /admin/ota/health:
    get:
      operationId: get_ota_health
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryHealth'
          description: When devices would stop accepting the repository
        '502':
          description: The update repository could not be read
        '503':
          description: No update repository is configured
      summary: Get the update repository's freshness
      tags:
      - Updates
  /admin/ota/products:
    get:
      operationId: list_ota_products
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: Repository ids, e.g. `citra-sense`, in order
        '502':
          description: The update repository could not be read
        '503':
          description: No update repository is configured
      summary: List the products the update repository holds
      tags:
      - Updates
  /admin/ota/releases:
    get:
      operationId: list_ota_releases
      parameters:
      - description: The product's repository id, e.g. `citra-sense`.
        in: query
        name: product
        required: true
        schema:
          type: string
      - description: At most this many, newest first (default 50, at most 500).
        in: query
        name: limit
        required: false
        schema:
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Release'
                type: array
          description: Newest published first
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '502':
          description: The update repository could not be read
        '503':
          description: No update repository is configured
      summary: List one product's releases
      tags:
      - Updates
  /sensors/devices:
    get:
      operationId: list_sensor_devices
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SensorDevice'
                type: array
          description: Every enrolled box the caller may see
      summary: List the boxes behind the caller's sensors
      tags:
      - Updates
  /sensors/{sensor_id}/device:
    get:
      operationId: get_sensor_device
      parameters:
      - in: path
        name: sensor_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensorDevice'
          description: The sensor's box
        '404':
          description: The sensor has no box, or it is not visible
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get the box behind a sensor
      tags:
      - Updates
  /sensors/{sensor_id}/device/history:
    get:
      operationId: list_sensor_device_updates
      parameters:
      - in: path
        name: sensor_id
        required: true
        schema:
          format: uuid
          type: string
      - description: At most this many, newest first (default 50, at most 500).
        in: query
        name: limit
        required: false
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeviceUpdate'
                type: array
          description: Newest first
        '404':
          description: The sensor has no box, or it is not visible
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List the switches and refusals of a sensor's box
      tags:
      - Updates
components:
  schemas:
    Build:
      description: A build of a release for one hardware class and OS.
      properties:
        deviceClass:
          type: string
        platform:
          type: string
      required:
      - deviceClass
      - platform
      type: object
    DeviceUpdate:
      description: One switch or refusal a box reported.
      properties:
        at:
          description: When Citra Core first read the report of it; up to one poll after the switch.
          format: date-time
          type: string
        outcome:
          $ref: '#/components/schemas/UpdateOutcome'
        previous:
          description: The release it replaced, or the one the box stayed on.
          type:
          - string
          - 'null'
        product:
          type: string
        release:
          type: string
      required:
      - product
      - release
      - outcome
      - at
      type: object
    UpdateState:
      description: What a box's last report about one product means for the sensor's owner.
      enum:
      - current
      - waiting
      - paused
      - held
      - rolled_back
      - refused
      - no_build
      - no_plan
      - failing
      - not_checking_in
      type: string
    Wave:
      description: One step of a staged rollout.
      properties:
        opensAt:
          format: date-time
          type: string
        share:
          description: Percent of boxes admitted from then on.
          format: double
          type: number
      required:
      - opensAt
      - share
      type: object
    RepositoryHealth:
      description: The repository's freshness, from its signed metadata.
      properties:
        expiresAt:
          description: 'The first expiry: from then on, devices refuse the repository.'
          format: date-time
          type: string
        readAt:
          description: When Citra Core last read the repository.
          format: date-time
          type: string
        roles:
          items:
            $ref: '#/components/schemas/RoleExpiry'
          type: array
        signedAt:
          description: 'When the repository was last signed: a publish or the daily re-sign.'
          format: date-time
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/HealthStatus'
        unreadablePlans:
          description: Plans left out of the channel list because they could not be read; everything else shows.
          items:
            $ref: '#/components/schemas/PlanRef'
          type: array
      required:
      - status
      - expiresAt
      - roles
      - unreadablePlans
      - readAt
      type: object
    HealthStatus:
      description: Whether devices will keep accepting the repository.
      enum:
      - ok
      - overdue
      - expiring
      - expired
      type: string
    RoleExpiry:
      description: When one role's signed metadata stops being accepted.
      properties:
        expiresAt:
          format: date-time
          type: string
        role:
          type: string
      required:
      - role
      - expiresAt
      type: object
    PlanRef:
      description: A channel plan the repository lists but Citra Core could not read or would not accept.
      properties:
        channel:
          $ref: '#/components/schemas/Channel'
        product:
          type: string
      required:
      - product
      - channel
      type: object
    Release:
      description: A release of one product, as the repository holds it.
      properties:
        builds:
          items:
            $ref: '#/components/schemas/Build'
          type: array
        commit:
          type:
          - string
          - 'null'
        namedBy:
          description: The channels whose plans name it.
          items:
            $ref: '#/components/schemas/Channel'
          type: array
        product:
          type: string
        publishedAt:
          description: When its first build reached the repository.
          format: date-time
          type:
          - string
          - 'null'
        version:
          type: string
      required:
      - product
      - version
      - builds
      - namedBy
      type: object
    StateCount:
      description: How many boxes on a channel are in one state.
      properties:
        sensors:
          format: int64
          type: integer
        state:
          $ref: '#/components/schemas/UpdateState'
      required:
      - state
      - sensors
      type: object
    UpdateOutcome:
      description: A switch or refusal in a box's history.
      enum:
      - installed
      - rolled_back
      - refused
      type: string
    SensorDevice:
      description: The CitraSense box behind a telescope or antenna.
      properties:
        agentVersion:
          description: The citra-ota agent's own version.
          type:
          - string
          - 'null'
        checkedInAt:
          description: Its last report to the update repository, for any product.
          format: date-time
          type:
          - string
          - 'null'
        deviceClass:
          description: The hardware and OS it reports, e.g. `jetson-orin` and `l4t-r39.2`.
          type:
          - string
          - 'null'
        edgeSensorId:
          format: uuid
          type: string
        enrolledAt:
          format: date-time
          type:
          - string
          - 'null'
        hardware:
          description: The hardware class it was provisioned as.
          type: string
        hostname:
          description: What the box called itself when it enrolled; CitraSense sends its hostname.
          type:
          - string
          - 'null'
        lastSeenAt:
          description: Its last connection to the edge broker.
          format: date-time
          type:
          - string
          - 'null'
        name:
          type: string
        platform:
          type:
          - string
          - 'null'
        products:
          description: One per product the box runs, by product id.
          items:
            $ref: '#/components/schemas/DeviceProduct'
          type: array
      required:
      - edgeSensorId
      - name
      - hardware
      - products
      type: object
    ChannelRollout:
      description: 'One product''s channel: what its signed plan names, and how far the rollout has got.'
      properties:
        admitted:
          description: Percent of boxes the rollout admits now.
          format: double
          type: number
        channel:
          $ref: '#/components/schemas/Channel'
        commit:
          description: The commit a CI-built release came from, from its metadata or an older label's `-g<sha>`.
          type:
          - string
          - 'null'
        nextWaveAt:
          format: date-time
          type:
          - string
          - 'null'
        paused:
          type: boolean
        product:
          type: string
        release:
          description: The release the plan names; null for a channel boxes follow with nothing published.
          type:
          - string
          - 'null'
        sensors:
          description: Boxes reporting this product on this channel, by state; states with none are left out.
          items:
            $ref: '#/components/schemas/StateCount'
          type: array
        waves:
          items:
            $ref: '#/components/schemas/Wave'
          type: array
      required:
      - product
      - channel
      - paused
      - waves
      - admitted
      - sensors
      type: object
    ValidationError:
      properties:
        ctx:
          type: object
        input: {}
        loc:
          items:
            oneOf:
            - type: string
            - format: int64
              type: integer
          type: array
        msg:
          type: string
        type:
          type: string
      required:
      - loc
      - msg
      - type
      type: object
    DeviceProduct:
      description: 'What a box last reported about one product. Self-reported: shown, never acted on.'
      properties:
        channel:
          $ref: '#/components/schemas/Channel'
        code:
          description: The agent's own code for its last poll, e.g. `repository-error`.
          type: string
        product:
          description: The product's repository id, e.g. `citra-sense`.
          type: string
        reportedAt:
          format: date-time
          type: string
        running:
          description: The release the box runs; null before its first install.
          type:
          - string
          - 'null'
        state:
          $ref: '#/components/schemas/UpdateState'
        target:
          description: The release the state is about, when it is not the running one.
          type:
          - string
          - 'null'
      required:
      - product
      - channel
      - state
      - code
      - reportedAt
      type: object
    Channel:
      description: A release train a box follows for one product.
      enum:
      - dev
      - beta
      - stable
      type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http