Coming soon · Contract draft

Surveys, Reviews & Enablement

Planned

A participant-aware learning and feedback contract spanning surveys, reviews, assignments, quizzes, training, and readiness.

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

Survey, review, assignment, learning, skill, and readiness services

Contract posture

P3 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Commercial/Knowledge + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 6 · Knowledge and intake

Contract dependencies

• Canonical identity and provider mapping policy
• Field-level visibility rules
• Transactional event outbox

What this unlocks

Automate assignments

Read a stable domain model for surveys, reviews & enablement without depending on GUI routes or database shapes.

Collect participant-safe feedback

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

Track readiness outcomes

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

Lifecycle and invariants

Surveys, Reviews & Enablement exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftassignedin_progresscompletedpublishedexpired

From	To	Command	Authority
draft	assigned	Assign survey	Survey, learning, and readiness services
assigned	in_progress	Start response	Survey, learning, and readiness services
in_progress	completed	Complete response	Survey, learning, and readiness services
completed	published	Publish results	Survey, learning, and readiness services

Lifecycle invariants

• Participant tokens remain audience-bound capabilities.
• Raw answers follow explicit visibility policy.

Authority boundaries

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

DigitalStack owns

• Template and assignment lifecycle
• Response/result visibility policy
• Training and readiness state

Explicitly not building

• Share tokens as ordinary IDs
• Raw answers exposed beyond policy
• Agents completing training or reviews for people

Surface decisions

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

add

Templates, assignments, participant actions, responses, results, training, skills, and readiness

The API needs separate administrator and participant contracts.

keep

Participant-safe tokens outside ordinary resource IDs

Capability URLs preserve audience and scope boundaries.

remove

Raw-answer access through aggregate scopes and agents answering for people

Both undermine privacy and authenticity.

Interface plan

REST API

Planned

Versioned surveys, reviews & enablement resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable Survey 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 survey lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

LMS / Email / Slack / Teams 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 /surveys	survey(id: ID!): Survey	get_surveys_enablement	—	Survey, review, assignment, learning, skill, and readiness services
Primary command	POST /surveys	draftSurveyChange(input: DraftSurveyChangeInput!): SurveyChangeProposal!	draft_surveys_enablement_change	survey.created	Survey, review, assignment, learning, skill, and readiness services

Proposed scopes

Proposed scopes are not grantable yet.

surveys:readplanned scope

Read governed surveys, reviews & enablement resources.

surveys:writeplanned scope

Create and edit bounded surveys, reviews & enablement fields.

surveys:operateplanned scope

Run explicit surveys, reviews & enablement lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Survey, review, assignment, learning, skill, and readiness 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/surveys

List surveys, reviews & enablement

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

surveys:read

POST/api/v1/surveysconfirmation

Create Survey

Create one canonical resource with idempotency and actor attribution.

surveys:write

GET/api/v1/surveys/{id}

Retrieve Survey

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

surveys:read

PATCH/api/v1/surveys/{id}confirmation

Update Survey

Update bounded editable fields using optimistic versioning.

surveys:write

POST/api/v1/surveys/{id}/publish-resultsconfirmation

publish results Survey

Run one explicit domain command after validation and authorization.

surveys:operate

publish results a Survey

Planned request

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

Planned response

{
  "data": {
    "id": "survey_123",
    "status": "results_published",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

Survey

SurveyConnection

SurveyChangeProposal

Operation

Queries

survey(id: ID!): Survey

surveyList(filter: SurveyFilter, pagination: PaginationInput): SurveyConnection!

Mutations

draftSurveyChange(input: DraftSurveyChangeInput!): SurveyChangeProposal!

applySurveyChange(input: ApplySurveyChangeInput!): SurveyPayload!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Surveys, Reviews & Enablement

get_surveys_enablement

Planned

Read the authorized surveys, reviews & enablement state, provenance, and allowed actions.

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

Draft Surveys, Reviews & Enablement change

draft_surveys_enablement_change

Planned

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

Scope: surveys: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 Surveys, Reviews & Enablement change

apply_surveys_enablement_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: surveys: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 surveys, reviews & enablement change and help me apply it.

1. Call get_surveys_enablement to inspect current state, provenance, and allowed actions.
2. Call draft_surveys_enablement_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_surveys_enablement_change with the proposal version.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

survey.createdplanned event

A canonical Survey was created.

payload: survey_id, status, created_at

survey.updatedplanned event

Governed Survey fields changed.

payload: survey_id, changed_fields, version, occurred_at

survey.results_publishedplanned event

The publish results command completed.

payload: survey_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded surveys, reviews & enablement proposals through MCP.

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

LMS / Email / Slack / Teams

Action sink

Deliver assignments and collect narrowly scoped participant actions.

Authority: Participant identity, token audience, and result visibility remain governed by DigitalStack.

Open contract decisions

Resolve before implementation approval

• Which result aggregates require minimum cohort sizes for privacy?

Proof obligations

Must remain true	Failure indicator
Survey, review, assignment, learning, skill, and readiness 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.