> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/notifications-api.md).

# Notifications API

Subscribe to live change events for Records and Object Types in your tenant.

The Notifications API streams change events from your tenant as they happen. Use it to keep a user interface, dashboard, or cache current without polling. For example, a backend service can subscribe to an [Object Type](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types.md) and update a live dashboard when its Records change.

Events are live only. The API does not store them, so a client receives only the events that occur while it is connected. To read or change data, use the [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md).

The CLI's `ctxl logs --follow` command also uses this API to show new log messages as they arrive.

## What you can do

* Receive an event when a Record of an Object Type is created, updated, deleted, or rolled back.
* Narrow a subscription to one Record or one event action, such as `update`.
* Receive an event when an Object Type definition is created, changed, or deleted.

The reference also lists `POST /events`, which publishes events. Contextual services use it to publish the events described here.

## Base URL and reference

* **API base URL:** `https://notifications.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Notifications API reference](https://notifications.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://notifications.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). On the API base URL, the hostname identifies your tenant, so the `x-org-id` header is optional. If you send it, its value must match the hostname.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL.

## Authentication and permissions

Send an access token in the `Authorization: Bearer <access-token>` header. For credential types, token audiences, and tenant context, see [Authentication and Permissions](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md).

The token needs read permission for the events you want. The API delivers only the events that the token can read and leaves out the rest without an error. If a stream shows only heartbeats while matching changes occur, check the read permissions.

| Events                            | Subscription parameters                            | Required permission                                            |
| --------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
| Record changes for an Object Type | `namespace=native-object` and `module=<type-id>`   | **Object data & action execution → Read** for that Object Type |
| Object Type definition changes    | `namespace=contextual` and `module=native-objects` | **Service components → Object Types → Read**                   |

The permission names match the labels on an API Key's [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions). If you use an API Key, set them there.

A browser's native `EventSource` cannot send the `Authorization` header, and the API does not accept a token in the URL. A fetch-based server-sent events (SSE) client can send the header, and the API accepts cross-origin requests that include it. Never put a Client Secret in browser code. To show live updates without giving a browser an access token, subscribe from your server and forward the updates to your page.

## Request and response details

* Subscribe with `GET /events`. The `namespace` parameter is required: `native-object` or `contextual`. Add `module`, `id`, or `action` to narrow the subscription. If you omit one of these parameters, the subscription matches every value.
* For Record events, `module` is the Object Type ID used in its Native Object API path, and `id` is the Record's primary key value. Record changes use the actions `create`, `update`, `delete`, and `rollback`.
* A subscription without `action` can also receive other actions, such as log activity for a Record or a Record count for an Object Type. Check `action` before you act on an event.
* The response has content type `text/event-stream` and stays open. Each event is a `data:` line with one JSON object. The object contains `orgId`, `namespace`, `module`, `id`, `action`, and `data`. The event content is in `data.data`, and `data.metaData` can include `requestId` and `logCorrelationId`.
* For the Record actions `create`, `update`, `delete`, and `rollback`, `data.data` is the Record, and [Secret](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/data-schema/secret.md) properties show `<ENCRYPTED>`. Other actions carry other content.
* About once per second, the API sends an `event: heartbeat` message with no data. Ignore it.
* Delivery is best effort. Events are not replayed and have no IDs to resume from. A large event, or a large batch of events, may not be sent. After you reconnect, read the current state to catch up: Records from the Native Object API, and Object Type definitions from the [Native Object Registry API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-registry-api.md). The stream sets `retry: 10000`, so standard SSE clients wait 10 seconds before they reconnect.
* Bulk deletions do not send a Record `delete` event for each Record. Deleting all Records of an Object Type with the Native Object Registry API sends no Record `delete` events. Deleting an Object Type sends one Object Type `delete` event, not one for each of its Records. Deleting one Record with the Native Object API sends a Record `delete` event, with the same best-effort delivery as other events.
* Reconnect with a valid access token. A request with an expired token returns `401`.

## Example request

This request subscribes to changes to the Records of one Object Type:

```bash
curl --no-buffer "https://notifications.<tenant-id>.my.contextual.io/api/v1/events?namespace=native-object&module=<type-id>" \
  --header "Authorization: Bearer <access-token>"
```

Replace `<type-id>` with the Object Type ID and `<access-token>` with your access token. A successful response has status `200` and stays open. It sends a heartbeat about once per second and a `data:` line for matching events, which can include actions other than Record changes. Press Ctrl+C to close the stream.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/notifications-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
