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

# Notifications API

> Read your in-app notification feed and mark items read through the Goliath developer API

## About

Read your in-app notifications (the bell feed) and mark them read from your own
code — track what's happening across your deals, contacts, and tasks without
opening the CRM.

All operations go through the developer API gateway — one endpoint, called by
`operationId`. If you haven't set up a key yet, start with the
[Developer API Overview](/developer-api/overview).

<Note>
  **These are your notifications**

  The feed is scoped to the key owner — you only ever read and mark your own
  notifications. A notification id that belongs to another user is a silent
  no-op on `markNotificationsRead`, never an error. See
  [Authorization](/developer-api/authorization) for the model.
</Note>

## Operations

### Reading the feed (`READ` scope)

| operationId                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listNotifications`             | List your notifications, newest first. Optional filters: `notificationTypeFilter`, `seen` (`true` = read only, `false` = unread only, omitted = both), `searchTerm`. Cursor-paginated (`limit` defaults to 25, capped at 50); `total` + `hasUnread` mean nothing is silently truncated, and each row carries the related-record ids (`contactId`, `dealId`, `noteId`, `replyId`, `taskId`, `callId`) plus `actionType`/`actionTargetId` for deep-linking. |
| `getNotificationCounts`         | Unread and read counts for your feed (the badge numbers). Optional `notificationTypeFilter`. A cheap poll for "do I have anything new" before listing.                                                                                                                                                                                                                                                                                                    |
| `getAvailableNotificationTypes` | The catalog of notification types you can filter by — each `notificationType` is the exact string to pass as `notificationTypeFilter`. Call this first: the filter is a free string, so a typo silently returns an empty feed rather than an error.                                                                                                                                                                                                       |

### Marking read (`WRITE` scope)

| operationId             | What it does                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `markNotificationsRead` | Mark specific notifications read or unread by id. `isSeen: true` clears them from the unread badge; `false` marks them unread. `notificationIds` come from `listNotifications`. Only your own notifications are affected. |

## Example

Fetch your unread notifications, then mark them read:

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "listNotifications", "variables": { "seen": false } }'
```

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "markNotificationsRead", "variables": { "notificationIds": ["NOTIFICATION_ID"], "isSeen": true } }'
```

Full variable schemas, response shapes, and worked examples for every
operation are available from the
[discovery endpoint](/developer-api/overview#discovering-operations).