openapi: 3.2.0
info:
  title: Tasking Feasibility API
  description: Canopy API for Self-Service Tasking
  version: 3.13.0
servers:
- url: https://api.canopy.umbra.space/tasking
  description: Live Environment
- url: https://api.canopy.prod.umbra-sandbox.space/tasking
  description: Sandbox Environment
security:
- bearerAuth: []
tags:
- name: Feasibility
paths:
  /feasibilities:
    post:
      tags:
      - Feasibility
      summary: Create Feasibility
      description: Creates a feasibility request for the given constraints. Feasibilities begin with status RECEIVED, and should transition to COMPLETED or ERROR within a few minutes. Poll feasibility by id until status is COMPLETED, upon which opportunities will also be returned.
      operationId: create_feasibility
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeasibilityRequest-Input'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feasibility'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /feasibilities/{id}:
    get:
      tags:
      - Feasibility
      summary: Get Feasibility
      description: Returns feasibility by id. When status is COMPLETED, the opportunities array will be populated with opportunities.
      operationId: get_feasibility
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feasibility'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Point:
      properties:
        bbox:
          anyOf:
          - prefixItems:
            - type: number
            - type: number
            - type: number
            - type: number
            type: array
            maxItems: 4
            minItems: 4
          - prefixItems:
            - type: number
            - type: number
            - type: number
            - type: number
            - type: number
            - type: number
            type: array
            maxItems: 6
            minItems: 6
          - type: 'null'
          title: Bbox
        type:
          type: string
          title: Type
          default: Point
        coordinates:
          anyOf:
          - $ref: '#/components/schemas/Position2D'
          - $ref: '#/components/schemas/Position3D'
          title: Coordinates
      type: object
      required:
      - type
      - coordinates
      title: Point
      description: Point Model
    FeasibilityStatus:
      type: string
      enum:
      - RECEIVED
      - COMPLETED
      - ERROR
      title: FeasibilityStatus
      description: Feasibility Status
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ScanConstraints:
      properties:
        imagingMode:
          type: string
          title: Imagingmode
          description: 'The imaging mode for the task. Supported imaging modes include: SPOTLIGHT, SCAN.'
          default: SCAN
        geometry:
          $ref: '#/components/schemas/LineString'
          description: Starting and ending points for a scan geometry. The first coordinate is the starting point and the second coordinate is the ending point. There must be exactly two coordinates in the geometry.
        polarization:
          $ref: '#/components/schemas/PolarizationEnum'
          description: The first letter indicates the orientation of the wave as it is transmitted. The second letter indicates how the wave is filtered when received.
          default: VV
        rangeResolutionMinMeters:
          type: number
          title: Rangeresolutionminmeters
          description: ' Valid range resolutions include: 0.5, 1.0, 2.0. Please query the organization settings endpoint for allowed range resolution values for your organization'
          default: 2
        grazingAngleMinDegrees:
          type: integer
          maximum: 79
          minimum: 0
          title: Grazinganglemindegrees
          description: The minimum angle between the local tangent plane at the target location and the line of sight vector between the satellite and the target.
          default: 32
        grazingAngleMaxDegrees:
          type: integer
          maximum: 80
          minimum: 1
          title: Grazinganglemaxdegrees
          description: The maximum angle between the local tangent plane at the target location and the line of sight vector between the satellite and the target.
          default: 60
        swathWidthMeters:
          type: integer
          maximum: 10000
          minimum: 1000
          title: Swathwidthmeters
          description: The swath width of the scan in meters.
          default: 8000
      type: object
      required:
      - geometry
      title: ScanConstraints
    FeasibilityRequest-Output:
      properties:
        constraints:
          oneOf:
          - $ref: '#/components/schemas/ScanConstraints'
          - $ref: '#/components/schemas/SpotlightConstraints'
          title: Constraints
          discriminator:
            propertyName: imagingMode
            mapping:
              SCAN: '#/components/schemas/ScanConstraints'
              SPOTLIGHT: '#/components/schemas/SpotlightConstraints'
        windowStartAt:
          type: string
          format: date-time
          title: Windowstartat
        windowEndAt:
          type: string
          format: date-time
          title: Windowendat
        contractId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Contractid
          description: Explicit contract chosen for feasibility; if omitted default contract is used
        imagingMode:
          $ref: '#/components/schemas/ImagingMode'
          description: The 'imagingMode' property is deprecated. Use 'constraints.imagingMode' instead.
          deprecated: true
          readOnly: true
        spotlightConstraints:
          anyOf:
          - $ref: '#/components/schemas/SpotlightConstraints'
          - type: 'null'
          description: The 'spotlightConstraints' property is deprecated. Use 'constraints' instead.
          deprecated: true
          readOnly: true
        scanConstraints:
          anyOf:
          - $ref: '#/components/schemas/ScanConstraints'
          - type: 'null'
          description: The 'scanConstraints' property is deprecated. Use 'constraints' instead.
          deprecated: true
          readOnly: true
      type: object
      required:
      - constraints
      - windowStartAt
      - windowEndAt
      - imagingMode
      - spotlightConstraints
      - scanConstraints
      title: FeasibilityRequest
      deprecationWarning: Having additional properties is deprecated and will be forbidden in the future.
    FeasibilityRequest-Input:
      properties:
        constraints:
          oneOf:
          - $ref: '#/components/schemas/ScanConstraints'
          - $ref: '#/components/schemas/SpotlightConstraints'
          title: Constraints
          discriminator:
            propertyName: imagingMode
            mapping:
              SCAN: '#/components/schemas/ScanConstraints'
              SPOTLIGHT: '#/components/schemas/SpotlightConstraints'
        windowStartAt:
          type: string
          format: date-time
          title: Windowstartat
        windowEndAt:
          type: string
          format: date-time
          title: Windowendat
        contractId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Contractid
          description: Explicit contract chosen for feasibility; if omitted default contract is used
        imagingMode:
          anyOf:
          - $ref: '#/components/schemas/ImagingMode'
          - type: 'null'
          description: The 'imagingMode' property is deprecated. It is now derived from the 'constraints' property.
          deprecated: true
        scanConstraints:
          anyOf:
          - $ref: '#/components/schemas/ScanConstraints'
          - type: 'null'
          description: The 'scanConstraints' property is deprecated. Use 'constraints' instead.
          deprecated: true
        spotlightConstraints:
          anyOf:
          - $ref: '#/components/schemas/SpotlightConstraints'
          - type: 'null'
          description: The 'spotlightConstraints' property is deprecated. Use 'constraints' instead.
          deprecated: true
      type: object
      required:
      - constraints
      - windowStartAt
      - windowEndAt
      title: FeasibilityRequest
      deprecationWarning: Having additional properties is deprecated and will be forbidden in the future.
    Feasibility:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        opportunities:
          anyOf:
          - items:
              $ref: '#/components/schemas/Opportunity'
            type: array
          - type: 'null'
          title: Opportunities
        feasibilityRequest:
          anyOf:
          - $ref: '#/components/schemas/FeasibilityRequest-Output'
          - type: 'null'
        organizationId:
          type: string
          title: Organizationid
        status:
          $ref: '#/components/schemas/FeasibilityStatus'
          default: RECEIVED
        userId:
          type: string
          title: Userid
      type: object
      required:
      - organizationId
      - userId
      title: Feasibility
      description: 'An async operation that checks the active schedule and returns Opportunities


        Feasibility begins in the RECEIVED state and transitions to COMPLETE if the Umbra

        scheduler is able to generate Opportunities for the given FeasibilityRequest,

        otherwise the Feasibility is transitioned to ERROR.'
    Position2D:
      prefixItems:
      - type: number
        title: Longitude
      - type: number
        title: Latitude
      type: array
      maxItems: 2
      minItems: 2
    LineString:
      properties:
        bbox:
          anyOf:
          - prefixItems:
            - type: number
            - type: number
            - type: number
            - type: number
            type: array
            maxItems: 4
            minItems: 4
          - prefixItems:
            - type: number
            - type: number
            - type: number
            - type: number
            - type: number
            - type: number
            type: array
            maxItems: 6
            minItems: 6
          - type: 'null'
          title: Bbox
        type:
          type: string
          title: Type
          default: LineString
        coordinates:
          items:
            anyOf:
            - $ref: '#/components/schemas/Position2D'
            - $ref: '#/components/schemas/Position3D'
          type: array
          minItems: 2
          title: Coordinates
      type: object
      required:
      - type
      - coordinates
      title: LineString
      description: LineString Model
    PolarizationEnum:
      type: string
      enum:
      - VV
      - HH
      title: Polarization
      description: The first letter indicates the orientation of the wave as it is transmitted. The second letter indicates how the wave is filtered when received.
    ImagingMode:
      type: string
      enum:
      - SPOTLIGHT
      - SCAN
      title: ImagingMode
      description: The Imaging Mode for the Task
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Position3D:
      prefixItems:
      - type: number
        title: Longitude
      - type: number
        title: Latitude
      - type: number
        title: Altitude
      type: array
      maxItems: 3
      minItems: 3
    Opportunity:
      properties:
        windowStartAt:
          type: string
          format: date-time
          title: Windowstartat
          description: The start time in UTC of this Opportunity
        windowEndAt:
          type: string
          format: date-time
          title: Windowendat
          description: The end time in UTC of this Opportunity
        durationSec:
          type: number
          title: Durationsec
          description: The duration (in seconds) of this Opportunity
        grazingAngleStartDegrees:
          type: number
          title: Grazinganglestartdegrees
          description: The starting grazing angle in degrees
        grazingAngleEndDegrees:
          type: number
          title: Grazingangleenddegrees
          description: The ending grazing angle in degrees
        targetAzimuthAngleStartDegrees:
          type: number
          title: Targetazimuthanglestartdegrees
          description: The start angle measured clockwise from north as measured at the target location.
        targetAzimuthAngleEndDegrees:
          type: number
          title: Targetazimuthangleenddegrees
          description: The end angle measured clockwise from north as measured at the target location.
        squintAngleStartDegrees:
          anyOf:
          - type: number
          - type: 'null'
          title: Squintanglestartdegrees
          description: The starting squint angle in degrees. This is a legacy field that uses "Umbra Squint" (or right broadside squint).
          deprecated: true
        squintAngleEndDegrees:
          anyOf:
          - type: number
          - type: 'null'
          title: Squintangleenddegrees
          description: The ending squint angle in degrees. This is a legacy field that uses "Umbra Squint" (or right broadside squint).
          deprecated: true
        squintAngleEngineeringDegreesStart:
          type: number
          title: Squintangleengineeringdegreesstart
          description: 'Starting squint angle. "Squinted" refers to how far away from broadside the angle is. Since exactly broadside is either 90 or -90 degrees, the proximity of the angle to 0 degrees suggests the satellite is further “squinted” forward for collection. In contrast, closeness to 180 or -180 degrees indicates being further “squinted” backward.  Approximate until the collect is PROCESSED. Learn more at: https://docs.canopy.umbra.space/docs/squint'
        squintAngleEngineeringDegreesEnd:
          type: number
          title: Squintangleengineeringdegreesend
          description: 'Ending squint angle. "Squinted" refers to how far away from broadside the angle is. Since exactly broadside is either 90 or -90 degrees, the proximity of the angle to 0 degrees suggests the satellite is further “squinted” forward for collection. In contrast, closeness to 180 or -180 degrees indicates being further “squinted” backward.  Approximate until the collect is PROCESSED. Learn more at: https://docs.canopy.umbra.space/docs/squint'
        slantRangeStartKm:
          type: number
          title: Slantrangestartkm
          description: The starting slant range in kilometers
        slantRangeEndKm:
          type: number
          title: Slantrangeendkm
          description: The ending slant range in kilometers
        groundRangeStartKm:
          type: number
          title: Groundrangestartkm
          description: The starting ground range in kilometers
        groundRangeEndKm:
          type: number
          title: Groundrangeendkm
          description: The ending ground range in kilometers
        satelliteId:
          type: string
          title: Satelliteid
          description: The ID for the Umbra satellite that will perform the Collect for this Opportunity.
          default: ''
      type: object
      required:
      - windowStartAt
      - windowEndAt
      - durationSec
      - grazingAngleStartDegrees
      - grazingAngleEndDegrees
      - targetAzimuthAngleStartDegrees
      - targetAzimuthAngleEndDegrees
      - squintAngleEngineeringDegreesStart
      - squintAngleEngineeringDegreesEnd
      - slantRangeStartKm
      - slantRangeEndKm
      - groundRangeStartKm
      - groundRangeEndKm
      title: Opportunity
      description: 'An open window on the active schedule that satisfies the given Feasibility constraints


        For more information about the geometry fields, see:

        https://docs.canopy.umbra.space/docs/tasking-geometries'
    SceneSize:
      type: string
      enum:
      - 4x4_KM
      - 5x5_KM
      - 10x10_KM
      - NATURAL_FOOTPRINT
      title: SceneSize
      description: The requested Spotlight Scene Size in kilometers.
    SpotlightConstraints:
      properties:
        imagingMode:
          type: string
          title: Imagingmode
          description: 'The imaging mode for the task. Supported imaging modes include: SPOTLIGHT, SCAN.'
          default: SPOTLIGHT
        geometry:
          $ref: '#/components/schemas/Point'
          description: The centroid of the area as a GeoJSON Point. The third altitude coordinate may be specified (in meters) and will be calculated automatically if not provided.
        polarization:
          $ref: '#/components/schemas/PolarizationEnum'
          description: The first letter indicates the orientation of the wave as it is transmitted. The second letter indicates how the wave is filtered when received.
          default: VV
        rangeResolutionMinMeters:
          type: number
          title: Rangeresolutionminmeters
          description: 'The ground plane resolution of the range component, perpendicular to the direction of travel for the image. When combined with multilook_factor, this determines the image''s ground plane azimuth resolution. Valid range resolution values include: 0.25, 0.35, 0.5, 1.0, 2.0. Please query the organization settings endpoint for allowed range resolution values for your organization'
          default: 1
        multilookFactor:
          type: integer
          title: Multilookfactor
          description: 'The factor by which dwell time is increased in relation to the ground plane range resolution, indicating a multi-looked image. When combined with range_resolution_min_meters, this determines the image''s ground plane azimuth resolution. Valid multilook factor values include: 1, 2, 4, 8.'
          default: 1
        grazingAngleMinDegrees:
          type: integer
          maximum: 89
          minimum: 0
          title: Grazinganglemindegrees
          description: The minimum angle between the local tangent plane at the target location and the line of sight vector between the satellite and the target.
          default: 45
        grazingAngleMaxDegrees:
          type: integer
          maximum: 90
          minimum: 1
          title: Grazinganglemaxdegrees
          description: The maximum angle between the local tangent plane at the target location and the line of sight vector between the satellite and the target.
          default: 65
        targetAzimuthAngleStartDegrees:
          type: integer
          maximum: 360
          minimum: 0
          title: Targetazimuthanglestartdegrees
          description: The start angle measured clockwise from north as measured at the target location. This value may be greater than targetAzimuthAngleEndDegrees in order to image clockwise from west of north to east of north.
          default: 1
        targetAzimuthAngleEndDegrees:
          type: integer
          maximum: 360
          minimum: 0
          title: Targetazimuthangleenddegrees
          description: The end angle measured clockwise from north as measured at the target location. This value may be less than targetAzimuthAngleStartDegrees in order to image clockwise from west of north to east of north.
          default: 360
        sceneSize:
          $ref: '#/components/schemas/SceneSize'
          description: 'The Spotlight image scene size in kilometers. The first number is the azimuth dimension and the second is the range dimension. Valid scene size values include: 4x4_KM, 5x5_KM, 10x10_KM, NATURAL_FOOTPRINT. Please query the organization settings endpoint for allowed scene size and range resolution values for your organization.'
          default: 5x5_KM
      type: object
      required:
      - geometry
      title: SpotlightConstraints
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT