openapi: 3.0.3
info:
  title: Cumulocity Notification 2.0 API
  version: 10.20.0
  description: |
    High-throughput, persistent, ordered notification streaming for production microservices. Subscribers
    declare typed subscriptions (managed object, measurements, events, alarms, operations), exchange them
    for short-lived JWT tokens, and consume via WebSocket. Survives subscriber outages by buffering messages
    on the server.
servers:
- url: https://{tenant}.cumulocity.com
  variables:
    tenant:
      default: example
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Subscriptions
- name: Tokens
paths:
  /notification2/subscriptions:
    get:
      tags: [Subscriptions]
      summary: List Notification 2.0 Subscriptions
      operationId: listSubscriptions
      parameters:
      - name: source
        in: query
        schema: {type: string}
      - name: context
        in: query
        schema:
          type: string
          enum: [tenant, mo]
      - name: subscription
        in: query
        schema: {type: string}
      responses:
        '200':
          description: A collection of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCollection'
    post:
      tags: [Subscriptions]
      summary: Create a Subscription
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201':
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    delete:
      tags: [Subscriptions]
      summary: Delete Subscriptions by Filter
      operationId: deleteSubscriptions
      responses:
        '204':
          description: Subscriptions deleted.
  /notification2/subscriptions/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema: {type: string}
    get:
      tags: [Subscriptions]
      summary: Retrieve a Subscription
      operationId: getSubscription
      responses:
        '200':
          description: A single subscription.
    delete:
      tags: [Subscriptions]
      summary: Delete a Subscription
      operationId: deleteSubscription
      responses:
        '204':
          description: Subscription deleted.
  /notification2/token:
    post:
      tags: [Tokens]
      summary: Create a Subscription Token
      operationId: createToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: A short-lived JWT token to use with the WebSocket consumer endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
  /notification2/unsubscribe:
    post:
      tags: [Tokens]
      summary: Unsubscribe (Invalidate Token)
      operationId: unsubscribeToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token: {type: string}
      responses:
        '200':
          description: Token invalidated.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Subscription:
      type: object
      required: [subscription, context]
      properties:
        id: {type: string, readOnly: true}
        self: {type: string, format: uri, readOnly: true}
        subscription: {type: string}
        context:
          type: string
          enum: [tenant, mo]
        source:
          type: object
          properties:
            id: {type: string}
            self: {type: string, format: uri}
        fragmentsToCopy:
          type: array
          items: {type: string}
        subscriptionFilter:
          type: object
          properties:
            apis:
              type: array
              items:
                type: string
                enum: [alarms, events, eventsWithChildren, managedobjects, measurements, operations]
            typeFilter: {type: string}
        nonPersistent: {type: boolean}
    SubscriptionCollection:
      type: object
      properties:
        self: {type: string, format: uri}
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    TokenRequest:
      type: object
      required: [subscriber, subscription]
      properties:
        subscriber: {type: string}
        subscription: {type: string}
        expiresInMinutes:
          type: integer
          minimum: 1
          maximum: 1440
        nonPersistent: {type: boolean}
        signed: {type: boolean}
        shared: {type: boolean}
    TokenResponse:
      type: object
      properties:
        token: {type: string}