> ## Documentation Index
> Fetch the complete documentation index at: https://docs.occtoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Consume tenant-scoped CloudEvents by pull or live stream, and inspect the retained stream's current position.

The Occtoo Events API lets you react to changes across your tenant — sources, cards, segments, destinations, endpoints, and users — without polling each resource. Every change is published as a [CloudEvents](https://cloudevents.io/) message (`application/cloudevents+json`).

## Consume and inspect events

<Columns cols={3}>
  <Card title="Pull">
    Page through events with `GET /v1/events` using a cursor. Good for batch processing and catch-up jobs.
  </Card>

  <Card title="Metadata">
    Inspect the first and latest retained positions and exact event count with `GET /v1/events/metadata`. Good for consumer health checks.
  </Card>

  <Card title="Stream" href="/api-reference/events/streaming">
    Subscribe to a live, ordered Server-Sent Events stream at `GET /v1/events/stream`. Good for real-time reactions.
  </Card>
</Columns>

## Inspect stream metadata

Call `GET /v1/events/metadata` to inspect the retained stream without retrieving event payloads. It accepts the same optional `filter` as the pull and stream endpoints.

```bash theme={null}
curl --get 'https://api.occtoo.com/v1/events/metadata' \
  --header 'Authorization: Bearer <access-token>' \
  --data-urlencode 'filter=type eq "source.updated" and sourceId eq "products"'
```

```json theme={null}
{
  "first": {
    "sequence": "003.00000000000000184001",
    "time": "2026-07-04T08:10:00Z"
  },
  "latest": {
    "sequence": "003.00000000000000184467",
    "time": "2026-07-04T09:15:12.345Z"
  },
  "after": "<opaque pull cursor>",
  "total": 184
}
```

* `first` and `latest` identify the boundaries of the retained filtered view. Their `time` is `null` when the CloudEvent has no time.
* `after` is an opaque pull cursor for the `latest` position. Store it as a checkpoint or pass it to `GET /v1/events`.
* `total` is the exact count across the complete retained filtered view, not the count after a consumer checkpoint.

Compare `latest.sequence` with your last successfully processed sequence to determine whether a consumer is caught up. Do not use the difference between sequences as a pending-event count because filtered-out events can create gaps.

When no retained event matches, `first`, `latest`, and `after` are `null`, and `total` is `0`.

## Event types

Occtoo publishes 30 event types across sources, cards, segments, destinations, endpoints and users. All are currently at payload schema version `1.0`.

Every `data` payload includes these two properties, so they are omitted from the tables below:

| Property         | Type             | Description                                                                                        |
| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `correlationIds` | `string[]`       | Ids correlating this event with the operation that caused it. Always present.                      |
| `actor`          | `object \| null` | Who caused the change, as `{ "id": "<user or service id>" }`. `null` for system-initiated changes. |

In the tables, `?` marks a property that is not required — it may be absent or `null`. See the [data property reference](#data-property-reference) for types and meanings.

### Sources

| Event type             | Description                     | Data properties                                                                      |
| ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------ |
| `source.created`       | A source was created.           | `sourceId`                                                                           |
| `source.updated`       | A source configuration changed. | `sourceId`, `changes`, `properties?`                                                 |
| `source.deleted`       | A source was deleted.           | `sourceId`                                                                           |
| `source_entry.added`   | A source entry was added.       | `sourceId`, `entryKey`, `version`, `properties?`                                     |
| `source_entry.updated` | A source entry changed.         | `sourceId`, `entryKey`, `version`, `changedProperties`, `valuesTruncated`, `values?` |
| `source_entry.deleted` | A source entry was deleted.     | `sourceId`, `entryKey`, `version`                                                    |

### Cards

| Event type                        | Description                                | Data properties                                     |
| --------------------------------- | ------------------------------------------ | --------------------------------------------------- |
| `card.updated`                    | A card changed as a result of source data. | `cardDefinitionId`, `cardId`, `changedProperties`   |
| `card.segment_membership_changed` | A card entered or left a segment.          | `cardDefinitionId`, `cardId`, `segmentId`, `change` |
| `card_definition.created`         | A card definition was created.             | `cardDefinitionId`                                  |
| `card_definition.updated`         | A card definition changed.                 | `cardDefinitionId`, `changes`                       |
| `card_definition.activated`       | A card definition became active.           | `cardDefinitionId`                                  |
| `card_definition.deleted`         | A card definition was deleted.             | `cardDefinitionId`                                  |
| `card_definition.restored`        | A card definition was restored.            | `cardDefinitionId`                                  |

### Segments

| Event type         | Description             | Data properties                                                    |
| ------------------ | ----------------------- | ------------------------------------------------------------------ |
| `segment.created`  | A segment was created.  | `segmentId`, `segmentDefinitionId`, `cardDefinitionId?`            |
| `segment.updated`  | A segment changed.      | `segmentId`, `segmentDefinitionId`, `changes`, `cardDefinitionId?` |
| `segment.archived` | A segment was archived. | `segmentId`, `segmentDefinitionId`, `cardDefinitionId?`            |
| `segment.restored` | A segment was restored. | `segmentId`, `segmentDefinitionId`, `cardDefinitionId?`            |
| `segment.deleted`  | A segment was deleted.  | `segmentId`, `segmentDefinitionId`, `cardDefinitionId?`            |

### Destinations

| Event type                  | Description                                       | Data properties                                                                                                                                  |
| --------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `destination.created`       | A destination was created.                        | `destinationId`                                                                                                                                  |
| `destination.published`     | A destination was published.                      | `destinationId`                                                                                                                                  |
| `destination.stopped`       | A destination was stopped.                        | `destinationId`                                                                                                                                  |
| `destination.deleted`       | A destination was deleted.                        | `destinationId`                                                                                                                                  |
| `destination_entry.updated` | An entry was written to a destination endpoint.   | `destinationId`, `apiVersionId`, `apiVersion`, `endpointId`, `endpoint`, `entryId`, `version`, `changedProperties`, `valuesTruncated`, `values?` |
| `destination_entry.deleted` | An entry was removed from a destination endpoint. | `destinationId`, `apiVersionId`, `apiVersion`, `endpointId`, `endpoint`, `entryId`, `version`                                                    |

### Endpoints

| Event type         | Description                         | Data properties                                             |
| ------------------ | ----------------------------------- | ----------------------------------------------------------- |
| `endpoint.created` | A destination endpoint was created. | `destinationId`, `apiVersionId`, `apiVersion`, `endpointId` |
| `endpoint.updated` | A destination endpoint changed.     | `destinationId`, `apiVersionId`, `apiVersion`, `endpointId` |
| `endpoint.deleted` | A destination endpoint was deleted. | `destinationId`, `apiVersionId`, `apiVersion`, `endpointId` |

### Users

| Event type     | Description                | Data properties                               |
| -------------- | -------------------------- | --------------------------------------------- |
| `user.created` | A tenant user was created. | `userId`, `email?`, `firstName?`, `lastName?` |
| `user.updated` | A tenant user changed.     | `userId`, `email?`, `firstName?`, `lastName?` |
| `user.deleted` | A tenant user was deleted. | `userId`, `email?`, `firstName?`, `lastName?` |

## Data property reference

Properties marked **filterable** can be used in the filter grammar of `GET /v1/events`, `GET /v1/events/metadata`, and `GET /v1/events/stream`. The exact set accepted for a given type is returned as `filterableProperties` by `GET /v1/event-types`.

| Property              | Type                | Filterable | Description                                                                                                                          |
| --------------------- | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `apiVersion`          | `string`            | Yes        | Destination API version name the endpoint belongs to.                                                                                |
| `apiVersionId`        | `string`            | Yes        | Identifier of the destination API version.                                                                                           |
| `cardDefinitionId`    | `string`            | Yes        | Identifier of the card definition. Nullable on `segment.*` events.                                                                   |
| `cardId`              | `string`            | —          | Identifier of the individual card.                                                                                                   |
| `change`              | `string`            | —          | The membership change that occurred on `card.segment_membership_changed`.                                                            |
| `changedProperties`   | `string[]`          | —          | Names of the properties that changed.                                                                                                |
| `changes`             | `string[]`          | —          | Names of the configuration areas that changed.                                                                                       |
| `destinationId`       | `string`            | Yes        | Identifier of the destination.                                                                                                       |
| `email`               | `string \| null`    | —          | User email address.                                                                                                                  |
| `endpoint`            | `string`            | —          | Name of the destination endpoint.                                                                                                    |
| `endpointId`          | `string`            | Yes        | Identifier of the destination endpoint.                                                                                              |
| `entryId`             | `string`            | —          | Identifier of the destination entry.                                                                                                 |
| `entryKey`            | `string`            | —          | Key of the source entry within its source.                                                                                           |
| `firstName`           | `string \| null`    | —          | User first name.                                                                                                                     |
| `lastName`            | `string \| null`    | —          | User last name.                                                                                                                      |
| `properties`          | `array \| null`     | —          | On `source.updated`, the changed source properties as `{ "id", "change" }` objects. On `source_entry.added`, the entry's properties. |
| `segmentDefinitionId` | `string`            | Yes        | Identifier of the segment definition.                                                                                                |
| `segmentId`           | `string`            | Yes        | Identifier of the segment.                                                                                                           |
| `sourceId`            | `string`            | Yes        | Identifier of the source.                                                                                                            |
| `userId`              | `string`            | Yes        | Identifier of the tenant user.                                                                                                       |
| `values`              | `object \| null`    | —          | Changed values keyed by property name, each an array of `{ "value", "language?" }`. Omitted when `valuesTruncated` is `true`.        |
| `valuesTruncated`     | `boolean`           | —          | Whether `values` was dropped because the payload exceeded the size limit.                                                            |
| `version`             | `string \| integer` | —          | Monotonic version of the entry, as an integer-valued string or integer.                                                              |

<Note>
  `GET /v1/event-types` is the authoritative, machine-readable version of this page — it returns each type's description, `filterableProperties` and full inline JSON Schema. Fetch a single schema with `GET /v1/events/schemas/{type}/{version}`.
</Note>

## Resuming a stream

The SSE `id` field of each streamed event contains a raw, resumable event sequence. Pass it (or a pull cursor) as the `after` query parameter when reconnecting to continue exactly where you left off — no events lost, none replayed.

<Note>
  The Events API uses the same authentication as the rest of the platform API: a bearer token or API key. See the [API overview](/api-reference/overview#authentication) for how to obtain tokens.
</Note>