GET
v1/notifications/
Service tier
One person's notifications in one organization, newest first (standalone apps).
Query email, org_id, workspace_ids (as for summary), filter (all, unread, mentions, needs_action), app, cursor (meta.next_cursor of the previous page) and limit (default 50, at most 200).
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/notifications/
Query parameters
| Name | Default |
app | none |
cursor | none |
email | none |
filter | none |
limit | none |
org_id | none |
workspace_ids | none |
Responses
200 data and meta envelope
{
"data": {
"notifications": [
"..."
]
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
curl -X GET "https://platform.mattering.io/api/internal/v1/notifications/?app=...&cursor=...&email=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: platform_app/notification_views.py (notification_views.internal_list)
POST
v1/notifications/emit/
Service tier
Store notification events for people (1 to 100 per call).
Body {"events": [event, ...]}; each event carries recipient_email, org_id, workspace_id, app, kind, title, body, actor, path, subject, dedupe_key, group_key, needs_action and occurred_at (contract section 3), plus the optional backfill booleans silent (stored, never emailed) and read (stored already read, never grouped or emailed); with either, occurred_at may lie up to 400 days back, otherwise at most 5 minutes (older values are clamped). app must be one the X-Internal-App-Origin header may emit. A dropped event is not an error: the answer is 200 with dropped: [{index, reason}] (reasons not_member, kind_off, self, invalid) so the caller never retries it; unknown_kind (not in the registry) and app_mismatch (the origin may not emit that app) are per-event drops too. A repeated dedupe_key is a no-op (duplicates); an event whose group_key matches an unread row folds into it (coalesced). Only malformed JSON, a missing or empty events list or more than 100 events answer 400.
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/notifications/emit/
Body keys (JSON)
| Key | Required | Default |
events | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"accepted": "...",
"duplicates": "...",
"coalesced": "...",
"dropped": "..."
},
"meta": {
"count": 0
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_json |
Example
curl -X POST "https://platform.mattering.io/api/internal/v1/notifications/emit/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"events": "..."
}'
Source: platform_app/notification_views.py (notification_views.internal_emit)
POST
v1/notifications/read/
Service tier
Mark one person's notifications read or unread (standalone apps).
Body {"email", "org_id", "ids": [...]} or {"all": true, "app"?}; "unread": true flips them back; optional workspace_ids (list or comma string) as for summary. Only rows the person can see are touched.
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/notifications/read/
Body keys (JSON)
| Key | Required | Default |
all | optional or conditional | none |
app | optional or conditional | none |
email | optional or conditional | none |
ids | optional or conditional | none |
org_id | optional or conditional | none |
unread | optional or conditional | none |
workspace_ids | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"updated": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_json |
Example
curl -X POST "https://platform.mattering.io/api/internal/v1/notifications/read/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"all": "...",
"app": "...",
"email": "...",
"ids": "...",
"org_id": "...",
"unread": "...",
"workspace_ids": "..."
}'
Source: platform_app/notification_views.py (notification_views.internal_read)
POST
v1/notifications/resolve/
Service tier
Mark matching notifications read, and resolve needs-action ones.
Body {"org_id", "app", "subject": {"type", "id"}} or group_key or dedupe_key instead of subject; optional recipient_email (omitted: everyone the rows are addressed to). Apps call this when the person opens the record inside the app.
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/notifications/resolve/
Body keys (JSON)
| Key | Required | Default |
app | optional or conditional | none |
dedupe_key | optional or conditional | none |
group_key | optional or conditional | none |
org_id | optional or conditional | none |
recipient_email | optional or conditional | none |
subject | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"matched": "...",
"read": "...",
"resolved": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_json |
Example
curl -X POST "https://platform.mattering.io/api/internal/v1/notifications/resolve/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"app": "...",
"dedupe_key": "...",
"group_key": "...",
"org_id": "...",
"recipient_email": "...",
"subject": "..."
}'
Source: platform_app/notification_views.py (notification_views.internal_resolve)
POST
v1/notifications/retract/
Service tier
Delete matching notifications (record deleted, or access lost).
Body as for resolve: org_id, app, subject or group_key or dedupe_key, optional recipient_email (omitted: everyone).
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/notifications/retract/
Body keys (JSON)
| Key | Required | Default |
app | optional or conditional | none |
dedupe_key | optional or conditional | none |
group_key | optional or conditional | none |
org_id | optional or conditional | none |
recipient_email | optional or conditional | none |
subject | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"deleted": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | invalid_json |
Example
curl -X POST "https://platform.mattering.io/api/internal/v1/notifications/retract/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"app": "...",
"dedupe_key": "...",
"group_key": "...",
"org_id": "...",
"recipient_email": "...",
"subject": "..."
}'
Source: platform_app/notification_views.py (notification_views.internal_retract)
GET
v1/notifications/summary/
Service tier
Bell counts for one person in one organization (standalone apps).
Query email, org_id and workspace_ids (comma list from the app's own session; when absent the platform asks the directory and, if that fails, counts organization-level rows only) and cursor (the last answer's; unchanged returns {unchanged: true, cursor}). other_orgs is always empty here.
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/notifications/summary/
Query parameters
| Name | Default |
cursor | none |
email | none |
org_id | none |
workspace_ids | none |
Responses
200 data and meta envelope
{
"data": {
"unread": "...",
"needs_action": "...",
"by_app": "...",
"other_orgs": "...",
"cursor": "..."
}
}
200 data and meta envelope
{
"data": {
"unchanged": true,
"cursor": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
curl -X GET "https://platform.mattering.io/api/internal/v1/notifications/summary/?cursor=...&email=...&org_id=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: platform_app/notification_views.py (notification_views.internal_summary)
GET
v1/org-erasure/
Service tier
List v1. derived from route
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/org-erasure/
Responses
200 data and meta envelope
{
"data": {
"...": "..."
}
}
409 bare JSON object (no envelope)
...
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | missing_field |
| 500 | files_failed |
Example
curl -X GET "https://platform.mattering.io/api/internal/v1/org-erasure/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: platform_app/data_rights_views.py (data_rights_views.internal_org_erasure)
GET
v1/org-export/
Service tier
List v1. derived from route
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/org-export/
Responses
200 data and meta envelope
{
"data": {
"...": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | missing_field |
Example
curl -X GET "https://platform.mattering.io/api/internal/v1/org-export/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: platform_app/data_rights_views.py (data_rights_views.internal_org_export)
GET
v1/user-erasure/
Service tier
List v1. derived from route
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/user-erasure/
Responses
200 data and meta envelope
{
"data": {
"...": "..."
}
}
409 bare JSON object (no envelope)
...
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | missing_field |
| 500 | files_failed |
Example
curl -X GET "https://platform.mattering.io/api/internal/v1/user-erasure/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: platform_app/data_rights_views.py (data_rights_views.internal_user_erasure)
GET
v1/user-export/
Service tier
List v1. derived from route
URL
- Service tierhttps://platform.mattering.io/api/internal/v1/user-export/
Responses
200 data and meta envelope
{
"data": {
"...": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | missing_field |
Example
curl -X GET "https://platform.mattering.io/api/internal/v1/user-export/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: platform_app/data_rights_views.py (data_rights_views.internal_user_export)