Notifications
List notifications for a team and mark them seen. Responses use the standard envelope documented in Responses and errors.
Both routes return 403 for an invalid API key and 429 when its rate limit is exceeded. The session-only mutation returns 401 for a missing or invalid session.
Endpoints#
| Method | Path | Auth |
|---|---|---|
GET | /v1/notifications | API key + resolvable profile context |
POST | /v1/notifications/{notificationId}/seen | API key + session |
Details#
GET /v1/notifications#
The conditional auth wrapper requires a session, validated x-profile-id + x-team-id headers, or an API key scoped to both a profile and team. The notification team itself is selected from the API key’s team ID when present; otherwise it is selected from the session’s current team (falling back to the first profile team). Header values are not used to select the notification team, so an app-level API key with headers but no session still has no usable team.
Headers#
| Header | Required |
|---|---|
x-api-key | Yes |
Authorization | One valid context option; Bearer <session> |
x-profile-id | With x-team-id as an alternative context option |
x-team-id | With x-profile-id as an alternative context option |
Path parameters#
None.
Query parameters#
| Field | Type | Required | Constraints |
|---|---|---|---|
type | string | No | Only default; omitted defaults to default |
limit | integer | No | 1–100 |
exclusiveStartKey | string | No | Opaque key returned as lastEvaluatedKey |
profileId | string | No | Filters the fetched page to notifications unread by that profile |
Body#
Not applicable.
Success response#
200:
{
"success": true,
"data": {
"items": [],
"lastEvaluatedKey": "opaque-continuation-key"
}
}lastEvaluatedKey can be absent when no continuation key exists. The limit applies before the optional profileId unread filter, so a filtered page can contain fewer than limit items.
Errors and statuses#
Route errors: 400 invalid type/limit or no team is available; 401 session required by the auth wrapper; 500 notification retrieval failure.
POST /v1/notifications/{notificationId}/seen#
Marks notifications seen for the session’s current profile/team. A notification is automatically deleted when marking it seen means all non-API team members have seen it.
Headers#
| Header | Required |
|---|---|
x-api-key | Yes |
Authorization | Yes — Bearer <session> |
Path parameters#
| Param | Description |
|---|---|
notificationId | URL-encoded notification sort key, or the literal all or multiple |
Query parameters#
| Field | Type | Required | Constraints |
|---|---|---|---|
delete | string | No | Only true requests deletion; valid only for one ID and requires session profile role admin |
ids | string | Conditional | Required with path multiple; non-empty JSON string array or comma-separated IDs |
Body#
No JSON body.
Success response#
All successful variants return 200:
- single mark:
data: { markedAsSeen: true, notification }; - already seen: the same shape with the current notification;
- auto-delete:
data: { markedAsSeen: true, deleted: true, notificationId, message }; - admin delete:
data: { deleted: true, notificationId }; all:data: { markedAsSeen: true, count, deletedCount, message };multiple:data: { markedAsSeen: true, count, invalidIds, deletedCount, message }.
all fetches at most 1,000 notifications. multiple has no route-level ID-count limit.
Errors and statuses#
Route errors: 400 missing session team/profile, missing ID, invalid ids, or deletion requested with all/multiple; 403 non-admin single deletion; 404 single notification not found; 500 count, update, or deletion failure.