Coming soon · Contract draft

Wiki & Knowledge

Planned

A knowledge graph for pages, topics, blocks, versions, relationships, templates, connectors, and publication workflows.

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

Wiki page, version, relationship, template, and connector services

Contract posture

P2 · 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

Build a knowledge graph

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

Draft and publish pages

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

Synchronize trusted sources

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

Lifecycle and invariants

Wiki & Knowledge exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftreviewpublishedstalearchived

From	To	Command	Authority
draft	review	Request review	Wiki knowledge service
review	published	Publish page	Wiki knowledge service
published	stale	Mark stale	Wiki knowledge service
stale	archived	Archive page	Wiki knowledge service

Lifecycle invariants

• Connector content retains provenance.
• Agents cannot publish without confirmation.

Authority boundaries

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

DigitalStack owns

• Knowledge page and version identity
• Topic and relationship graph
• Template, publication, and connector lifecycle

Explicitly not building

• Agents publishing without review
• External wiki IDs replacing canonical identity
• Connector content bypassing provenance

Surface decisions

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

add

Page/topic/search/version/relationship/template/publish and connector resources

A knowledge API needs both graph structure and publication lifecycle.

keep

Draft and publish as separate tools

Generated knowledge remains reviewable before becoming shared truth.

remove

External wiki IDs as canonical IDs and automatic connector publication

Mappings and review protect identity and trust.

Interface plan

REST API

Planned

Versioned wiki & knowledge resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable KnowledgePage 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 knowledge page lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Confluence / Notion / Drive / SharePoint 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 /knowledge/pages	knowledgePage(id: ID!): KnowledgePage	get_wiki_knowledge	—	Wiki page, version, relationship, template, and connector services
Primary command	POST /knowledge/pages	draftKnowledgePageChange(input: DraftKnowledgePageChangeInput!): KnowledgePageChangeProposal!	draft_wiki_knowledge_change	knowledge_page.created	Wiki page, version, relationship, template, and connector services

Proposed scopes

Proposed scopes are not grantable yet.

knowledge:readplanned scope

Read governed wiki & knowledge resources.

knowledge:writeplanned scope

Create and edit bounded wiki & knowledge fields.

knowledge:operateplanned scope

Run explicit wiki & knowledge lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Wiki page, version, relationship, template, and connector 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/knowledge/pages

List wiki & knowledge

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

knowledge:read

POST/api/v1/knowledge/pagesconfirmation

Create KnowledgePage

Create one canonical resource with idempotency and actor attribution.

knowledge:write

GET/api/v1/knowledge/pages/{id}

Retrieve KnowledgePage

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

knowledge:read

PATCH/api/v1/knowledge/pages/{id}confirmation

Update KnowledgePage

Update bounded editable fields using optimistic versioning.

knowledge:write

POST/api/v1/knowledge/pages/{id}/publishconfirmation

publish KnowledgePage

Run one explicit domain command after validation and authorization.

knowledge:operate

publish a KnowledgePage

Planned request

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

Planned response

{
  "data": {
    "id": "knowledge_page_123",
    "status": "published",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

KnowledgePage

KnowledgePageConnection

KnowledgePageChangeProposal

Operation

Queries

knowledgePage(id: ID!): KnowledgePage

knowledgePageList(filter: KnowledgePageFilter, pagination: PaginationInput): KnowledgePageConnection!

Mutations

draftKnowledgePageChange(input: DraftKnowledgePageChangeInput!): KnowledgePageChangeProposal!

applyKnowledgePageChange(input: ApplyKnowledgePageChangeInput!): KnowledgePagePayload!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Wiki & Knowledge

get_wiki_knowledge

Planned

Read the authorized wiki & knowledge state, provenance, and allowed actions.

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

Draft Wiki & Knowledge change

draft_wiki_knowledge_change

Planned

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

Scope: knowledge: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 Wiki & Knowledge change

apply_wiki_knowledge_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: knowledge: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 wiki & knowledge change and help me apply it.

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

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

knowledge_page.createdplanned event

A canonical KnowledgePage was created.

payload: knowledge_page_id, status, created_at

knowledge_page.updatedplanned event

Governed KnowledgePage fields changed.

payload: knowledge_page_id, changed_fields, version, occurred_at

knowledge_page.publishedplanned event

The publish command completed.

payload: knowledge_page_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded wiki & knowledge proposals through MCP.

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

Confluence / Notion / Drive / SharePoint

Synchronization provider

Import or publish knowledge with version and provenance mapping.

Authority: Direction, conflict policy, and publication authority are explicit.

Open contract decisions

Resolve before implementation approval

• How should conflicting edits be reconciled for bidirectional knowledge connectors?

Proof obligations

Must remain true	Failure indicator
Wiki page, version, relationship, template, and connector 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.