openapi: 3.0.0

info:
  title: CAPIF_Events_API
  description: |
    API for event subscription management.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
  version: "1.4.0"

externalDocs:
  description: 3GPP TS 29.222 V19.5.0 Common API Framework for 3GPP Northbound APIs
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.222/

servers:
  - url: '{apiRoot}/capif-events/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 7.5 of 3GPP TS 29.222

paths:
  /{subscriberId}/subscriptions:
    post:
      summary: Create a new CAPIFs Event Subscription.
      operationId: CreateEventSubsc
      tags:
        - CAPIFs Events Subscriptions (Collection)
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSubscription'
      responses:
        '201':
          description: Created (Successful creation of subscription).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure.
              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:
        notificationDestination:
          '{$request.body#/notificationDestination}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EventNotification'
              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'

  /{subscriberId}/subscriptions/{subscriptionId}:
    delete:
      summary: Delete an existing Individual CAPIF Events Subscription resource.
      operationId: DeleteIndEventSubsc
      tags:
        - Individual CAPIFs Events Subscription (Document)
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          description: Identifier of an individual Events Subscription
          required: true
          schema:
            type: string
      responses:
        '204':
          description: >
            No Content. The Individual CAPIF Events 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'

    put:
      summary: Update an existing Individual CAPIF Events Subscription resource.
      operationId: UpdateIndEventSubsc
      tags:
        - Individual CAPIFs Events Subscription (Document)
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          description: Identifier of the individual Subscriber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSubscription'
      responses:
        '200':
          description: OK (Successful update of the subscription).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '204':
          description: No Content. (Successful update of the 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'
        '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: Modify an existing Individual CAPIF Events Subscription resource.
      operationId: ModifyIndEventSubsc
      tags:
        - Individual CAPIFs Events Subscription (Document)
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          description: Identifier of the individual Subscriber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/EventSubscriptionPatch'
      responses:
        '200':
          description: OK (Successful modification of the subscription).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '204':
          description: No Content (Successful modification of the 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'
        '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:
    EventSubscription:
      type: object
      description: Represents a CAPIF Events Subscription.
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEvent'
          minItems: 1
          description: Subscribed events.
        eventFilters:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEventFilter'
          minItems: 1
          description: Subscribed event filters.
        eventReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        notificationDestination:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        requestTestNotification:
          type: boolean
          description: >
            Set to true by Subscriber to request the CAPIF core function to send a
            test notification as defined in in clause 7.6. Set to false or omitted otherwise.
        websockNotifConfig:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - events
        - notificationDestination

    EventNotification:
      type: object
      description: Represents a CAPIF Events Notification.
      properties:
        subscriptionId:
          type: string
          description: >
            Identifier of the subscription resource to which the notification
            is related.
        events:
          $ref: '#/components/schemas/CAPIFEvent'
        eventDetail:
          $ref: '#/components/schemas/CAPIFEventDetail'
      required:
        - subscriptionId
        - events

    CAPIFEventFilter:
      type: object
      description: Represents a CAPIF event filter.
      properties:
        apiIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identifier of the service API.
        apiInvokerIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identity of the API invoker.
        aefIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identifier of the API exposing function.

    CAPIFEventDetail:
      type: object
      description: Represents the CAPIF event related details.
      properties:
        serviceAPIDescriptions:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/ServiceAPIDescription'
          minItems: 1
          description: Description of the service API as published by the APF.
        apiIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identifier of the service API.
        apiInvokerIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identity of the API invoker.
        accCtrlPolList:
          $ref: '#/components/schemas/AccessControlPolicyListExt'
        invocationLogs:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Logging_API_Invocation_API.yaml#/components/schemas/InvocationLog'
          minItems: 1
          description: Invocation logs.
        apiTopoHide:
          $ref: '#/components/schemas/TopologyHiding'
        onboardingCriteria:
          type: array
          items:
            $ref: 'TS29222_CAPIF_API_Invoker_Management_API.yaml#/components/schemas/OnboardingCriteria'
          minItems: 1
        onboardedCount:
          type: array
          items:
            $ref: '#/components/schemas/ApiInvokerCount'
          minItems: 1
        discoveryCount:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryCount'
          minItems: 1

    AccessControlPolicyListExt:
      description: Represents the extension for access control policies.
      allOf:
        - $ref: 'TS29222_CAPIF_Access_Control_Policy_API.yaml#/components/schemas/AccessControlPolicyList'
        - type: object
          properties:
            apiId:
              type: string
      required:
        - apiId

    TopologyHiding:
      type: object
      description: Represents the routing rules information of a service API.
      properties:
        apiId:
          type: string
        routingRules:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Routing_Info_API.yaml#/components/schemas/RoutingRule'
          minItems: 1
      required:
        - apiId
        - routingRules

    EventSubscriptionPatch:
      type: object
      description: >
        Represents the parameters to request the modification of a CAPIF Events Subscription
        resource.
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEvent'
          minItems: 1
          description: Subscribed events.
        eventFilters:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEventFilter'
          minItems: 1
          description: Subscribed event filters.
        eventReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        notificationDestination:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'

    ApiInvokerCount:
      type: object
      description: Represents the count data for onboarding.
      properties:
        apiId:
          type: string
        count:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
      required:
        - apiId
        - count

    DiscoveryCount:
      type: object
      description: Represents the count data for discovery.
      properties:
        apiId:
          type: string
        discoveryReqCount:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        discoveryRspCount:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
      required:
        - apiId
      anyOf:
        - required: [discoveryReqCount]
        - required: [discoveryRspCount]

    CAPIFEvent:
      anyOf:
      - type: string
        enum:
          - SERVICE_API_AVAILABLE
          - SERVICE_API_UNAVAILABLE
          - SERVICE_API_UPDATE
          - API_INVOKER_ONBOARDED
          - API_INVOKER_OFFBOARDED
          - SERVICE_API_INVOCATION_SUCCESS
          - SERVICE_API_INVOCATION_FAILURE
          - ACCESS_CONTROL_POLICY_UPDATE
          - ACCESS_CONTROL_POLICY_UNAVAILABLE
          - API_INVOKER_AUTHORIZATION_REVOKED
          - API_INVOKER_UPDATED
          - API_TOPOLOGY_HIDING_CREATED
          - API_TOPOLOGY_HIDING_REVOKED
          - API_INVOKER_ONBOARDING_CRITERIA_FAILED
          - SERVICE_API_ONBOARDED_BY_API_INVOKERS_COUNT
          - SERVICE_API_DISCOVERY_BY_API_INVOKERS_COUNT
      - 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: |
        Describes the CAPIF event.  
        Possible values are:
        - SERVICE_API_AVAILABLE:
          Events related to the availability of service APIs after the service APIs are
          published.
        - SERVICE_API_UNAVAILABLE:
          Events related to the unavailability of service APIs after the service APIs are
          unpublished.
        - SERVICE_API_UPDATE: Events related to change in service API information.
        - API_INVOKER_ONBOARDED: Events related to API invoker onboarded to CAPIF.
        - API_INVOKER_OFFBOARDED: Events related to API invoker offboarded from CAPIF.
        - SERVICE_API_INVOCATION_SUCCESS:
          Events related to the successful invocation of service APIs.
        - SERVICE_API_INVOCATION_FAILURE: Events related to the failed invocation of service APIs.
        - ACCESS_CONTROL_POLICY_UPDATE:
          Events related to the update for the access control policy related to the service APIs.
        - ACCESS_CONTROL_POLICY_UNAVAILABLE:
          Events related to the unavailability of the access control policy related to
          the service APIs.
        - API_INVOKER_AUTHORIZATION_REVOKED: Events related to the revocation of the authorization
          of API invokers to access the service APIs.
        - API_INVOKER_UPDATED: Events related to API invoker profile updated to CAPIF.
        - API_TOPOLOGY_HIDING_CREATED:
          Events related to the creation or update of the API topology hiding
          information of the service APIs after the service APIs are published.
        - API_TOPOLOGY_HIDING_REVOKED:
          Events related to the revocation of the API topology hiding information of
          the service APIs after the service APIs are unpublished.
        - API_INVOKER_ONBOARDING_CRITERIA_FAILED: Events related to API Invoker onboarding criteria
          failed to be met. 
        - SERVICE_API_ONBOARDED_BY_API_INVOKERS_COUNT: Events related to the number of times the
          API Invokers requested to onboard the targeted service API(s).
        - SERVICE_API_DISCOVERY_BY_API_INVOKERS_COUNT: Events related to the number of times the
          API Invokers requested and/or received the targeted service API(s)during the
          discovery service.