API and MCP reference

This page is for people building integrations or writing instructions for an AI client. For ordinary browser use, start with your first workspace. To connect an existing AI app, use Connect an AI app.

Choose the interface

Your task	Interface	Contract
Let an AI client discover and use dtxWiki tools	Authenticated Streamable HTTP at /mcp	MCP input and output schemas
Build an application or script that calls HTTP resources	REST under /api/v1	REST OpenAPI schema

Both interfaces use the running dtxWiki server and its access controls. Use HTTPS for a remote server. MCP accepts a PAT or dtxWiki OAuth bearer token; REST accepts a browser session cookie or a PAT/OAuth JWT bearer token where that operation permits bearer authentication. Browser sign-in alone does not authenticate an external MCP client. Some REST operations accept only the browser session, for example access-key management and the server-administrator attachment operations; each operation’s security entry in the OpenAPI schema lists what it accepts.

The linked schemas describe dtxWiki v0.2.1. Check the contract for the installed version before implementing requests; 0.2 integration changes lists what changed. Creating a credential does not grant extra workspace membership or override its scopes and allowed-workspace list.

Start an MCP task in the right workspace

1. Call list_my_workspaces to discover the workspaces this connection can access.
2. Select the intended workspace's ID, then call guide with that workspace_id. Read the returned workflow and policy instructions.
3. Supply the chosen workspace_id in subsequent workspace tool calls. Use search to locate relevant material and fetch or read to inspect it.
4. Read the result and its warnings before continuing. A title match or partial response is not the same as reading the full evidence.

The workspace ID is a UUID, not its display name or URL slug. Keep it associated with the correct server and task rather than guessing it from another installation.

For example, after connecting your AI app, ask:

Use list_my_workspaces to find the Product Launch workspace. Call guide with its ID, then search for our launch checklist and read the relevant evidence. Explain the outstanding tasks with sources. Do not change any pages.

This is an example instruction for the connected client, not a command to paste into your terminal. The app still needs to execute the tools and use the returned material.

Find the tool for the job

The v0.2.1 registry contains 29 tools. Your connection's tools/list response determines the tools available to it; scopes and other access checks can limit the result.

Task	Tools
Discover and read	list_my_workspaces, guide, search, fetch, grep_wiki, what_changed, read, get_index, read_concept, read_context_outline, read_structure_map, list_changes
Edit Context	create_context_page, begin_context_edit, update_context_edit, submit_context_edit_for_review, discard_context_edit, patch_context_edit, list_my_context_edits, upload_image, cite, submit_feedback
Work with Agent instructions	list_agent_categories, read_agent_page, write_agent_page_draft, build_agent_input_bundle
Review and maintenance	list_requested_changes, submit_revision_for_review, wiki_maintenance

Use the schema for each tool to check required fields and response structure. A tool's presence does not mean every operation is permitted in every workspace or page state. Start with read access and validate the result in the browser before granting writes.

The tool contract is revision 29. The server reports it in serverInfo.version, which has the form <app version>+llmwiki.mcp.v1.tools.29.<digest>. To notice a contract change, compare the whole string or its tools.<N> part instead of ordering versions, and refresh tools/list when it changes.

The browser's Settings → Labs choices do not affect MCP tools or the REST API. Someone checking an Agent page draft written through MCP can open it from a copied /workspaces/<workspace_id>/agent/pages/<page_id> link even while their Agent menu is hidden, or turn on Show Agent menu; see Agent pages.

An image uploaded with upload_image becomes an unused file when no version of its page references it and no open edit holds it. Background cleanup reclaims an unused file once it is older than the workspace's retention period, counted from upload: 7 days by default, and an Owner can change or turn this off in Settings → Attachments.

Make a reviewable Context edit

For an existing page, follow this sequence in a practice workspace first:

1. Read the current page and its structure with read_structure_map; use read_context_outline when you need heading or section detail. fetch, Context reads and begin_context_edit expose the visible version's references.
2. Call begin_context_edit and keep its returned version_id, editing_revision and content_hash. This MCP editing session is author-private; it differs from browser Save draft, which makes a draft visible to the workspace's Editors and Owners.
3. Use patch_context_edit for a supported partial-body operation, or update_context_edit for a complete body replacement or metadata change. Pass version_id, the current editing_revision as expected_editing_revision, and an idempotency_key.
4. Search and read the documents used as evidence, then call cite to register them in that open edit before submitting. After any write, use the returned editing_revision for the next command; a reference-only change can advance it too.
5. Read back the exact version's body and references and inspect the result in the browser. Call submit_context_edit_for_review once the task is ready, or discard_context_edit to abandon it. Check the returned review/publication state.

For a new page, use create_context_page and continue with its returned identifiers. list_my_context_edits finds edits that are still open. On a stale-version or revision conflict, read the latest state before retrying a changed request. Reuse an idempotency key for a retry of the same command, not for a different edit. In Chats, expected_editing_revision appears as Overwrite protection number under Raw request details.

Saving an MCP edit, submitting a review, publishing to the workspace and publishing to the web are separate operations. A submitted draft can become visible to authorized Editors without being available to Viewers. See Context pages and Review and history.

update_context_edit requires the full body_md, including metadata-only updates. The final body, including managed frontmatter, must stay within 1,000,000 characters. Use the dedicated cite command for reference registration rather than adding an unsupported citation array to an ordinary edit request.

Register references with cite

In revision 29, cite is Register references: it writes the selected Context, Library or Agent document IDs into your own open Context edit. Use search and read/fetch to choose documents first. The credential needs draft-write (included by the UI's Write permission), and the caller needs the appropriate workspace role. A read-only credential cannot register references.

Input	How to supply it
workspace_id, page_id	Explicit workspace UUID and the Context page UUID or supported stable URL.
version_id, expected_editing_revision	The open edit and its current revision returned by the last read/write. A published or submitted version is not an open edit.
idempotency_key	A unique command key; retain it for an uncertain retry of that same request. retry_only is available for checking an existing command without initiating a new one.
add	Selected {target_kind, target_id, note?} entries. Kinds are context_page, library_item, agent_page; target_id is the document UUID, not its version. Notes have a 2,000-character limit.
remove	A {target_kind, target_id} pair, or a source-owned reference_id from the reference metadata.
conversation_token	Echo the token for this MCP task, or use new when deliberately starting a chat.

Supply at least one add/remove entry. A command accepts at most 500 entries combined, with no duplicate target in either list and no target both added and removed. The page's combined in-text and registered bibliography supports at most 500 distinct targets.

The result returns version_id, editing_revision, references_hash, added/removed/unchanged registrations and a receipt. It changes reference metadata without publishing the page or inserting a body marker. Insert an address-based @cite{...} in the body when you need an in-text citation; the editor's reference picker does this in browser workflows. Removing a registration does not remove remaining in-text citations; inspect remaining_inline_occurrences and the body.

The old claim-search inputs to cite are no longer accepted. Refresh tool schemas and replace that workflow with search/read followed by cite registration. Published graph citation relationships change only when the source version is published.

Input limits

dtxWiki rejects input that breaks a limit; it never shortens it. Lengths count characters (Unicode code points) unless the table says bytes. An MCP tool returns a tool error with the code validation_failed and retryable: false. REST returns HTTP 422 with error_code validation_failed, which the browser shows as “Some submitted information is invalid.” The schemas publish these limits, including the extensions x-normalized-maxLength and x-final-maxLength.

Input	Limit
Page and Agent page titles	Up to 256, on one line; spaces at either end are removed first
Page and Agent page bodies (body_md, body_markdown)	Up to 1,000,000 for the final stored Markdown, including managed frontmatter
tags and aliases	Up to 32 each; each tag 1–48, each alias 1–80
reason, patch_description, risk_notes, other note fields, suggested_action	Up to 2,000
nav_summary; workspace goal	Up to 160; up to 512
patch_context_edit operations	Up to 20 operations per request; the final body must still fit the body limit
submit_feedback body	Up to 10,000
References	500 distinct targets per page across inline citations and registrations; 500 add/remove entries combined per cite request
build_agent_input_bundle	requested_categories: up to 4 of agent_guide, persona, skill, memory; context_refs and library_artifact_refs: up to 128 each
Folder, Chats and workspace titles (REST)	Up to 80, 120 and 128; workspace slug up to 80
Ask question (REST)	Up to 8,000 after trimming
Search query (REST)	Up to 2,048
Inline comment note (REST)	Up to 5,000; selected anchor_text up to 2,000, context_before and context_after up to 500 each
Access key name; custom AI app display name	1–128 on one line; up to 160
Workspaces per access key or OAuth approval	Up to 256
Account email, display name and new password (REST)	Email up to 254 bytes, with up to 64 bytes before @; display name 1–32; new password 8–128

Follow paginated structure results

Large documents may need several calls. Do not treat the first response as the whole document.

Tool	How to continue
read_structure_map	Follow next_cursor. Check block and table-row omission information; document.block_count counts blocks in the whole document.
read_context_outline	Pass the returned outline_next_cursor as the next request's outline_cursor to continue the heading list. Its separate cursor pages the selected section body.

The outline and section cursors serve different purposes. Keep each cursor with the tool, workspace, document, and request it belongs to.

Make a read-only REST check

Create a PAT with the intended workspace access through MCP access settings. Prepare DTXWIKI_MCP_PAT using your approved secrets setup or the step-by-step environment variable guide, then run the check below from that terminal. Do not put a literal token in a shared script or terminal history.

This Bash example lists the workspaces the credential can access. Replace the example server URL with your own:

DTXWIKI_API='https://wiki.example.com/api/v1'
printf 'Authorization: Bearer %s\n' "$DTXWIKI_MCP_PAT" |
  curl --fail-with-body --silent --show-error \
    --header @- "$DTXWIKI_API/workspaces"

The header is supplied through standard input. The returned workspace information may be private; redact it before sharing a diagnostic report. A successful list request validates that request, not a write workflow or a native AI client's connection.

Workspace resources use the workspace UUID in their path, for example /api/v1/workspaces/{workspace_id}/context/pages. Use the OpenAPI schema for methods, request bodies, authentication, pagination, and errors. REST errors include error_code, message, request_id, and warnings; retain the request ID when asking an operator to investigate, without sharing credentials or private content. Input over a limit returns HTTP 422 with validation_failed; see Input limits.

Upgrade an integration from v0.1

dtxWiki v0.2.1 uses contract revision 29. Re-read tools/list and refresh generated input/output schemas whenever the complete serverInfo.version changes.

Contract surface	Required change
Workspace selection	Every workspace-scoped tool and dynamic prompt requires an explicit workspace_id. Missing/malformed tool targets return the tool-error envelope without creating a trace or chat. list_my_workspaces remains target-free. Never use an ambient selected workspace.
Discovery	personal_workspace_id and member is_personal_anchor_owner are removed. Use returned default_workspace_id or current_workspace_id as discovery hints, then explicitly select the intended UUID.
Context identity	Read, search and review results use workspace-qualified stable_url and link_markdown instead of concept_path and resource_uri. Pass the page UUID or /p/<workspace_id>/<page_id>; a legacy /p/<page_id> input is accepted only within the explicit tool workspace. Browser links copied for sharing should include both IDs.
Index navigation	Use exact dtxwiki://index/<kind>/<id> destinations in the explicit workspace. Folder refs go to get_index.node; Context/Library refs go to read_concept.path. Other page tools require their documented UUID or browser link. Normal exports retain lookup paths.
Guide	detail_level="brief" is the default. normal adds taxonomies, prompts/resources, policy and tools; detailed adds full field guidance (full is an alias). Removed placement_parent_candidates and active_agent_pages are replaced by get_index(format="nodes") and list_agent_categories. Check can_have_children before selecting a parent. Large workspaces route to search/index rather than an oversized whole-workspace bundle.
Edit responses	create_context_page, update_context_edit, patch_context_edit and submit_context_edit_for_review return compact IDs, hashes, state, review information and edit_receipt, without body_md. Read the returned version_id for the stored body; my_edit only names an edit still open. begin_context_edit still returns the body.
Receipts and diagnostics	edit_receipt.changes replaces first_change and may be bounded with omission counts. Inspect body_adjusted, server_fixes, lint_report and applied findings. Agent draft writes add normalization_report for exact index refs. An advisory context_page_has_no_graph_visible_links on a successful submission is guidance, not failure or proof of an edge.
Result envelope	Use result_status, request_id, conversation_token, optional warnings/review ID and failure fields. envelope.meta and result_summary are removed. Empty declared defaults may be omitted; decode absent fields using their schema defaults. Nullable edit_receipt.changes, edit_receipt.body_adjusted and envelope.retryable remain explicit because null means unknown. Protocol _meta also carries com.dtxwiki/requestId.
Pending edits	Within the same MCP chat, begin_context_edit can reopen that chat's own still-pending submission with the same version ID and withdraw its earlier review. The next submit replaces the review. Other chats/authors or already-decided versions branch normally. Keep one edit per task and submit once when ready.
References (revision 29)	cite replaces candidate search with real reference registration on an open edit. Context reads and fetch/begin_context_edit include references; publication combines registered and address-based inline references and updates citation graph relationships.
Publication feed	what_changed describes published-head movements. unpublished has null version_id; invalidate by page_id. created can republish or restore a page and should be an upsert. previous_version_id is the previously published head, not necessarily the candidate's parent. Respect permission-filtered metadata.

The earlier input bounds still apply. A stale-base conflict can take precedence over invalid-body validation: refresh the base before retrying. Restores, copied versions, submit and publish preserve historical bytes; authored saves and published Lint maintenance have their own documented normalization rules.

REST additions and compatibility

Use the pinned OpenAPI schema for the precise request and authorization contract:

Operation	Purpose
GET /api/v1/workspaces/{workspace_id}/graph/capability	Inspect workspace-map availability and management capability.
POST …/graph/query, POST …/graph/overview/query	Query bounded actor-visible local graph and workspace-map scenes. A response is not a complete audit/history export.
POST …/context/pages/{page_id}/references	Add/remove references on the caller's open edit; requires Editor access and draft-write for bearer credentials, with version_id, expected_editing_revision, idempotency_key and at most 500 combined entries.
POST …/graph/citations/evidence/query	Read retained evidence for a selected citation pair. Pass source_page_id, target_kind, target_id, optional cursor and limit (1–50, default 20); ordinary content-read access applies. Follow next_cursor even if a window has no visible items.
GET /api/v1/workspaces/{workspace_id}/inbox, GET /api/v1/users/me/inbox	List notices for the current user and scope. Corresponding POST …/marks applies marks to the observed revision.
POST …/reviews/{review_item_id}/decisions/{decision_id}/undo	Guarded Context decision undo through a browser session; unavailable/changed results can return 409.
POST /api/v1/admin/deployment/update-check	Administrator update lookup; does not install packages.

Workspace screens carry the workspace UUID in their route. The workspace-less page-location API is removed; choose the workspace before requesting content. Context page responses include the selected version's references and references_hash. When a browser session publishes a mutable editing version, pass that read hash as expected_references_hash along with expected_content_hash. Frozen submitted versions already bind their references. If a hash or revision changed, read the current version before deciding how to continue.

Search's general all scope excludes feedback and changes; explicit scopes remain available to authorized callers. Browser Agent filtering follows Labs, while API/MCP callers use the relevant schema and permission checks. Never infer access from a local browser preference.

Account SSO is separate from MCP OAuth authorization. A linked sign-in provider neither replaces a PAT nor adds credential scopes. Access Key workspace changes apply to existing Streamable HTTP sessions on the next request. Reload catalogs on contract change, not merely after reconnecting the transport.

---

Version evidence: MCP tool registry, tool contract revision, workspace guide input, workspace discovery input, input limits, MCP validation errors, OAuth registration limits, readiness check, account input policy, activity feed contract, activity endpoints and access, reference commands, reference registration service, citation evidence query, publish hash checks.