---
title: "Events"
description: "The CloudEvents envelope every Qomni event shares."
version: "en"
---

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

# Events

Every event is a [CloudEvent 1.0](https://cloudevents.io): the same envelope and, inside `data`, what is specific to each event. `id` is the idempotency key (it comes from the work, not from chance) and `subject` is the workspace, so a consumer can drop duplicates and process in order per workspace. Names follow `ai.qomni.<domain>.<object>.<action>.v<n>`.

## Envelope

CloudEvents 1.0 as every qomni event uses it (STYLE.md, events). Each event schema is this envelope plus its `type` and its `data`. `id` is the idempotency key, derived from the work; `subject` is the workspace slug, so brokers partition by workspace; `time` is when it happened.

| Field | Type | Detail |
| --- | --- | --- |
| `specversion` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | `"1.0"` |
| `id` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | ≤ 200 |
| `source` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | Who publishes it, e.g. /cells/co1/agents |
| `type` <br /><span class="q-ev-flag q-ev-required">Required</span> | string |  |
| `time` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | `date-time` |
| `datacontenttype` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | `"application/json"` |
| `subject` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | The workspace slug. |
| `livemode` <br /><span class="q-ev-flag q-ev-optional">Optional</span> | boolean | CloudEvents extension: false for test-mode work. |
| `traceparent` <br /><span class="q-ev-flag q-ev-optional">Optional</span> | string | CloudEvents distributed-tracing extension. |
| `data` <br /><span class="q-ev-flag q-ev-required">Required</span> | object |  |

## Shared objects

Objects several events carry inside `data`.

### `actor`

Who or what acted: an agent, a member, an API key (its ID, never the key) or the system.

| Field | Type | Detail |
| --- | --- | --- |
| `type` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | `agent`, `member`, `api_key`, `system` |
| `id` <br /><span class="q-ev-flag q-ev-required">Required</span> | string |  |
| `on_behalf_of` <br /><span class="q-ev-flag q-ev-optional">Optional</span> | string | The member an API key or an approved agent action acts for. |

### `subject`

| Field | Type | Detail |
| --- | --- | --- |
| `type` <br /><span class="q-ev-flag q-ev-required">Required</span> | string | `agent`, `conversation`, `call`, `phone_number` |
| `id` <br /><span class="q-ev-flag q-ev-required">Required</span> | string |  |

Source: https://docs.qomni.ai/events/index.mdx
