Citra Space Ground Stations API

openapi: 3.2.0
info:
  title: SOICAT Ground Stations API
  version: 0.1.0
tags:
- name: ground_stations
paths:
  /ground-stations:
    get:
      operationId: get_ground_stations_ground_stations_get
      parameters:
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroundStationList'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Ground Stations
      tags:
      - ground_stations
    post:
      operationId: create_ground_station_ground_stations_post
      parameters:
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroundStationCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroundStation'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Ground Station
      tags:
      - ground_stations
  /ground-stations/{ground_station_id}:
    delete:
      operationId: delete_ground_station_ground_stations__ground_station_id__delete
      parameters:
      - description: The ID of the ground station to delete
        in: path
        name: ground_station_id
        required: true
        schema:
          format: uuid
          type: string
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Ground Station
      tags:
      - ground_stations
    get:
      operationId: get_ground_station_ground_stations__ground_station_id__get
      parameters:
      - description: The ID of the ground station to retrieve
        in: path
        name: ground_station_id
        required: true
        schema:
          format: uuid
          type: string
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroundStation'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Ground Station
      tags:
      - ground_stations
    put:
      operationId: update_ground_station_ground_stations__ground_station_id__put
      parameters:
      - description: The ID of the ground station to update
        in: path
        name: ground_station_id
        required: true
        schema:
          format: uuid
          type: string
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroundStationInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroundStation'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Ground Station
      tags:
      - ground_stations
  /ground-stations/{ground_station_id}/antennas:
    get:
      operationId: get_ground_station_antennas_ground_stations__ground_station_id__antennas_get
      parameters:
      - description: The ID of the ground station
        in: path
        name: ground_station_id
        required: true
        schema:
          format: uuid
          type: string
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Antenna'
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Ground Station Antennas
      tags:
      - ground_stations
  /ground-stations/{ground_station_id}/telescopes:
    get:
      operationId: get_ground_station_telescopes_ground_stations__ground_station_id__telescopes_get
      parameters:
      - description: The ID of the ground station
        in: path
        name: ground_station_id
        required: true
        schema:
          format: uuid
          type: string
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Telescope'
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Ground Station Telescopes
      tags:
      - ground_stations
  /my/ground-stations:
    get:
      operationId: get_user_ground_stations_my_ground_stations_get
      parameters:
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          format: uuid
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroundStationList'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get User Ground Stations
      tags:
      - ground_stations
components:
  schemas:
    HyperspectralConfig:
      description: "Configuration for hyperspectral instruments and spectrographs.\n\nCaptures entire spectrum simultaneously across many channels.\n\nExample:\n    {\n        \"type\": \"hyperspectral\",\n        \"min_wavelength_nm\": 400,\n        \"max_wavelength_nm\": 1000,\n        \"spectral_resolution_nm\": 2.0,\n        \"num_channels\": 300\n    }"
      properties:
        max_wavelength_nm:
          description: Maximum wavelength coverage in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
        min_wavelength_nm:
          description: Minimum wavelength coverage in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
        num_channels:
          description: Number of spectral channels (optional)
          exclusiveMinimum: 0
          format: int32
          type:
          - integer
          - 'null'
        spectral_resolution_nm:
          description: Spectral resolution (wavelength per channel) in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
        type:
          const: hyperspectral
          default: hyperspectral
          description: Configuration type discriminator
          type: string
      required:
      - min_wavelength_nm
      - max_wavelength_nm
      - spectral_resolution_nm
      type: object
    GroundStationInput:
      properties:
        altitude:
          format: double
          type:
          - number
          - 'null'
        latitude:
          format: double
          type:
          - number
          - 'null'
        launchCorridors:
          items:
            $ref: '#/components/schemas/LaunchCorridor'
          type:
          - array
          - 'null'
        launchesPossible:
          type:
          - boolean
          - 'null'
        longitude:
          format: double
          type:
          - number
          - 'null'
        name:
          maxLength: 255
          minLength: 1
          type:
          - string
          - 'null'
      type: object
    LaunchCorridor:
      properties:
        azMax:
          format: double
          maximum: 360
          minimum: 0
          type: number
        azMin:
          format: double
          maximum: 360
          minimum: 0
          type: number
        id:
          format: uuid
          type: string
        label:
          maxLength: 64
          minLength: 1
          type: string
      required:
      - label
      - azMin
      - azMax
      type: object
    TunableFilterConfig:
      description: "Configuration for tunable filters (LCTF, AOTF).\n\nCan observe any wavelength within the specified range with fixed bandwidth.\n\nExample:\n    {\n        \"type\": \"tunable\",\n        \"min_wavelength_nm\": 400,\n        \"max_wavelength_nm\": 900,\n        \"bandwidth_nm\": 10,\n        \"wavelength_step_nm\": 1.0\n    }"
      properties:
        bandwidth_nm:
          description: Fixed bandwidth at all wavelengths (FWHM) in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
        max_wavelength_nm:
          description: Maximum tunable wavelength in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
        min_wavelength_nm:
          description: Minimum tunable wavelength in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
        type:
          const: tunable
          default: tunable
          description: Configuration type discriminator
          type: string
        wavelength_step_nm:
          default: 1.0
          description: Minimum wavelength adjustment step in nanometers
          exclusiveMinimum: 0
          format: double
          type: number
      required:
      - min_wavelength_nm
      - max_wavelength_nm
      - bandwidth_nm
      type: object
    Telescope:
      properties:
        activeStatus:
          enum:
          - active
          - inactive
          readOnly: true
          type: string
        angularNoise:
          description: Angular noise in arcseconds
          format: double
          type: number
        automatedScheduling:
          default: false
          description: Whether the telescope is enabled for automated scheduling
          type: boolean
        calibrationAuditType:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/AuditType'
            description: Audit type that produced calibration_status
        calibrationEvaluatedAt:
          description: creation_epoch of the audit that produced calibration_status
          format: date-time
          type:
          - string
          - 'null'
        calibrationStatus:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/AuditStatus'
            description: Latest calibration anchor status (TREND preferred, else BASELINE)
        captureTimeSeconds:
          description: Per-exposure observation time in seconds (readout included); null = system default
          format: int32
          minimum: 1
          type:
          - integer
          - 'null'
        creationEpoch:
          format: date-time
          type: string
        edgeSensorId:
          description: Direct-to-core edge sensor assigned to this telescope
          format: uuid
          type:
          - string
          - 'null'
        fieldOfView:
          anyOf:
          - type: number
          - type: 'null'
          description: 'Computed diagonal field of view in degrees from sensor specifications.


            If all four sensor spec fields are present, this value takes precedence over

            legacy_field_of_view. Both may be stored simultaneously; legacy_field_of_view

            is only used by consumers when this computed value is None.


            Returns None if any required sensor specification is missing.'
          readOnly: true
        filterChangeTimeSeconds:
          description: Time required to change filters in seconds
          format: double
          type:
          - number
          - 'null'
        focalLength:
          description: Focal length of the optical system in millimeters
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        focalRatio:
          description: Focal ratio (f-number) of the optical system, unitless
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        groundStationId:
          description: Ground station this telescope is assigned to
          format: uuid
          type:
          - string
          - 'null'
        homeAzimuth:
          description: Home azimuth position in degrees
          format: double
          type: number
        homeElevation:
          description: Home elevation position in degrees
          format: double
          type: number
        horizontalPixelCount:
          description: Number of horizontal pixels in the sensor
          exclusiveMinimum: 0
          format: int32
          type:
          - integer
          - 'null'
        id:
          format: uuid
          type: string
        imageCircleDiameter:
          description: Diameter of the usable image circle in millimeters
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        isActive:
          description: Whether the telescope has produced an observation in the last SENSOR_ACTIVE_WINDOW_MINUTES per the latest sensor-auditor cycle
          type:
          - boolean
          - 'null'
        isOnline:
          description: Whether the telescope is online per the latest sensor-auditor cycle
          type:
          - boolean
          - 'null'
        isSimulated:
          default: false
          type: boolean
        lastConnectionEpoch:
          description: Last time the telescope connected
          format: date-time
          type:
          - string
          - 'null'
        lastObservationEpoch:
          description: Epoch of the most recent observation seen by sensor-auditor
          format: date-time
          type:
          - string
          - 'null'
        legacyFieldOfView:
          description: Original FOV in degrees (pre-sensor specs migration)
          format: double
          type:
          - number
          - 'null'
        maxMagnitude:
          description: Maximum detectable magnitude
          format: double
          type: number
        maxSlewRate:
          description: Maximum slew rate in degrees per second
          format: double
          type: number
        maxSunElevation:
          description: Highest Sun elevation over the site at which the telescope observes, in degrees (default -12, nautical darkness); null observes at any Sun elevation
          format: double
          maximum: 90
          minimum: -90
          type:
          - number
          - 'null'
        minElevation:
          description: Minimum elevation angle in degrees
          format: double
          type: number
        name:
          description: Telescope name
          maxLength: 255
          minLength: 1
          type: string
        pixelSize:
          description: Physical size of each pixel in micrometers
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        satelliteId:
          description: Satellite this telescope is assigned to
          format: uuid
          type:
          - string
          - 'null'
        spectralConfig:
          description: Spectral configuration (discrete filters, tunable, or hyperspectral)
          oneOf:
          - type: 'null'
          - additionalProperties: {}
            propertyNames:
              type: string
            type: object
          - $ref: '#/components/schemas/DiscreteFilterConfig'
          - $ref: '#/components/schemas/TunableFilterConfig'
          - $ref: '#/components/schemas/HyperspectralConfig'
        spectralMaxWavelengthNm:
          description: Maximum wavelength coverage in nanometers (computed from spectral_config)
          format: double
          type:
          - number
          - 'null'
        spectralMinWavelengthNm:
          description: Minimum wavelength coverage in nanometers (computed from spectral_config)
          format: double
          type:
          - number
          - 'null'
        status:
          enum:
          - online
          - offline
          readOnly: true
          type: string
        userGroupName:
          description: Owning user group name (set when group-owned)
          type:
          - string
          - 'null'
        userId:
          format: uuid
          type: string
        username:
          type:
          - string
          - 'null'
        verticalPixelCount:
          description: Number of vertical pixels in the sensor
          exclusiveMinimum: 0
          format: int32
          type:
          - integer
          - 'null'
      required:
      - id
      - userId
      - creationEpoch
      - name
      - angularNoise
      - maxMagnitude
      - minElevation
      - maxSlewRate
      - homeAzimuth
      - homeElevation
      - fieldOfView
      - status
      - activeStatus
      type: object
    FilterSpec:
      description: 'Specification for a single filter-wheel slot.


        A normal (bandpass) filter carries central_wavelength_nm + bandwidth_nm. A

        transmission grating (is_grating=True) disperses rather than band-passes, so

        it carries groove density + grating-to-sensor distance instead, and its

        bandpass fields are optional. Filter name is used for hardware matching by

        the daemon.


        ``dwell_seconds`` is how long this slot needs on sky. It is edge-supplied: only

        the daemon knows its own burst sizing. It is read on a grating slot only, where

        it doubles as the tasking switch, since the scheduler tasks a grating slot only

        when it declares one. On a bandpass slot it is recorded but ignored: the

        scheduler uses the telescope''s ``capture_time_seconds`` there, so a per-slot

        dwell cannot change a wheel''s reservation.'
      properties:
        bandwidth_nm:
          description: Full width at half maximum (FWHM) in nanometers (bandpass filters only)
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        central_wavelength_nm:
          description: Central wavelength in nanometers (bandpass filters only)
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        dwell_seconds:
          description: Wall-clock time this slot needs on sky, reported by the daemon. Read for a grating only, which is not tasked at all without one and is clamped to the scheduler's per-segment cap above it. Ignored on a bandpass slot, which uses the telescope's capture_time_seconds
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        grating_angle_deg:
          description: Dispersion-axis angle in degrees; None = auto-detect (gratings only)
          format: double
          type:
          - number
          - 'null'
        grating_distance_mm:
          description: Grating-to-sensor distance in mm; sets the dispersion scale (gratings only)
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        grating_lines_per_mm:
          description: Groove density in lines/mm (gratings only; e.g. SA-200 -> 200)
          exclusiveMinimum: 0
          format: double
          type:
          - number
          - 'null'
        is_grating:
          default: false
          description: True if this slot is a transmission grating (disperser)
          type: boolean
        name:
          description: Filter name as reported by hardware (e.g., 'Red', 'Ha', 'V', 'SA-200')
          type: string
      required:
      - name
      type: object
    GroundStation:
      properties:
        altitude:
          format: double
          type: number
        creationEpoch:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        latitude:
          format: double
          type: number
        launchCorridors:
          items:
            $ref: '#/components/schemas/LaunchCorridor'
          type: array
        launchesPossible:
          default: false
          type: boolean
        longitude:
          format: double
          type: number
        name:
          type: string
        updateEpoch:
          format: date-time
          type: string
        userId:
          format: uuid
          type: string
        username:
          type:
          - string
          - 'null'
      required:
      - latitude
      - longitude
      - altitude
      - id
      - userId
      - creationEpoch
      - updateEpoch
      - name
      type: object
    Antenna:
      properties:
        activeStatus:
          enum:
          - active
          - inactive
          readOnly: true
          type: string
        automatedScheduling:
          default: false
          description: Whether the antenna is enabled for automated scheduling
          type: boolean
        calibrationAuditType:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/AuditType'
            description: Audit type that produced calibration_status
        calibrationEvaluatedAt:
          description: creation_epoch of the audit that produced calibration_status
          format: date-time
          type:
          - string
          - 'null'
        calibrationStatus:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/AuditStatus'
            description: Latest calibration anchor status (TREND preferred, else BASELINE)
        captureTimeSeconds:
          description: Per-capture collection time in seconds; null = system default
          format: int64
          minimum: 1
          type:
          - integer
          - 'null'
        creationEpoch:
          format: date-time
          type: string
        edgeSensorId:
          description: Direct-to-core edge sensor assigned to this antenna
          format: uuid
          type:
          - string
          - 'null'
        groundStationId:
          description: Ground station this antenna is assigned to
          format: uuid
          type:
          - string
          - 'null'
        halfPowerBeamWidth:
          description: Half power beam width in degrees
          format: double
          type: number
        homeAzimuth:
          description: Home azimuth position in degrees
          format: double
          type: number
        homeElevation:
          description: Home elevation position in degrees
          format: double
          type: number
        id:
          format: uuid
          type: string
        isActive:
          description: Whether the antenna has produced an observation in the last SENSOR_ACTIVE_WINDOW_MINUTES per the latest sensor-auditor cycle
          type:
          - boolean
          - 'null'
        isOnline:
          description: Whether the antenna is online per the latest sensor-auditor cycle
          type:
          - boolean
          - 'null'
        isSimulated:
          default: false
          type: boolean
        lastConnectionEpoch:
          description: Last time the antenna connected
          format: date-time
          type:
          - string
          - 'null'
        lastObservationEpoch:
          description: Epoch of the most recent observation seen by sensor-auditor
          format: date-time
          type:
          - string
          - 'null'
        maxFrequency:
          description: Maximum frequency in Hz
          format: int64
          type: integer
        maxSlewRate:
          description: Maximum slew rate in degrees per second
          format: double
          type: number
        minElevation:
          description: Minimum elevation angle in degrees
          format: double
          type: number
        minFrequency:
          description: Minimum frequency in Hz
          format: int64
          type: integer
        name:
          description: Antenna name
          maxLength: 255
          minLength: 1
          type: string
        satelliteId:
          description: Satellite this antenna is assigned to
          format: uuid
          type:
          - string
          - 'null'
        status:
          enum:
          - online
          - offline
          readOnly: true
          type: string
        userGroupId:
          description: User group that owns this antenna
          format: uuid
          type:
          - string
          - 'null'
        userGroupName:
          description: Owning user group name (set when group-owned)
          type:
          - string
          - 'null'
        userId:
          format: uuid
          type: string
        username:
          type:
          - string
          - 'null'
      required:
      - id
      - userId
      - creationEpoch
      - name
      - minFrequency
      - maxFrequency
      - minElevation
      - maxSlewRate
      - homeAzimuth
      - homeElevation
      - halfPowerBeamWidth
      - status
      - activeStatus
      type: object
    AuditType:
      enum:
      - baseline
      - trend
      type: string
    AuditStatus:
      enum:
      - nominal
      - degraded
      type: string
    DiscreteFilterConfig:
      description: "Configuration for telescopes with discrete filter wheels.\n\nExample:\n    {\n        \"type\": \"discrete\",\n        \"filters\": [\n            {\"name\": \"Red\", \"central_wavelength_nm\": 630, \"bandwidth_nm\": 100},\n            {\"name\": \"Ha\", \"central_wavelength_nm\": 656.3, \"bandwidth_nm\": 7},\n            {\"name\": \"Clear\", \"central_wavelength_nm\": 550, \"bandwidth_nm\": 300}\n        ]\n    }"
      properties:
        filters:
          description: List of available filters
          items:
            $ref: '#/components/schemas/FilterSpec'
          minItems: 1
          type: array
        type:
          const: discrete
          default: discrete
          description: Configuration type discriminator
          type: string
      required:
      - filters
      type: object
    GroundStationCreate:
      properties:
        altitude:
          format: double
          type: number
        latitude:
          format: double
          type: number
        launchCorridors:
          items:
            $ref: '#/components/schemas/LaunchCorridor'
          type: array
        launchesPossible:
          default: false
          type: boolean
        longitude:
          format: double
          type: number
        name:
          maxLength: 255
          minLength: 1
          type: string
      required:
      - latitude
      - longitude
      - altitude
      - name
      type: object
    GroundStationList:
      properties:
        groundStations:
          items:
            $ref: '#/components/schemas/GroundStation'
          type: array
      required:
      - groundStations
      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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http