3GPP Retrieve (custom operation without associated resources) API

openapi: 3.2.0
info:
  title: 3gpp-uav-fa Retrieve (custom operation without associated resources) API
  version: 1.0.0
  description: "API for UAV Flight Assistance.  \n© 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  \nAll rights reserved.\n"
servers:
- url: '{apiRoot}/3gpp-uav-fa/v1'
  variables:
    apiRoot:
      default: https://example.com
      description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.
security:
- {}
- oAuth2ClientCredentials: []
tags:
- name: Retrieve (custom operation without associated resources)
paths:
  /{afId}/retrieve:
    parameters:
    - name: afId
      in: path
      description: Represents the identifier of the AF.
      required: true
      schema:
        type: string
    post:
      summary: Request to retrieve UAV flight information.
      operationId: RetrieveUAVFlightInfo
      tags:
      - Retrieve (custom operation without associated resources)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UAVFlightInfoReq'
      responses:
        '200':
          description: 'OK. The UAV Flight information retrieval request is successfully processed, and the the requested UAV Flight information is returned in the response body.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UAVFlightInfoResp'
        '307':
          $ref: TS29122_CommonData.yaml#/components/responses/307
        '308':
          $ref: TS29122_CommonData.yaml#/components/responses/308
        '400':
          $ref: TS29122_CommonData.yaml#/components/responses/400
        '401':
          $ref: TS29122_CommonData.yaml#/components/responses/401
        '403':
          $ref: TS29122_CommonData.yaml#/components/responses/403
        '404':
          $ref: TS29122_CommonData.yaml#/components/responses/404
        '411':
          $ref: TS29122_CommonData.yaml#/components/responses/411
        '413':
          $ref: TS29122_CommonData.yaml#/components/responses/413
        '415':
          $ref: TS29122_CommonData.yaml#/components/responses/415
        '429':
          $ref: TS29122_CommonData.yaml#/components/responses/429
        '500':
          $ref: TS29122_CommonData.yaml#/components/responses/500
        '503':
          $ref: TS29122_CommonData.yaml#/components/responses/503
        default:
          $ref: TS29122_CommonData.yaml#/components/responses/default
components:
  schemas:
    CandidateFlightPathInfo:
      description: Represents the candidate flight path information.
      type: object
      properties:
        borderCrssPnt:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
        accptDeviatDist:
          $ref: TS29571_CommonData.yaml#/components/schemas/Uinteger
        accptDeviatTime:
          $ref: TS29122_CommonData.yaml#/components/schemas/DurationSec
        canFlightPath:
          $ref: '#/components/schemas/FlightPath'
    UAVFlightInfoResp:
      description: Represents the UAV Flight information retrieval response.
      type: object
      properties:
        retrievedResults:
          type: array
          items:
            $ref: '#/components/schemas/UAVFlightAssistNotif'
          minItems: 1
        suppFeat:
          $ref: TS29571_CommonData.yaml#/components/schemas/SupportedFeatures
      required:
      - retrievedResults
    RetrievePurpose:
      anyOf:
      - type: string
        enum:
        - USS_CHANGEOVER
        - PRE_FLIGHT_PLANNING
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration and is not used to encode content defined in the present version of this API.

          '
      description: "Represents the purpose of the retrieved UAV flight information.  \nPossible values are:\n  - USS_CHANGEOVER: Indicates that the purpose of the UAV Flight information retrieval is\n    USS changeover.\n  - PRE_FLIGHT_PLANNING: Indicates that the purpose of the UAV Flight information retrieval\n    is pre-flight planning.\n"
    FlightPath:
      description: Represents a flight path.
      type: object
      properties:
        pathSegInfo:
          type: array
          items:
            $ref: '#/components/schemas/FlightPathSegInfo'
          minItems: 1
      required:
      - pathSegInfo
    AltitudeRepEvent:
      anyOf:
      - type: string
        enum:
        - TA_CHANGE
        - RAN_NODE_CHANGE
        - GEO_LOCATION_CHANGE
        - ANY_ALTITUDE_CHANGE
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents the UAV's altitude reporting event.  \nPossible values are:\n- TA_CHANGE: Indicates that the UAV's altitude reporting trigger is the change of the UAV's\n  serving TA.\n- RAN_NODE_CHANGE: Indicates that the UAV's altitude reporting trigger is the change of the\n  UAV's serving RAN node.\n- GEO_LOCATION_CHANGE: Indicates that the UAV's altitude reporting trigger is the change of\n  the UAV's geographical location.\n- ANY_ALTITUDE_CHANGE: Indicates that the UAV's altitude reporting trigger is any change of\n  the UAV's altitude.\n"
    RangSlUavData:
      description: Represents the Ranging and Slidelink UAV data.
      type: object
      properties:
        uavId:
          $ref: TS29571_CommonData.yaml#/components/schemas/Gpsi
        presetDistInd:
          type: boolean
          description: 'Indicates whether the Ranging/Sidelink distance to the target UAV is small than the preset distance value. - "true" indicates that the distance is smaller than the preset distance value. - "false" indicates that the distance is not smaller than the preset distance value. - The default value is "false" when this attribute is omitted.

            '
        rangSlDistance:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/LinearDistance
      required:
      - uavId
      anyOf:
      - required:
        - presetDistInd
      - required:
        - rangSlDistance
    FlightPathSegInfo:
      description: Represents a flight path segment.
      type: object
      properties:
        flightSeg:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
        ussId:
          type: string
        candBdCrsPoints:
          type: array
          items:
            $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
          minItems: 1
        uavSpeed:
          $ref: TS29571_CommonData.yaml#/components/schemas/Float
        altitude:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/Altitude
        timeSchedule:
          $ref: TS29122_CommonData.yaml#/components/schemas/TimeWindow
        timeDuration:
          $ref: TS29122_CommonData.yaml#/components/schemas/DurationSec
      required:
      - flightSeg
      - ussId
      not:
        required:
        - timeSchedule
        - timeDuration
    UAVFlightAssistNotif:
      description: Represents the UAV Flight Assistance Notification.
      type: object
      properties:
        subscriptionId:
          type: string
        uavStatus:
          $ref: '#/components/schemas/UavStatus'
        bdCrsPoint:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
        altitude:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/Altitude
        altitudeRptInd:
          type: boolean
          enum:
          - true
          description: 'Indicates whether the UAV altitude reporting is successful or not. true indicates the failure of UAV altitude reporting.

            '
        uavLocation:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
        uavTrajectInd:
          type: boolean
          description: "Indicates whether the UAV is following the assigned path/trajectory.\n - \"true\" indicates that the UAV is following the assigned path/trajectory.\n - \"false\" indicates that UAV is not following the assign path/trajectory.\n - The default value is \"false\" when this attribute is omitted.\n"
        uavPresList:
          type: array
          items:
            $ref: TS29571_CommonData.yaml#/components/schemas/Gpsi
          minItems: 1
        rangSlUavData:
          type: array
          items:
            $ref: '#/components/schemas/RangSlUavData'
          minItems: 1
        qosSustainInfoData:
          type: array
          items:
            $ref: TS29522_AnalyticsExposure.yaml#/components/schemas/QosSustainabilityExposure
          minItems: 1
        altitudeRepReqs:
          $ref: '#/components/schemas/AltitudeRepReqs'
      required:
      - subscriptionId
      - uavStatus
      not:
        required:
        - altitude
        - altitudeRptInd
    AltThresholds:
      description: Represents the UAV's altitude thresholds.
      type: object
      properties:
        lowerBound:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/Altitude
        upperBound:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/Altitude
      anyOf:
      - required:
        - lowerBound
      - required:
        - upperBound
    AltitudeRepReqs:
      description: Represents the UAV's altitude reporting requirements.
      type: object
      properties:
        repThresholds:
          $ref: '#/components/schemas/AltThresholds'
        repPeriodicity:
          $ref: TS29571_CommonData.yaml#/components/schemas/Uinteger
        repEvents:
          type: array
          items:
            $ref: '#/components/schemas/AltitudeRepEvent'
          minItems: 1
      oneOf:
      - required:
        - repThresholds
      - required:
        - repPeriodicity
      - required:
        - repEvents
    UavStatus:
      anyOf:
      - type: string
        enum:
        - LEAVING
        - ENTERING
        - DEVIATING
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents the status of the UAV.  \nPossible values are:\n- LEAVING: Indicates that the UAV status is leaving an area which is part of the planned\n  flight path.\n- ENTERING: Indicates that the UAV status is entering an area which is part of the planned\n  flight path.\n- DEVIATING: Indicates that the UAV status is deviating from the planned flight path.\n"
    UAVFlightInfoReq:
      description: Represents the UAV Flight information retrieval request.
      type: object
      properties:
        gpsi:
          $ref: TS29571_CommonData.yaml#/components/schemas/Gpsi
        retrievePurpose:
          $ref: '#/components/schemas/RetrievePurpose'
        targetUssList:
          type: array
          items:
            type: string
          minItems: 1
        canFltPathsInfo:
          type: array
          items:
            $ref: '#/components/schemas/CandidateFlightPathInfo'
          minItems: 1
        suppFeat:
          $ref: TS29571_CommonData.yaml#/components/schemas/SupportedFeatures
      required:
      - gpsi
      - retrievePurpose
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}
externalDocs:
  description: '3GPP TS 29.522 V19.5.0; 5G System; Network Exposure Function Northbound APIs.

    '
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.522/