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 PAT bearer token. Browser sign-in alone does not authenticate an external MCP client.

The linked schemas describe v0.1.2. Check the contract for the installed version before implementing requests. 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.1.2 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.

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.
2. Open your private edit with begin_context_edit, using the returned document version as its base.
3. For a partial body change, use patch_context_edit with a supported typed operation. For a complete body replacement or title, tags, aliases, or placement changes, use update_context_edit.
4. Use the edit's editing_version_id, current expected_editing_revision, and the required operation key from the contract. If the version or revision conflicts, inspect the latest result before retrying a changed request.
5. Inspect the edit in the browser. Submit that exact edit for review with submit_context_edit_for_review when it is ready, or use discard_context_edit to abandon it.

For a new page, use create_context_page and continue with the edit identifiers it returns. list_my_context_edits helps you find edits that are still open.

Saving an edit does not automatically submit it for review or publish it. Review, workspace publication, and publication to the web are separate steps. See Context pages and Review and history.

update_context_edit requires the full body_md, including when changing metadata. The Context editing tools do not provide a body-free metadata update or a citation-array write. A citation returned by cite is not automatically attached by an edit command. Check the schema and retained citations instead of assuming that those actions happened.

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. Have DTXWIKI_MCP_PAT available through your approved secrets setup. 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.

---

Version evidence: MCP tool registry, workspace guide input, workspace discovery input.