openapi: 3.2.0 info: title: Event Manager Events 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: Events paths: /events: get: operationId: FetchEvents description: Fetch a batch of events starting from a specified cursor position, supporting real-time event consumption with optional limits and timeouts. parameters: - name: subscription_id description: 'Required. Identifier of the subscription under which events are being consumed. Used in conjunction with instance_id to manage event distribution. ' required: true in: query schema: description: 'Required. Identifier of the subscription under which events are being consumed. Used in conjunction with instance_id to manage event distribution. ' 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}$ - name: consumer_id description: Required. Unique identifier for the consumer instance, ensuring event distribution among multiple instances. required: true in: query schema: description: Required. Unique identifier for the consumer instance, ensuring event distribution among multiple instances. 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}$ - name: offset description: Required. Specifies the starting point for event fetching, allowing instances to resume from a precise position. required: true in: query schema: description: Required. Specifies the starting point for event fetching, allowing instances to resume from a precise position. type: integer format: int64 - name: limit description: Optional. Limits the number of events returned in one response. Helps manage processing load. in: query schema: description: Optional. Limits the number of events returned in one response. Helps manage processing load. default: 100 type: integer - name: timeout description: 'Optional. Time to wait for events to become available in ISO 8601 duration format. Can be decreased by the server to the session timeout of the subscription. ' in: query schema: description: 'Optional. Time to wait for events to become available in ISO 8601 duration format. Can be decreased by the server to the session timeout of the subscription. ' default: PT30S type: string pattern: ^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$ responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetEventsResponse' '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' '429': description: "This response indicates that the client must retry the request later. There are two possible reasons:\n 1. **Non-leader consumer instance**: The client is attempting to consume events as a non-leader instance. \n Only the leader instance is allowed to consume events. \n The client should retry after the time specified in the `Retry-After` header to attempt to become the leader.\n 2. **Rate limiting**: The client has exceeded the allowed rate of event consumption, either by sending too many poll requests or consuming too many events in a given period. \n The client should wait before retrying, as specified in the `Retry-After` header.\n" headers: Retry-After: description: The time in seconds to wait before retrying the poll request. required: true schema: description: The time in seconds to wait before retrying the poll request. type: integer content: {} '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - oauth2: - urn:acronis.com:event_manager:{cti_query}:subscriber tags: - Events summary: Fetch events x-summary-source: derived x-operation-id-source: normalized x-operation-id-original: Fetch events components: schemas: debugInfo: description: Error debug information (map type) type: object Event: description: 'Defines the structure of the event that has occurred. Events will contain two types of information: the event data representing the occurrence and context metadata providing contextual information about the occurrence. A single occurrence may result in more than one event. Events are limited to a maximum size of 64KB, which includes both headers and payload. ' x-cti.cti: - cti.a.p.em.event.v1.0 - cti.a.p.em.msg.v1.0 x-cti.final: false example: id: eb39471d-a1c5-44d4-8a2a-cb413d720e87 type: cti.a.p.em.event.v1.0~a.p.test.async.event.v1.0 time: '2022-03-31T10:43:21Z' ingest_time: '2021-04-15T19:41:40.1007002Z' previous: 1 sequence: 2 source: '123' tenant_id: abbf321a-7d6a-49c9-8538-47db342d1638 data: message: Hello, World! type: object additionalProperties: false required: - id - type - time - source - tenant_id properties: id: description: "Immutable, producer-generated identifier of this event instance. While a randomly generated UUID or a similar mechanism is recommended for system-wide uniqueness, it is not possible to guarantee that no other producer will generate the same ID.\nUniqueness scope - Strongly RECOMMENDED to be a randomly generated UUIDv4 so collisions across producers are practically negligible. - Consumers and downstream services MAY assume uniqueness of `id` within the scope of `(type, id)`. \n However a better alternative is `(sequence, type)` combination for persistent topics.\n\nGeneration rules - MUST be assigned by the producer when the event is created and MUST NOT change thereafter. - MUST NOT be the nil UUID (`00000000-0000-0000-0000-000000000000`) and MUST NOT be empty. - SHOULD be lowercase canonical UUID text with hyphens.\n" example: 10c8cd6b-a8b3-4bac-b12f-ceae89c5e43f 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}$ type: description: The specific event type. x-cti.id: true 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 time: description: 'Precise time when event has occurred. The time is set by the producer and may be set as past or future time. The time should be in UTC and formatted as ISO 8601. ' example: '2021-03-13T22:43:50.1004002Z' type: string format: date-time ingest_time: description: 'Time when the event was received by Event Manager and fully controlled by the Event Manager. The time should be in UTC and formatted as ISO 8601. ' x-apis.writeable: false example: '2021-04-15T19:41:40.1007002Z' type: string format: date-time previous: description: 'Identifies the sequence number of the directly preceding event in the ordered topic stream. This field is used to explicitly link events in sequence, facilitating tracking of event order and detection of any missing events. This field is optional for unordered topics (e.g. topic.ordering == NONE) ' type: integer format: int64 sequence: description: 'A unique identifier that represents the position of this event within the overall event stream. This sequence number is crucial for maintaining the order of events within ordered topics. In ''PRODUCER'' ordering mode, this number is assigned by the event producer. In ''EVENTMANAGER'' ordering mode, this number is assigned by the event manager. This field is optional for unordered topics (e.g. topic.ordering == NONE) ' type: integer format: int64 source: description: 'The source that produced the event, specified by type and ID. It can be any context filled by Producer. This field is not being processed by Event Manager and it''s up to Producer to define what to be specified in the source field. This field could be used for debugging purposes or as additional information for Consumer ' example: com.acronis.eu2-cloud/account-server/ type: string maxLength: 1024 subject: description: 'ID of the specific object where event (e.g. state change notification) happened. For example, it can be a task id in the cti.a.p.em.event.v1.0~a.p.task.created.v1.0 event It can be omitted for cases where the event is not related to a specific object. ' x-cti.overridable: true example: 152a71d6-51cd-11ec-bf63-0242ac130002 type: string maxLength: 1024 subject_type: description: 'CTI type of the subject. Required to provide granular access to events associated with specific subject type. If `allowed_subject_types` is defined for event type field value should represent same or derived CTI type. ' x-cti.reference: true x-cti.overridable: true 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 tenant_id: description: Acronis tenant ID that generated the event example: d52a71d6-51cd-11ec-bf63-0242ac130002 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}$ client_id: description: Acronis API client ID (or Agent ID) that generated the event. Can be used to isolate events for different agents or clients example: a52a71d6-51cd-11ec-bf63-0242ac130002 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}$ trace_parent: description: ID of event which caused this event to connect event reactions. Typically this uuid should reference to parent event id example: a6771d65-51cd-11ec-bf63-0242ac130002 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}$ data_ref: description: Payload data stored in some external place, i.e. to impose additional authorization, would be identical content to data example: https://s3.eu4-cloud.acronis.com/payloads/presentation_1 type: string maxLength: 1024 data: {} 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' GetEventsResponse: type: object additionalProperties: false required: - offset - events properties: offset: description: Latest offset of the subscriber. This is the offset that should be used in the next poll request. type: integer format: int64 events: description: A batch of events starting from the cursor position for each partition. type: array maxItems: 100 items: $ref: '#/components/schemas/Event' 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 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