3GPP UAV Flight Assistance Configurations (Collection) API

openapi: 3.2.0
info:
  title: 3gpp-uav-fa UAV Flight Assistance Configurations (Collection) 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: UAV Flight Assistance Configurations (Collection)
paths:
  /{afId}/configurations:
    parameters:
    - name: afId
      in: path
      description: Represents the identifier of the AF.
      required: true
      schema:
        type: string
    get:
      summary: Request to retrieve all the active UAV Flight Assistance Configurations at the NEF.
      operationId: GetUavFlightAssistConfig
      tags:
      - UAV Flight Assistance Configurations (Collection)
      responses:
        '200':
          description: 'OK. All the Individual UAV Flight Assistance Configuration resources managed by the NEF are returned. If there are no existing Individual UAV Flight Assistance Configuration resources managed at the NEF, an empty array is returned.

            '
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UavFlightAssistance'
                minItems: 0
        '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
        '406':
          $ref: TS29122_CommonData.yaml#/components/responses/406
        '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
    post:
      summary: Request the creation of a new UAV Flight Assistance Configuration.
      operationId: CreateUavFlightAssistConfig
      tags:
      - UAV Flight Assistance Configurations (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UavFlightAssistance'
      responses:
        '201':
          description: 'Created. The UAV Flight Assistance Configuration is successfully created and a representation of the created Individual UAV Flight Assistance Configuration resource shall be returned.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UavFlightAssistance'
          headers:
            Location:
              description: 'Contains the URI of the created Individual UAV Flight Assistance Configuration resource.

                '
              required: true
              schema:
                type: string
        '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
      callbacks:
        UavFlightAssistNotif:
          '{$request.body#/notifUri}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/UAVFlightAssistNotif'
              responses:
                '200':
                  description: 'OK. The notification is successfully received and acknowledged, and notification related information is returned in the response body.

                    '
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/UAVFlightAssistNotifResp'
                '204':
                  description: 'No Content. The notification is successfully received and acknowledged.

                    '
                '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:
    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
    UavFlightAssistance:
      description: Represents the UAV Flight Assistance Configuration.
      type: object
      properties:
        uavId:
          $ref: TS29571_CommonData.yaml#/components/schemas/Gpsi
        reqPurpose:
          $ref: '#/components/schemas/RequestPurpose'
        monitorMode:
          $ref: '#/components/schemas/MonitoringMode'
        environingUavs:
          type: array
          items:
            $ref: TS29571_CommonData.yaml#/components/schemas/Gpsi
          minItems: 1
        preSetDistance:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/LinearDistance
        qosSustReq:
          $ref: TS29522_AnalyticsExposure.yaml#/components/schemas/AnalyticsEventFilter
        notifUri:
          $ref: TS29122_CommonData.yaml#/components/schemas/Uri
        flightPath:
          $ref: '#/components/schemas/FlightPath'
        altitudeRep:
          type: array
          items:
            $ref: '#/components/schemas/AltitudeReport'
          minItems: 1
        altitudeRepReqs:
          $ref: '#/components/schemas/AltitudeRepReqs'
        stopAltRepInd:
          type: boolean
          enum:
          - true
          description: 'Indicates whether to stop the altitude reporting for the UAV UE. Set to true indicates to stop the altitude reporting for the UAV UE. When present, this attribute shall be set to true. The presence of this attribute set to the value false is forbidden. This attribute may be present only in the PUT request.

            '
        suppFeat:
          $ref: TS29571_CommonData.yaml#/components/schemas/SupportedFeatures
      required:
      - uavId
      - reqPurpose
      - notifUri
    MonitoringMode:
      anyOf:
      - type: string
        enum:
        - UAV_LOCATION
        - FLIGHT_TRAJECTORY
        - FLIGHT_ENVIRONMENT
        - RANGING_SIDELINK_POSITION
        - QOS_SUSTAINABILITY_ANALYTICS
      - 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 in UAV Flight Assistance monitoring mode.  \nPossible values are:\n  - UAV_LOCATION: Indicates that the monitoring mode is UAV location monitoring.\n  - FLIGHT_TRAJECTORY: Indicates that the monitoring mode is flight trajectory\n    monitoring.\n  - FLIGHT_ENVIRONMENT: Indicates that the monitoring mode is flight environment\n    monitoring.\n  - RANGING_SIDELINK_POSITION: Indicates that the monitoring mode is\n    Ranging/Sidelink positioning location monitoring.\n  - QOS_SUSTAINABILITY_ANALYTICS: Indicates that the monitoring mode is QoS sustainability\n    analytics monitoring.\n"
    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
    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
    AltitudeReport:
      description: Represents the UAV's altitude report.
      type: object
      properties:
        altitude:
          $ref: TS29572_Nlmf_Location.yaml#/components/schemas/Altitude
        event:
          $ref: '#/components/schemas/AltitudeRepEvent'
        timeStamp:
          $ref: TS29122_CommonData.yaml#/components/schemas/DateTime
      required:
      - altitude
    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
    RequestPurpose:
      anyOf:
      - type: string
        enum:
        - USS_CHANGEOVER
        - IN_FLIGHT_MONITORING
      - 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 UAV Flight Assitance request purpose.  \nPossible values are:\n  - USS_CHANGEOVER: Indicates that the purpose of the request is pre-flight planning.\n  - IN_FLIGHT_MONITORING:Indicates that the purpose of the request is in-flight monitoring.\n"
    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"
    UAVFlightAssistNotifResp:
      description: Represents the response to a UAV Flight Assistance Notification.
      type: object
      properties:
        ussChgInd:
          type: boolean
          description: 'This attribute is used to indicate whether the USS changeover was completed successfully. true indicates that USS changeover was successful. false indicates that USS changeover failed.

            '
      required:
      - ussChgInd
  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/