Citra Space Elsets API

openapi: 3.2.0
info:
  title: SOICAT Elsets API
  version: 0.1.0
tags:
- name: elsets
paths:
  /elsets/counts:
    get:
      operationId: get_elset_counts_elsets_counts_get
      parameters:
      - in: query
        name: days
        required: false
        schema:
          default: 3
          exclusiveMinimum: 0
          title: Days
          type: integer
      - in: query
        name: show_future
        required: false
        schema:
          default: false
          title: Show Future
          type: boolean
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElsetCounts'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Elset Counts
      tags:
      - elsets
  /elsets/latest:
    get:
      operationId: get_elsets_elsets_latest_get
      parameters:
      - in: query
        name: days
        required: false
        schema:
          default: 14
          title: Days
          type: integer
      - description: Filter to specific elset types. Omit for server-default ranking.
        in: query
        name: types
        required: false
        schema:
          anyOf:
          - items:
              $ref: '#/components/schemas/CitraElsetType'
            type: array
          - type: 'null'
          description: Filter to specific elset types. Omit for server-default ranking.
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElsetList'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Elsets
      tags:
      - elsets
  /elsets/leo-scatter:
    get:
      operationId: get_leo_scatter_data_elsets_leo_scatter_get
      parameters:
      - in: query
        name: days
        required: false
        schema:
          default: 14
          exclusiveMinimum: 0
          title: Days
          type: integer
      - in: query
        name: min_sma
        required: false
        schema:
          default: 6500.0
          exclusiveMinimum: 0
          title: Min Sma
          type: number
      - in: query
        name: max_sma
        required: false
        schema:
          default: 8000.0
          exclusiveMinimum: 0
          title: Max Sma
          type: number
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeoElsetScatterData'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Leo Scatter Data
      tags:
      - elsets
  /elsets/near-geo-scatter:
    get:
      operationId: get_near_geo_scatter_data_elsets_near_geo_scatter_get
      parameters:
      - in: query
        name: days
        required: false
        schema:
          default: 14
          exclusiveMinimum: 0
          title: Days
          type: integer
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NearGeoElsetScatterData'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Near Geo Scatter Data
      tags:
      - elsets
  /elsets/{elset_id}/reject:
    patch:
      description: 'Soft-delete an elset by setting its review status to rejected.


        This marks the elset as rejected and creates a review history entry

        to track the change.'
      operationId: reject_elset_elsets__elset_id__reject_patch
      parameters:
      - description: The ID of the elset to reject
        in: path
        name: elset_id
        required: true
        schema:
          description: The ID of the elset to reject
          format: uuid
          title: Elset Id
          type: string
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Reject Elset
      tags:
      - elsets
  /elsets/{elset_id}/state-bundle:
    get:
      description: 'Return a stored elset as a multi-representation state bundle (JSON) or a 3LE text file.


        Wraps `keplime.Satellite.to_advanced_state_bundle()`, returning the elset''s

        osculating Cartesian state, osculating Keplerian elements, and two mean-element

        TLEs (Kozai-GP and Brouwer-XP) — each as canonical 2-line strings for tool

        interop. Pure conversion (no propagation); the bundle''s epoch is the elset''s

        native epoch.


        With `format=MEAN_KOZAI_3LE`, returns `text/plain`: the Space-Track `0 ` line

        followed by the Kozai-GP TLE''s two lines. `norad_cat_id` comes from the catalog and is

        Alpha-5 encoded into the TLE lines by keplime (>= 2.1.0).'
      operationId: get_elset_state_bundle_elsets__elset_id__state_bundle_get
      parameters:
      - description: UUID of the elset to convert to a multi-representation state bundle.
        in: path
        name: elset_id
        required: true
        schema:
          description: UUID of the elset to convert to a multi-representation state bundle.
          format: uuid
          title: Elset Id
          type: string
      - description: Output format. JSON returns the full state bundle; MEAN_KOZAI_3LE returns a 3LE text file.
        in: query
        name: format
        required: false
        schema:
          default: JSON
          description: Output format. JSON returns the full state bundle; MEAN_KOZAI_3LE returns a 3LE text file.
          oneOf:
          - $ref: '#/components/schemas/DownloadFormat'
      - in: header
        name: X-Scenario-Context
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedStateBundleResponse'
            text/plain: {}
          description: State bundle (JSON) or, with format=MEAN_KOZAI_3LE, a 3LE text file.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Elset State Bundle
      tags:
      - elsets
components:
  schemas:
    LeoElsetScatterData:
      items:
        $ref: '#/components/schemas/LeoElsetPoint'
      title: LeoElsetScatterData
      type: array
    NearGeoElsetScatterData:
      items:
        $ref: '#/components/schemas/NearGeoElsetPoint'
      title: NearGeoElsetScatterData
      type: array
    CartesianStateOut:
      properties:
        positionKm:
          $ref: '#/components/schemas/CartesianVectorOut'
        velocityKmS:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/CartesianVectorOut'
      required:
      - positionKm
      - velocityKmS
      type: object
    KeplerianElementsOut:
      properties:
        argumentOfPeriapsisDeg:
          format: double
          type: number
        eccentricity:
          format: double
          type: number
        inclinationDeg:
          format: double
          type: number
        meanAnomalyDeg:
          format: double
          type: number
        raanDeg:
          description: Right ascension of the ascending node, degrees [0, 360).
          format: double
          type: number
        semiMajorAxisKm:
          format: double
          type: number
      required:
      - semiMajorAxisKm
      - eccentricity
      - inclinationDeg
      - raanDeg
      - argumentOfPeriapsisDeg
      - meanAnomalyDeg
      type: object
    ElsetCounts:
      items:
        $ref: '#/components/schemas/ElsetCountBin'
      title: ElsetCounts
      type: array
    Elset-Output:
      properties:
        argumentOfPerigee:
          title: Argumentofperigee
          type: number
        bStar:
          default: 0.0
          title: Bstar
          type: number
        ballisticCoefficient:
          default: 0.0
          title: Ballisticcoefficient
          type: number
        creationEpoch:
          title: Creationepoch
          type: string
        eccentricity:
          title: Eccentricity
          type: number
        epoch:
          title: Epoch
          type: string
        id:
          title: Id
          type: string
        inUdl:
          default: false
          title: Inudl
          type: boolean
        inclination:
          title: Inclination
          type: number
        meanAnomaly:
          title: Meananomaly
          type: number
        meanMotion:
          description: "Calculate mean motion from semi-major axis.\n\nUses keplime's mean_motion_from_semi_major_axis() to convert semi-major axis to mean motion.\n\nReturns:\n    Mean motion in revolutions per day"
          readOnly: true
          title: Meanmotion
          type: number
        meanMotionDot:
          default: 0.0
          title: Meanmotiondot
          type: number
        meanMotionDotDot:
          default: 0.0
          title: Meanmotiondotdot
          type: number
        migrationId:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
        raan:
          title: Raan
          type: number
        reviewStatus:
          default: approved
          oneOf:
          - $ref: '#/components/schemas/ReviewStatus'
        rms:
          anyOf:
          - type: number
          - type: 'null'
        satelliteId:
          format: uuid
          title: Satelliteid
          type: string
        satelliteName:
          anyOf:
          - type: string
          - type: 'null'
        satelliteReviewStatus:
          anyOf:
          - $ref: '#/components/schemas/ReviewStatus'
          - type: 'null'
        scenarioId:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
        semiMajorAxis:
          title: Semimajoraxis
          type: number
        srpCoefficient:
          default: 0.0
          title: Srpcoefficient
          type: number
        tle:
          anyOf:
          - items: false
            maxItems: 2
            minItems: 2
            prefixItems:
            - type: string
            - type: string
            type: array
          - type: 'null'
        type:
          $ref: '#/components/schemas/CitraElsetType'
        userGroupId:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
        userGroupName:
          anyOf:
          - type: string
          - type: 'null'
        userId:
          format: uuid
          title: Userid
          type: string
        userTier:
          $ref: '#/components/schemas/UserTier'
        username:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - id
      - userId
      - userGroupId
      - satelliteId
      - userTier
      - creationEpoch
      - epoch
      - type
      - semiMajorAxis
      - inclination
      - raan
      - eccentricity
      - argumentOfPerigee
      - meanAnomaly
      - tle
      - meanMotion
      title: Elset
      type: object
    OsculatingKeplerianOut:
      properties:
        elements:
          $ref: '#/components/schemas/KeplerianElementsOut'
      required:
      - elements
      type: object
    AdvancedStateBundleResponse:
      properties:
        cartesianState:
          $ref: '#/components/schemas/CartesianStateOut'
        dragCoefficient:
          description: Drag coefficient from the source satellite.
          format: double
          type: number
        epoch:
          type: string
        meanBrouwerXp:
          $ref: '#/components/schemas/TleOut'
        meanKozaiGp:
          $ref: '#/components/schemas/TleOut'
        noradCatId:
          format: int32
          type:
          - integer
          - 'null'
        osculatingKeplerian:
          $ref: '#/components/schemas/OsculatingKeplerianOut'
        referenceFrame:
          description: Frame of cartesian_state and osculating_keplerian (mean TLEs are TEME).
          type: string
        satelliteName:
          type: string
        srpCoefficient:
          description: SRP coefficient from the source satellite.
          format: double
          type: number
      required:
      - satelliteName
      - noradCatId
      - epoch
      - referenceFrame
      - meanKozaiGp
      - meanBrouwerXp
      - cartesianState
      - osculatingKeplerian
      - dragCoefficient
      - srpCoefficient
      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
    UserTier:
      enum:
      - Standard
      - Plus
      - Premium
      - Enterprise
      - Government
      - Admin
      type: string
    DownloadFormat:
      description: 'Output format the elset state-bundle download endpoint can produce.


        Owned by the elset/download domain (the state-bundle endpoint is also used by callers

        with no effector concept). Shares string values with `EffectorTargetFormat` so the

        effector -> download mapping is an identity today, while letting the two diverge later.'
      enum:
      - JSON
      - MEAN_KOZAI_3LE
      title: DownloadFormat
      type: string
    ElsetList:
      items:
        $ref: '#/components/schemas/Elset-Output'
      title: ElsetList
      type: array
    CitraElsetType:
      enum:
      - SGP4 with Kozai mean motion
      - SGP4 with Brouwer mean motion
      - SGP4-XP with Brouwer mean motion
      - SP with Brouwer mean motion
      type: string
    NearGeoElsetPoint:
      properties:
        eccentricity:
          title: Eccentricity
          type: number
        epoch:
          title: Epoch
          type: string
        inclination:
          title: Inclination
          type: number
        launchYear:
          anyOf:
          - type: integer
          - type: 'null'
        noradCatId:
          title: Noradcatid
          type: integer
        raan:
          title: Raan
          type: number
        satelliteId:
          title: Satelliteid
          type: string
        satelliteName:
          title: Satellitename
          type: string
        semiMajorAxis:
          title: Semimajoraxis
          type: number
      required:
      - satelliteId
      - satelliteName
      - noradCatId
      - raan
      - inclination
      - semiMajorAxis
      - eccentricity
      - epoch
      - launchYear
      title: NearGeoElsetPoint
      type: object
    ReviewStatus:
      enum:
      - needs_review
      - in_review
      - approved
      - rejected
      - migrated
      - blocked
      title: ReviewStatus
      type: string
    ElsetCountBin:
      properties:
        count:
          title: Count
          type: integer
        hour:
          title: Hour
          type: string
      required:
      - hour
      - count
      title: ElsetCountBin
      type: object
    CartesianVectorOut:
      properties:
        x:
          format: double
          type: number
        y:
          format: double
          type: number
        z:
          format: double
          type: number
      required:
      - x
      - y
      - z
      type: object
    TleOut:
      properties:
        line1:
          type: string
        line2:
          type: string
      required:
      - line1
      - line2
      type: object
    LeoElsetPoint:
      properties:
        altitude:
          title: Altitude
          type: number
        eccentricity:
          title: Eccentricity
          type: number
        epoch:
          title: Epoch
          type: string
        inclination:
          title: Inclination
          type: number
        noradCatId:
          title: Noradcatid
          type: integer
        raan:
          title: Raan
          type: number
        satelliteId:
          title: Satelliteid
          type: string
        satelliteName:
          title: Satellitename
          type: string
        semiMajorAxis:
          title: Semimajoraxis
          type: number
      required:
      - satelliteId
      - satelliteName
      - noradCatId
      - semiMajorAxis
      - altitude
      - inclination
      - raan
      - eccentricity
      - epoch
      title: LeoElsetPoint
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http