openapi: 3.2.0
info:
  title: 3gpp-bdt BDT Subscription API
  version: 1.4.0
  description: "API for BDT resouce management.  \n© 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  \nAll rights reserved.\n"
servers:
- url: '{apiRoot}/3gpp-bdt/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: BDT Subscription
paths:
  /{scsAsId}/subscriptions:
    parameters:
    - name: scsAsId
      description: String identifying the SCS/AS.
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Fetch all active background data transfer subscription resources for a given SCS/AS.
      operationId: FetchAllActiveBDTSubscriptions
      tags:
      - BDT Subscription
      responses:
        '200':
          description: all BDT policy subscriptions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bdt'
                minItems: 0
                description: individual BDT policy subscription.
        '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: Creates a new background data transfer subscription resource.
      operationId: CreateBDTSubscription
      tags:
      - BDT Subscription
      requestBody:
        description: Contains the data to create a BDT subscription.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bdt'
      callbacks:
        bDTWarningNotification:
          '{$request.body#/notificationDestination}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ExNotification'
              responses:
                '204':
                  description: No Content (successful notification)
                '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
      responses:
        '201':
          description: Background data transfer policies offered to the SCS/AS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bdt'
          headers:
            Location:
              description: Contains the URI of the newly created 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
        '409':
          $ref: TS29122_CommonData.yaml#/components/responses/409
        '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:
    TransferPolicy:
      description: Represents an offered transfer policy sent from the SCEF to the SCS/AS, or a selected transfer policy sent from the SCS/AS to the SCEF.
      type: object
      properties:
        bdtPolicyId:
          type: integer
          description: Identifier for the transfer policy
        maxUplinkBandwidth:
          $ref: TS29122_CommonData.yaml#/components/schemas/Bandwidth
        maxDownlinkBandwidth:
          $ref: TS29122_CommonData.yaml#/components/schemas/Bandwidth
        ratingGroup:
          type: integer
          minimum: 0
          description: Indicates the rating group during the time window.
        timeWindow:
          $ref: TS29122_CommonData.yaml#/components/schemas/TimeWindow
      required:
      - bdtPolicyId
      - ratingGroup
      - timeWindow
    Bdt:
      description: Represents a Background Data Transfer subscription.
      type: object
      properties:
        self:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        supportedFeatures:
          $ref: TS29571_CommonData.yaml#/components/schemas/SupportedFeatures
        aspId:
          type: string
          description: Identifies an application service provider.
        volumePerUE:
          $ref: TS29122_CommonData.yaml#/components/schemas/UsageThreshold
        numberOfUEs:
          type: integer
          minimum: 1
          description: Identifies the number of UEs.
        desiredTimeWindow:
          $ref: TS29122_CommonData.yaml#/components/schemas/TimeWindow
        locationArea:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea
        locationArea5G:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
        referenceId:
          $ref: TS29122_CommonData.yaml#/components/schemas/BdtReferenceId
        transferPolicies:
          type: array
          items:
            $ref: '#/components/schemas/TransferPolicy'
          minItems: 1
          description: Identifies an offered transfer policy.
          readOnly: true
        selectedPolicy:
          type: integer
          description: 'Identity of the selected background data transfer policy. Shall not be present in initial message exchange, can be provided by NF service consumer in a subsequent message exchange.

            '
        externalGroupId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalGroupId
        notificationDestination:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        warnNotifEnabled:
          type: boolean
          description: 'Indicates whether the BDT warning notification is enabled (true) or not (false). Default value is false.

            '
        trafficDes:
          $ref: '#/components/schemas/TrafficDescriptor'
        energyInd:
          type: boolean
          default: false
          description: 'Indicates whether the AF is interested in transferring data in time windows that consume lower energy. true indicates that the AF is interested in transferring data in time windows that consume lower energy. false (default) indicates that the AF is not interested in transferring data in time windows that consume lower energy.

            '
      required:
      - volumePerUE
      - numberOfUEs
      - desiredTimeWindow
    ExNotification:
      description: Represents a Background Data Transfer notification.
      type: object
      properties:
        bdtRefId:
          $ref: TS29122_CommonData.yaml#/components/schemas/BdtReferenceId
        locationArea5G:
          $ref: TS29122_CommonData.yaml#/components/schemas/LocationArea5G
        timeWindow:
          $ref: TS29122_CommonData.yaml#/components/schemas/TimeWindow
        candPolicies:
          type: array
          items:
            $ref: '#/components/schemas/TransferPolicy'
          minItems: 1
          description: This IE indicates a list of the candidate transfer policies from which the AF may select a new transfer policy due to network performance degradation.
      required:
      - bdtRefId
    TrafficDescriptor:
      type: string
      description: Identify a traffic descriptor as defined in Figure 5.2.2 of 3GPP TS 24.526, octets v+5 to w.
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}
externalDocs:
  description: 3GPP TS 29.122 V19.5.0 T8 reference point for Northbound APIs
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.122/