Notifications
List the derived workspace inbox and mark rows read or archived.
Notifications are computed from the platform snapshot, then overlaid with in-memory read and archive sets. Conceptual behavior: Search and notifications.
| Path | Auth | Envelope |
|---|---|---|
/api/notifications | Session | Bare JSON |
/api/v1/notifications | Any valid bearer API key | Bare JSON |
No Idempotency-Key. No pagination. No create or hard-delete.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/notifications | { notifications } (?workspaceId=) |
| PATCH | /api/notifications | Mark one or all |
| GET | /api/v1/notifications | { notifications } for the key workspace |
| PATCH | /api/v1/notifications | Same actions; workspace from the key |
Auth
Session: membership required. Foreign workspace: 403
Cannot access notifications for another workspace. (list and PATCH, including all: true).
v1: 401 Valid bearer API key is required. Workspace, personal, and copilot keys can read.
PATCH requires current workspace.write; a valid read-only key receives 403. workspaceId in
the PATCH body is ignored.
Workspace keys with workspace.secret.read or workspace.write receive full notification content.
Personal, Copilot, Viewer, organization-derived, and oversight reads receive workspace-safe.v1.
The safe row keeps id, workspaceId, type, priority, status, createdAt, targetView, and
optional targetId; it replaces title and body with [redacted] and includes:
{ "redaction": { "applied": true, "projection": "safe-content", "contractVersion": "workspace-safe.v1" } }
PATCH body
{ "id": "notif_…", "action": "read", "workspaceId": "session-only", "all": false }
| Field | Rules |
|---|---|
all | If true, mark every non-archived row read; id not required |
id | Required when all is not true |
action | read (default if omitted) or archive. Else 400 |
workspaceId | Session only |
200 { notification } for one id, or { notifications } for all. Unknown id: 404
Notification not found.
Notification object
| Field | Values / notes |
|---|---|
id | Stable derived id |
workspaceId | Workspace |
type | run | schedule | deployment | credential | document |
priority | critical | warning | info | success |
title | string |
body | string |
status | unread | read | archived |
createdAt | ISO-8601 |
targetView | workflow | databases | docs | knowledge | schedules | logs | settings |
targetId | Optional jump target |
Errors
| HTTP | Body |
|---|---|
| 400 | Notification id is required. |
| 400 | Notification action must be read or archive. |
| 401 | Valid bearer API key is required |
| 403 | Cannot access notifications for another workspace. |
| 404 | Notification not found. |
Gaps
- Read/archive sets are in-process only; they do not survive restart or another instance.
all: truedoes not archive; archived rows stay archived and are omitted from the mark-all return list.- No filter query (
status,type). - v1 safe reads do not require a workspace-scoped key; mutations do require workspace write authority.