openapi: 3.0.0

info:
  title: 3gpp-ims-ee
  version: 1.0.0-alpha.2
  description: |
    API for IMS Event Exposure Services.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.522 V19.2.0; 5G System; Network Exposure Function Northbound APIs.
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.522/'

servers:
  - url: '{apiRoot}/3gpp-ims-ee/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.

security:
  - {}
  - oAuth2ClientCredentials: []

paths:
  /{afId}/subscriptions:
    parameters:
      - name: afId
        in: path
        description: Represents the identifier of the AF
        required: true
        schema:
          type: string

    get:
      summary: Retrieve all the active IMS EE Subscriptions managed by the NEF.
      operationId: GetImsEESubsc
      tags:
        - IMS EE Subscriptions (Collection)
      responses:
        '200':
          description: >
            OK. All the Individual IMS EE Subscription resource(s) managed by the NEF
            are returned.
            If there are no active Individual IMS EE Subscription resources at the NEF,
            an empty array is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ImsEESubsc'
                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 IMS EE Subscription.
      operationId: CreateImsEESubsc
      tags:
        - IMS EE Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImsEESubsc'
      responses:
        '201':
          description: >
            Created. A representation of the created IMS EE Subscription resource is
            returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImsEESubsc'
          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'
        '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:
        IMSEENotif:
          '{$request.body#/notifUri}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ImsEENotif'
              responses:
                '204':
                  description: >
                    No Content. The IMS EE 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'


  /{afId}/subscriptions/{subscriptionId}:
    parameters:
      - name: afId
        in: path
        description: Represents the identifier of the AF.
        required: true
        schema:
          type: string
      - name: subscriptionId
        in: path
        description: >
          Represents the identifier of the Individual IMS EE Subscription.
          resource.
        required: true
        schema:
          type: string

    get:
      summary: Retrieve an existing Individual IMS EE Subscription resource.
      operationId: GetIndImsEESubsc
      tags:
        - Individual IMS EE Subscription (Document)
      responses:
        '200':
          description: >
            OK. The requested Individual IMS EE Subscription resource is successfully
            returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImsEESubsc'
        '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'

    put:
      summary: Request the update of an existing Individual IMS EE Subscription resource.
      operationId: UpdateIndImsEESubsc
      tags:
        - Individual IMS EE Subscription (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImsEESubsc'
      responses:
        '200':
          description: >
            OK. The Individual IMS EE Subscription resource is successfully updated and
            a representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImsEESubsc'
        '204':
          description: >
            No Content. The Individual IMS EE Subscription resource is successfully updated and
            no content is returned in the response body.
        '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'

    patch:
      summary: Request the modification of an existing Individual IMS EE Subscription resource.
      operationId: ModifyIndImsEESubsc
      tags:
        - Individual IMS EE Subscription (Document)
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/IMSEESubscPatch'
      responses:
        '200':
          description: >
            OK. The Individual IMS EE Subscription resource is successfully modified and
            a representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImsEESubsc'
        '204':
          description: >
            No Content. The Individual IMS EE Subscription resource is successfully modified and
            no content is returned in the response body.
        '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'

    delete:
      summary: Request the deletion of an existing Individual IMS EE Subscription resource.
      operationId: DeleteIndImsEESubsc
      tags:
        - Individual IMS EE Subscription (Document)
      responses:
        '204':
          description: >
            No Content. The Individual IMS EE Subscription resource is successfully deleted.
        '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'
        '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:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}

  schemas:
#

# STRUCTURED DATA TYPES
#

    ImsEESubsc:
      description: Represents an IMS E E Subscription.
      type: object
      properties:
        eventReqs:
          type: array
          items:
            $ref: '#/components/schemas/ImsEventRequirement'
          minItems: 1
        tgtUeIds:
          type: array
          items:
            $ref: 'TS29562_Nhss_imsSDM.yaml#/components/schemas/PublicIdentity'
          minItems: 1
        anyUeInd:
          type: boolean
          enum:
            - true
          description: >
            Identifies whether the subscription is for any UE.
            true indicates that the subscription is for any UE.
            When present, this attribute shall be set to true. The presence of this attribute set to
            the value false is forbidden.
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
      required:
        - eventReqs

    IMSEESubscPatch:
      description: Represents the requested modifications to an IMS EE Subscription.
      type: object
      properties:
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'

    ImsEENotif:
      description: Represents an IMS Event Exposure Notification.
      type: object
      properties:
        subscriptionId:
          type: string
        reports:
          type: array
          items:
             $ref: '#/components/schemas/ImsEventReport'
          minItems: 1
        imsFailureCause:
          type: string
          description: Contains the failure cause provided from the IMS AS.
      required:
        - subscriptionId
        - reports

    ImsEventRequirement:
      description: Represnets the IMS Event Requirement.
      type: object
      properties:
        stndImsEvent:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsEvent'
        nonStndImsEvent:
          description: Indicates the requested non-standardized IMS event.
          type: string
        imsEventType:
          $ref: '#/components/schemas/ImsEventType'
      required:
        - imsEventType
      oneOf:
        - required: [stndImsEvent]
        - required: [nonStndImsEvent]

    ImsEventReport:
      description: Represents an IMS Event Report.
      type: object
      properties:
        stndImsEvent:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsEvent'
        nonStndImsEvent:
          type: string
          description: Indicates the non-standardized IMS event within the requested scope.
        timeStamp:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/DateTime'
        eventRptInfo:
          type: string
      required:
        - timeStamp
      oneOf:
        - required: [stndImsEvent]
        - required: [nonStndImsEvent]


#
# SIMPLE DATA TYPES
#

#
# ENUMERATIONS DATA TYPES
#

    ImsEventType:
      anyOf:
      - type: string
        enum:
          - SUBSCRIBER_SPECIFIC
          - NON_SUBSCRIBER_SPECIFIC
      - 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 IMS Event Type.  
        Possible values are:
          - SUBSCRIBER_SPECIFIC: Indicates the IMS Event is Subscriber Specific for data channel.
          - NON_SUBSCRIBER_SPECIFIC: Indicates the IMS Event is Subscriber Specific for data
            channel.
