Acronis Subscriptions API

openapi: 3.2.0
info:
  title: Event Manager Subscriptions API
  description: Event Manager API describes the interface for event publishing and subscription management.
  version: v1
servers:
- url: https://dev-cloud.acronis.com/api/event_manager/v1
  variables: {}
tags:
- name: Subscriptions
paths:
  /subscriptions:
    post:
      operationId: Create event subscription
      description: Create a new event subscription based on the provided criteria, such as topic, cti filter, and optional filters.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSubscriptionRequest'
      responses:
        '201':
          description: Subscription was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionResponse'
        '401':
          description: Method required an authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Current user has no permissions for this URL/method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Another object of the same type already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - oauth2:
        - urn:acronis.com:event_manager:{cti_query}:subscriber
      tags:
      - Subscriptions
      summary: Create event subscription
      x-summary-source: derived
  /subscriptions/offset:
    get:
      operationId: Fetch subscription offset
      description: Fetch the current offset for a subscriber, indicating the position up to which events have been acknowledged.
      parameters:
      - name: subscription_id
        description: Required. Identifier of the subscription.
        required: true
        in: query
        schema:
          description: Required. Identifier of the subscription.
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionOffsetResponse'
        '401':
          description: Method required an authenticated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Current user has no permissions for this URL/method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - oauth2:
        - urn:acronis.com:event_manager:{cti_query}:subscriber
      tags:
      - Subscriptions
      summary: Fetch subscription offset
      x-summary-source: derived
components:
  schemas:
    GetSubscriptionOffsetResponse:
      type: object
      additionalProperties: false
      required:
      - subscription_id
      - offset
      properties:
        subscription_id:
          description: Unique identifier of the subscription.
          example: fd02a25c-fcb0-42a0-a5ce-56c1131db356
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        offset:
          description: Latest committed offset of the subscriber.
          type: integer
          format: int64
    debugInfo:
      description: Error debug information (map type)
      type: object
    error:
      description: Base error object
      example:
        domain: EventManager
        code: invalidEvent
        error: Bad Request
        context:
          errors:
          - event_id: 62d2afda-685e-457f-8624-92132d97a7ed
            message: 'Invalid payload: tenant_id is required'
      type: object
      required:
      - domain
      - code
      properties:
        domain:
          description: Error type or category. Can be ['Licensing','Access'] or name of service (for example 'PolicyManager' or 'VaultManager')
          type: string
        code:
          description: Error id or code, unique in the domain. Same as in 'reason' field
          type: string
        message:
          description: human-readable message, describing the error.
          type: string
        reason:
          description: Obsolete. Error id or code, unique in the domain. Same as in 'code' field
          type: string
        context:
          description: Error context dictionary
          type: object
        kb_link:
          $ref: '#/components/schemas/kbLinkInfo'
        debug:
          $ref: '#/components/schemas/debugInfo'
    ErrorMessage:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/error'
    kbLinkInfo:
      description: Components for kblink
      type: object
      required:
      - line_tag
      - ser_code
      - version
      - build
      - product
      - os
      properties:
        line_tag:
          type: string
        ser_code:
          type: string
        version:
          type: string
        build:
          type: string
        product:
          type: string
        os:
          type: string
    PostSubscriptionRequest:
      type: object
      additionalProperties: false
      required:
      - subscription_id
      - tenant_depth
      - types
      - topic_id
      properties:
        cel:
          description: Optional. CEL expression to filter events by.
          type: string
          maxLength: 4096
        subscription_id:
          description: Unique identifier of the subscription.
          example: fd02a25c-fcb0-42a0-a5ce-56c1131db356
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        tenant_depth:
          description: 'Required. Specifies the required tenancy depth

            `CURRENT` - return all the events with the tenant_id equal to the tenant_id specified in the subscription.

            `DIRECT` - return events for the tenant_id specified in the subscription and its direct children.

            `ALL` - return all the events for the tenant_id specified in the subscription and all its children.

            '
          enum:
          - CURRENT
          - DIRECT
          - ALL
          type: string
        auto_commit_interval:
          description: 'Optional. Interval at which to auto-commit offsets. The interval is specified in ISO 8601 format.

            '
          default: PT5M
          type: string
          pattern: ^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$
        auto_commit:
          description: Optional. Keep track of the last offset acknowledged by this consumer and automatically commit it. Auto-commit will potentially be made at the beginning of each and every poll request and on subscription eviction. This is useful when the subscriber does not have an external storage to keep track of the last offset committed.
          default: false
          type: boolean
        types:
          description: "Required. List of event types this subscription delivers.\n\nAllowed CTI prefixes:\n  - `cti.a.p.em.event.v1.0~`\n  - `cti.a.p.em.msg.v1.0~`\n\nSupported forms (right side of `~` only):\n  - Exact type:\n      `cti.a.p.em.event.v1.0~a.p.tenant.created.v1.0`\n  - All types prefixed with a specific path:\n      `cti.a.p.em.event.v1.0~a.p.tenant.*`\n  - Latest version of a particular type:\n      `cti.a.p.em.event.v1.0~a.p.tenant.updated.v1.*`\n\nVersion wildcard semantics:\n  - When v1.* is used, matching events are upcast to the latest available version of that type.\n  - When version is missing (i.e.,cti.a.p.em.event.v1.0~a.p.tenant.*), matching events are upcast to the latest available version of each major version."
          x-cti.reference:
          - cti.a.p.em.event.v1.0
          - cti.a.p.em.msg.v1.0
          type: array
          maxItems: 32
          minItems: 1
          items:
            $ref: '#/components/schemas/CTIWildcard'
        topic_id:
          description: 'Required. Identifier of the topic to subscribe to. The topic_id is used to filter events based on the topic they belong to.

            '
          x-cti.reference: cti.a.p.em.topic.v1.0
          type: string
          pattern: ^cti\.([a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z_][a-z0-9_.]*\.v[\d]+\.[\d]+)(~([a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z_][a-z0-9_.]*\.v[\d]+\.[\d]+))*(~[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12})?$
          maxLength: 1024
        session_timeout:
          description: 'Optional. Defines the maximum duration an instance can hold the leadership for event fetching without sending heartbeats. If the instance fails within this period, the system will reassign the leadership to ensure continuous event processing. This mechanism enhances fault tolerance by allowing for the automatic recovery of event consumption in case of instance failures. The duration is specified in ISO 8601 format.

            '
          default: PT30S
          type: string
          pattern: ^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$
        tenant_id:
          description: 'Optional. Specifies the root of the tenant hierarchy subtree to apply event filtering.

            If not provided, the tenant_id will be extracted from the access token.

            '
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        subject_types:
          description: Optional. List of subject types to filter by. Wildcard is supported.
          x-cti.reference: true
          type: array
          maxItems: 32
          items:
            $ref: '#/components/schemas/CTIWildcard'
    CTIWildcard:
      description: 'CTI with wildcard support, where the wildcard `*` can only be used as the final character of a segment.

        '
      type: string
      pattern: ^cti((\.([a-z][a-z0-9_]*))|\.)?(\.([a-z][a-z0-9_]*))?(\.([a-z_][a-z0-9_.]*))?(\.v(\d+|\d*\.\d*|\d*\.)?)?(~(([a-z][a-z0-9_]*)|([a-z][a-z0-9_]*)\.)?(\.([a-z][a-z0-9_]*))?(\.([a-z_][a-z0-9_.]*))?(\.v(\d+|\d*\.\d*|\d*\.)?)?)*\*$|^cti\.([a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z_][a-z0-9_.]*\.v[\d]+\.[\d]+)(~([a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z_][a-z0-9_.]*\.v[\d]+\.[\d]+))*(~[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12})?$
      maxLength: 1024
    GetSubscriptionResponse:
      type: object
      additionalProperties: false
      required:
      - subscription_id
      - tenant_depth
      - types
      - topic_id
      properties:
        cel:
          description: Optional. CEL expression to filter events by.
          type: string
          maxLength: 4096
        subscription_id:
          description: Unique identifier of the subscription.
          example: fd02a25c-fcb0-42a0-a5ce-56c1131db356
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        tenant_depth:
          description: 'Required. Specifies the required tenancy depth

            `CURRENT` - return all the events with the tenant_id equal to the tenant_id specified in the subscription.

            `DIRECT` - return events for the tenant_id specified in the subscription and its direct children.

            `ALL` - return all the events for the tenant_id specified in the subscription and all its children.

            '
          enum:
          - CURRENT
          - DIRECT
          - ALL
          type: string
        auto_commit_interval:
          description: 'Optional. Interval at which to auto-commit offsets. The interval is specified in ISO 8601 format.

            '
          default: PT5M
          type: string
          pattern: ^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$
        auto_commit:
          description: Optional. Keep track of the last offset acknowledged by this consumer and automatically commit it. Auto-commit will potentially be made at the beginning of each and every poll request and on subscription eviction. This is useful when the subscriber does not have an external storage to keep track of the last offset committed.
          default: false
          type: boolean
        types:
          description: "Required. List of event types this subscription delivers.\n\nAllowed CTI prefixes:\n  - `cti.a.p.em.event.v1.0~`\n  - `cti.a.p.em.msg.v1.0~`\n\nSupported forms (right side of `~` only):\n  - Exact type:\n      `cti.a.p.em.event.v1.0~a.p.tenant.created.v1.0`\n  - All types prefixed with a specific path:\n      `cti.a.p.em.event.v1.0~a.p.tenant.*`\n  - Latest version of a particular type:\n      `cti.a.p.em.event.v1.0~a.p.tenant.updated.v1.*`\n\nVersion wildcard semantics:\n  - When v1.* is used, matching events are upcast to the latest available version of that type.\n  - When version is missing (i.e.,cti.a.p.em.event.v1.0~a.p.tenant.*), matching events are upcast to the latest available version of each major version."
          x-cti.reference:
          - cti.a.p.em.event.v1.0
          - cti.a.p.em.msg.v1.0
          type: array
          maxItems: 32
          minItems: 1
          items:
            $ref: '#/components/schemas/CTIWildcard'
        topic_id:
          description: 'Required. Identifier of the topic to subscribe to. The topic_id is used to filter events based on the topic they belong to.

            '
          x-cti.reference: cti.a.p.em.topic.v1.0
          type: string
          pattern: ^cti\.([a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z_][a-z0-9_.]*\.v[\d]+\.[\d]+)(~([a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\.[a-z_][a-z0-9_.]*\.v[\d]+\.[\d]+))*(~[0-9a-f]{8}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{4}\b-[0-9a-f]{12})?$
          maxLength: 1024
        session_timeout:
          description: 'Optional. Defines the maximum duration an instance can hold the leadership for event fetching without sending heartbeats. If the instance fails within this period, the system will reassign the leadership to ensure continuous event processing. This mechanism enhances fault tolerance by allowing for the automatic recovery of event consumption in case of instance failures. The duration is specified in ISO 8601 format.

            '
          default: PT30S
          type: string
          pattern: ^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$
        tenant_id:
          description: 'Optional. Specifies the root of the tenant hierarchy subtree to apply event filtering.

            If not provided, the tenant_id will be extracted from the access token.

            '
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        subject_types:
          description: Optional. List of subject types to filter by. Wildcard is supported.
          x-cti.reference: true
          type: array
          maxItems: 32
          items:
            $ref: '#/components/schemas/CTIWildcard'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 security scheme definition for a service authorization.
      flows:
        password:
          scopes:
            urn:acronis.com:event_manager:{cti_query}:publisher: ''
            urn:acronis.com:event_manager:{cti_query}:subscriber: ''
            urn:acronis.com:audit:{role|permissions}: ''
          tokenUrl: /bc/ipd/token
        clientCredentials:
          scopes:
            urn:acronis.com:event_manager:{cti_query}:publisher: ''
            urn:acronis.com:event_manager:{cti_query}:subscriber: ''
            urn:acronis.com:audit:{role|permissions}: ''
          tokenUrl: /bc/ipd/token
        authorizationCode:
          scopes:
            urn:acronis.com:event_manager:{cti_query}:publisher: ''
            urn:acronis.com:event_manager:{cti_query}:subscriber: ''
            urn:acronis.com:audit:{role|permissions}: ''
          authorizationUrl: /bc/ipd/authorize
          tokenUrl: /bc/ipd/token