openapi: 3.0.0

info:
  title: 3gpp-ims-ee
  version: 1.0.1
  description: |
    API for the IMS Event Exposure Service.  
    © 2026, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.522 V19.6.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 Event Exposure Subscription.
      type: object
      properties:
        eventReqs:
          type: array
          items:
            $ref: '#/components/schemas/ImsEventRequirement'
          minItems: 1
        imsReptReq:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsReportingOptions'
        immReports:
          type: array
          items:
            $ref: '#/components/schemas/ImsEventReport'
          minItems: 1
        tgtUeIds:
          type: array
          items:
            $ref: 'TS29562_Nhss_imsSDM.yaml#/components/schemas/ImsPublicId'
          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'
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
        notifCorrelationId:
          type: string
      required:
        - eventReqs
        - imsReptReq
        - notifUri
        - notifCorrelationId
      oneOf:
        - required: [tgtUeIds]
        - required: [anyUeInd]

    ImsEESubscPatch:
      description: Represents the requested modifications to an IMS Event Exposure Subscription.
      type: object
      properties:
        eventReqs:
          type: array
          items:
            $ref: '#/components/schemas/ImsEventRequirement'
          minItems: 1
        imsReptReq:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsReportingOptions'
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'

    ImsEENotif:
      description: Represents an IMS Event Exposure Notification.
      type: object
      properties:
        subscriptionId:
          type: string
        sessionId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SessionId'
        reports:
          type: array
          items:
            $ref: '#/components/schemas/ImsEventReport'
          minItems: 1
        imsFailureCause:
          type: string
          description: Contains the failure cause provided from the IMS AS.
        tgtUeId:
          $ref: 'TS29562_Nhss_imsSDM.yaml#/components/schemas/ImsPublicId'
        eventsRemoved:
          type: array
          items:
            $ref: '#/components/schemas/ImsEventType'
          minItems: 1
        notifCorrelationId:
          type: string
      required:
        - subscriptionId
        - notifCorrelationId
      anyOf:
        - required: [reports]
        - required: [imsFailureCause]
        - required: [eventsRemoved]

    ImsEventRequirement:
      description: Represents the IMS Event Requirements.
      type: object
      properties:
        imsEventType:
          $ref: '#/components/schemas/ImsEventType'
        imsEventConfig:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsEventConfiguration'
      required:
        - imsEventType
        - imsEventConfig

    ImsEventReport:
      description: Represents an IMS Event Report.
      type: object
      properties:
        imsEvent:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsEvent'
        timeStamp:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/DateTime'
        eventRptInfo:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ImsEventReportInfo'
      required:
        - imsEvent
        - timeStamp


#
# 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 that the IMS Event type is Subscriber Specific for data
            channel.
          - NON_SUBSCRIBER_SPECIFIC: Indicates that the IMS Event type is Subscriber Specific for
            Data channel.