Coming soon · Contract draft

Notifications & Messaging

Planned

A user-centered inbox and messaging contract for notification lifecycle, participant-safe conversations, and scoped recent-change summaries.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Notification and participant messaging domain services

Contract posture

P2 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Platform + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 2 · Personal and stakeholder workflows

Contract dependencies

• Principal × scope grantability matrix
• Versioned interface catalog
• Transactional audit and event contracts

What this unlocks

Build a governed inbox

Read a stable domain model for notifications & messaging without depending on GUI routes or database shapes.

Route actionable messages

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Summarize recent change

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Notifications & Messaging exposes a bounded lifecycle with explicit commands and named authority at every transition.

unreadreadacknowledgeddismissed

From	To	Command	Authority
unread	read	Read notification	Notification and participant messaging services
read	acknowledged	Acknowledge action	Notification and participant messaging services
acknowledged	dismissed	Dismiss notification	Notification and participant messaging services

Lifecycle invariants

• Inbox reads are self or participant scoped.
• Audit history is not repackaged as employee surveillance.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• Notification identity and read state
• Conversation participant authorization
• Channel and delivery preferences

Explicitly not building

• Bulk employee surveillance
• Unscoped audit-log access
• Leaking private participant threads

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Personal inbox, message-thread, acknowledgement, and preference reads

Consumer apps need a bounded way to surface actionable DigitalStack communication.

keep

Audit log and personal notifications as separate contracts

An inbox should not inherit account-wide surveillance authority.

remove

Generic notification creation/update APIs and bulk message surveillance

Domain services create notifications; external callers should not impersonate system emitters.

Interface plan

REST API

Planned

Versioned notifications & messaging resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable Notification reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and confirmed apply tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense notification lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Slack / Teams / Email plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /notifications	notification(id: ID!): Notification	get_notifications_messaging	—	Notification and participant messaging domain services
Primary command	POST /notifications/{id}/acknowledge	draftNotificationChange(input: DraftNotificationChangeInput!): NotificationChangeProposal!	draft_notifications_messaging_change	notification.created	Notification and participant messaging domain services

Proposed scopes

Proposed scopes are not grantable yet.

notifications:readplanned scope

Read governed notifications & messaging resources.

notifications:writeplanned scope

Create and edit bounded notifications & messaging fields.

notifications:operateplanned scope

Run explicit notifications & messaging lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Notification and participant messaging domain services; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/notifications

List notifications & messaging

Return an authorized, paginated collection with stable filters and provenance.

notifications:read

GET/api/v1/notifications/{id}

Retrieve Notification

Return canonical detail, lifecycle state, permissions, and allowed actions.

notifications:read

POST/api/v1/notifications/{id}/acknowledgeconfirmation

acknowledge Notification

Run one explicit domain command after validation and authorization.

notifications:operate

GET/api/v1/messages

List my message threads

Return participant-authorized threads and unread state.

notifications:read

Execution: Synchronous

GET/api/v1/notifications/preferences

Get notification preferences

Return the caller’s channel and delivery preferences.

notifications:read

Execution: Synchronous

acknowledge a Notification

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/notifications/notification_123/acknowledge \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: notifications-messaging-acknowledge-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "notification_123",
    "status": "acknowledged",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

Notification

NotificationConnection

NotificationChangeProposal

Operation

Queries

notification(id: ID!): Notification

notificationList(filter: NotificationFilter, pagination: PaginationInput): NotificationConnection!

Mutations

draftNotificationChange(input: DraftNotificationChangeInput!): NotificationChangeProposal!

applyNotificationChange(input: ApplyNotificationChangeInput!): NotificationPayload!

Planned GraphQL query

query NotificationDetail($id: ID!) {
  notification(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Notifications & Messaging

get_notifications_messaging

Planned

Read the authorized notifications & messaging state, provenance, and allowed actions.

Scope: notifications:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Draft Notifications & Messaging change

draft_notifications_messaging_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: notifications:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Apply Notifications & Messaging change

apply_notifications_messaging_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: notifications:operate
Input: Proposal id, expected version, idempotency key, and explicit confirmation.
Output: Updated canonical resource and audit reference.
Write boundary: Confirmation, optimistic versioning, and idempotency required.

Planned agent workflow

User: Review the proposed notifications & messaging change and help me apply it.

1. Call get_notifications_messaging to inspect current state, provenance, and allowed actions.
2. Call draft_notifications_messaging_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. After explicit confirmation, call apply_notifications_messaging_change with the proposal version.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

notification.createdplanned event

A canonical Notification was created.

payload: notification_id, status, created_at

notification.updatedplanned event

Governed Notification fields changed.

payload: notification_id, changed_fields, version, occurred_at

notification.acknowledgedplanned event

The acknowledge command completed.

payload: notification_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "notification.acknowledged",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "notification",
    "id": "notification_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "notification_id": "notification_123",
    "prior_status": "draft",
    "status": "acknowledged"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded notifications & messaging proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Slack / Teams / Email

Action sink

Deliver notifications and narrowly scoped replies.

Authority: External channel actions pass through the same identity, permission, and audit checks.

Open contract decisions

Resolve before implementation approval

• Should external action sinks be allowed to dismiss notifications or only acknowledge them?

Proof obligations

Must remain true	Failure indicator
Notification and participant messaging domain services remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.