# Event Manager API

**Base URL**: https://dev-cloud.acronis.com/api/event_manager/v1

## Endpoints

### GET /topics

Fetch a list of all available topics that client is allowed to publish or subscribe to.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com:event_manager:{cti_query}:publisher`
* `urn:acronis.com:event_manager:{cti_query}:subscriber`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `topic_id` | (Optional) Optional. Specific topic ID to fetch. Wildcard is not supported.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$` |


#### Responses

| Code | Description |
|------|-------------|
| `200` | List of topics |
| `401` | Method required an authenticated user |
| `403` | Current user has no permissions for this URL/method |
| `500` | Internal service error |


### GET /topics/offsets

Fetch the latest offset for a specific topic, providing a global view of the current stream state.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com:event_manager:{cti_query}:publisher`
* `urn:acronis.com:event_manager:{cti_query}:subscriber`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `topic_id` | (Required) Required, Topic ID to fetch the offset for.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$` |
| `position` | (Required) Required, the position to fetch the offset for.<br><br>**Type**: String<br>**Allowed values**:<br>- `EARLIEST`<br>- `TIMESTAMP`<br>- `CURRENT` |
| `timestamp` | (Optional) Required for timestamp positions. Fetch the offset position to the neares future from a specific time. The timestamp is specified in ISO 8601 format using the RFC 3339 profile.<br><br>**Type**: DateTime |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `401` | Method required an authenticated user |
| `403` | Current user has no permissions for this URL/method |
| `500` | Internal service error |


### GET /types

Fetch a list of all available event types that client is allowed to publish or subscribe to.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com:event_manager:{cti_query}:publisher`
* `urn:acronis.com:event_manager:{cti_query}:subscriber`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `topic_id` | (Optional) Optional. Topic ID to fetch the event types for.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$` |
| `type_id` | (Optional) Optional. Specific event type ID to fetch.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$` |
| `include_schema` | (Optional) Optional. Include the schema of the event type.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `401` | Method required an authenticated user |
| `403` | Current user has no permissions for this URL/method |
| `500` | Internal service error |


### POST /subscriptions

Create a new event subscription based on the provided criteria, such as topic, cti filter, and optional filters.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com:event_manager:{cti_query}:subscriber`

#### Request parameters

##### Request body

**Media type**: application/json

**Schema definition**:

| Name | Description |
|------|-------------|
| `cel` | Optional. CEL expression to filter events by.<br><br>**Type**: String<br>**Max length**: 4096 |
| `subscription_id` | Unique identifier of the subscription.<br><br>**Type**: String<br>**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` | Required. Specifies the required tenancy depth<br>`CURRENT` - return all the events with the tenant_id equal to the tenant_id specified in the subscription.<br>`DIRECT` - return events for the tenant_id specified in the subscription and its direct children.<br>`ALL` - return all the events for the tenant_id specified in the subscription and all its children.<br><br>**Type**: String<br>**Allowed values**:<br>- `CURRENT`<br>- `DIRECT`<br>- `ALL` |
| `auto_commit_interval` | Optional. Interval at which to auto-commit offsets. The interval is specified in ISO 8601 format.<br><br>**Type**: String<br>**Pattern**: `^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$`<br>**Default**: PT5M |
| `auto_commit` | 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.<br><br>**Type**: Boolean<br>**Default**: false |
| `types` | Required. List of event types this subscription delivers.<br><br>Allowed CTI prefixes:<br>  - `cti.a.p.em.event.v1.0~`<br>  - `cti.a.p.em.msg.v1.0~`<br><br>Supported forms (right side of `~` only):<br>  - Exact type:<br>      `cti.a.p.em.event.v1.0~a.p.tenant.created.v1.0`<br>  - All types prefixed with a specific path:<br>      `cti.a.p.em.event.v1.0~a.p.tenant.*`<br>  - Latest version of a particular type:<br>      `cti.a.p.em.event.v1.0~a.p.tenant.updated.v1.*`<br><br>Version wildcard semantics:<br>  - When v1.* is used, matching events are upcast to the latest available version of that type.<br>  - 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.<br><br>**Type**: Array of String<br>**Array type description:**<br>CTI with wildcard support, where the wildcard `*` can only be used as the final character of a segment.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$`<br>**Min items**: 1<br>**Max items**: 32 |
| `topic_id` | Required. Identifier of the topic to subscribe to. The topic_id is used to filter events based on the topic they belong to.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$` |
| `session_timeout` | 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.<br><br>**Type**: String<br>**Pattern**: `^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$`<br>**Default**: PT30S |
| `tenant_id` | Optional. Specifies the root of the tenant hierarchy subtree to apply event filtering.<br>If not provided, the tenant_id will be extracted from the access token.<br><br>**Type**: String<br>**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` | Optional. List of subject types to filter by. Wildcard is supported.<br><br>**Type**: Array of String<br>**Array type description:**<br>CTI with wildcard support, where the wildcard `*` can only be used as the final character of a segment.<br><br>**Type**: String<br>**Max length**: 1024<br>**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})?$`<br>**Max items**: 32 |

**Example**:

```json
{
  "cel": "event.data.my_field == 'my_value'",
  "subscription_id": "fd02a25c-fcb0-42a0-a5ce-56c1131db356",
  "tenant_depth": "CURRENT",
  "auto_commit_interval": "PT5M",
  "auto_commit": false,
  "types": [
    "cti.a.p.em.event.v1.0~a.p.tenant.created.v1.0",
    "cti.a.p.em.event.v1.0~a.p.tenant.deleted.v1.0"
  ],
  "topic_id": "cti.a.p.em.topic.v1.0~a.p.tenant.v1.0",
  "session_timeout": "PT30S",
  "tenant_id": "8e1DaF21-efCf-892f-5BE7-E6Aeae3D4408",
  "subject_types": [
    "cti.a.monitoring.subject.v1.0~a.monitoring.cpu.v1.0",
    "cti.a.monitoring.subject.v1.0~a.monitoring.gpu.v1.0"
  ]
}
```

#### Responses

| Code | Description |
|------|-------------|
| `201` | Subscription was successfully created. |
| `401` | Method required an authenticated user |
| `403` | Current user has no permissions for this URL/method |
| `500` | Internal service error |
| `409` | Another object of the same type already exists |


### GET /subscriptions/offset

Fetch the current offset for a subscriber, indicating the position up to which events have been acknowledged.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com:event_manager:{cti_query}:subscriber`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `subscription_id` | (Required) Required. Identifier of the subscription.<br><br>**Type**: String<br>**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

| Code | Description |
|------|-------------|
| `200` | - |
| `401` | Method required an authenticated user |
| `403` | Current user has no permissions for this URL/method |
| `500` | Internal service error |


### GET /events

Fetch a batch of events starting from a specified cursor position, supporting real-time event consumption with optional limits and timeouts.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com:event_manager:{cti_query}:subscriber`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `subscription_id` | (Required) Required. Identifier of the subscription under which events are being consumed.  Used in conjunction with instance_id to manage event distribution.<br><br>**Type**: String<br>**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}$` |
| `consumer_id` | (Required) Required. Unique identifier for the consumer instance, ensuring event distribution among multiple instances.<br><br>**Type**: String<br>**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` | (Required) Required. Specifies the starting point for event fetching, allowing instances to resume from a precise position.<br><br>**Type**: Long<br>**Format**: int64 |
| `limit` | (Optional) Optional. Limits the number of events returned in one response. Helps manage processing load.<br><br>**Type**: Integer<br>**Default**: 100 |
| `timeout` | (Optional) 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.<br><br>**Type**: String<br>**Pattern**: `^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$`<br>**Default**: PT30S |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `429` | This response indicates that the client must retry the request later. There are two possible reasons:<br>  1. **Non-leader consumer instance**: The client is attempting to consume events as a non-leader instance. <br>    Only the leader instance is allowed to consume events. <br>    The client should retry after the time specified in the `Retry-After` header to attempt to become the leader.<br>  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. <br>    The client should wait before retrying, as specified in the `Retry-After` header. |
| `401` | Method required an authenticated user |
| `403` | Current user has no permissions for this URL/method |
| `500` | Internal service error |