Topolo Docs Topolo Platform
Open workspace

Create document version

Create an immutable locale-specific version and update full-text retrieval.

Outcome

Create an immutable locale-specific version and update full-text retrieval.

These examples were captured from the local Worker. Deployment, publication and retrieval are verified separately for each environment; local examples do not establish external provider delivery.

Before you start

  • Inspect the credential identity with topolo whoami and the exact action with topolo actions get before preparing input.

  • Discover an accessible Docs workspace with topolo resources topolo-docs and topolo workspaces list topolo-docs. Pass workspace resource type and identifier separately from action input.

  • The published required permission is docs:write; the active credential and resource binding must authorize the call.

  • Validate and plan the exact request. Execute only after the intended effect has been authorized; --confirm is the transport guard, not a grant of permission.

Discover the target


topolo actions get app_topolo_docs.documents.versions.create --detail --json
topolo resources topolo-docs --json
topolo workspaces list topolo-docs --json
Discover documentId with app_topolo_docs.documents.list.

Input fields

FieldRequiredMeaning
documentIdYesStable document identifier discovered from documents.list, spaces.documents.list or owned_documents.list in the active credential context.
titleNoHuman-readable title. Native creation uses an Untitled space, Untitled document or Untitled section title when omitted. Updates preserve an omitted title; document versions snapshot their title.
summaryNoShort document summary, stored up to 2,000 characters. A new version snapshots it; public reads retain the explicitly published version summary.
bodyMarkdownYesComplete Markdown body for the new immutable version. This replaces the version body, not a patch. The repository stores up to one million characters.
localeNoLocale of the version to create; omitted creation locale defaults to en. Public machine reads accept only the locale of the explicitly published version.
sourceRevisionNoProvenance revision for the immutable version. Owned-document upsert requires an exact lowercase 40-character commit SHA when supplied; ordinary version creation stores the supplied provenance string.
sourcePathNoRepository path or other provenance path associated with the immutable version. It is recorded as evidence metadata rather than used to fetch content.

Interpret the response

version is the new or deduplicated immutable content and document carries its currentVersionId. Identical locale/title/summary/body content can reuse an existing version. Creating a version does not change the public published pointer. agentGuidance is the separately stored structured layer for that immutable version, or null when absent. Its owner review declaration is not automatic accuracy certification. Human-only version writes clear the layer; non-null guidance requires exact source provenance.

Worked examples

The following inputs and responses were captured from the local Docs worker fixture. Auth and Nexus dependencies are simulated. Identifiers, URLs and timestamps are illustrative fixture values. Discover your own identifiers and choose an appropriate test resource; copying a fixture identifier does not make it valid in your environment. For workspace-bound calls, set DOCS_WORKSPACE_ID to the identifier returned by resource discovery. Run validation and planning first; the final call requires the intended effect to be authorized.

Minimal example

Save the input as payload.json:


{
  "documentId": "doc_de0efe08-781e-4e60-9d7a-2a48b6dd4dd4",
  "title": "Rotate an integration token",
  "summary": "Safely replace an integration token.",
  "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
  "locale": "en"
}

CLI:


topolo actions validate app_topolo_docs.documents.versions.create --data @payload.json --json
topolo actions plan app_topolo_docs.documents.versions.create --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_docs.documents.versions.create --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:


{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_docs.documents.versions.create",
    "input": {
      "documentId": "doc_de0efe08-781e-4e60-9d7a-2a48b6dd4dd4",
      "title": "Rotate an integration token",
      "summary": "Safely replace an integration token.",
      "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
      "locale": "en"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 201:


{
  "version": {
    "id": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87",
    "organizationId": "org_fixture",
    "workspaceId": "ws_fixture",
    "documentId": "doc_de0efe08-781e-4e60-9d7a-2a48b6dd4dd4",
    "locale": "en",
    "title": "Rotate an integration token",
    "summary": "Safely replace an integration token.",
    "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
    "agentGuidance": null,
    "contentHash": "f14fd31c10cbbf734ad4677c8c68f7036d2f3625815ed61465ff8375acd5e0b6",
    "sourceRevision": null,
    "sourcePath": null,
    "createdByUserId": "usr_fixture",
    "createdAt": "2026-10-03T08:07:30.881Z"
  },
  "document": {
    "id": "doc_de0efe08-781e-4e60-9d7a-2a48b6dd4dd4",
    "organizationId": "org_fixture",
    "workspaceId": "ws_fixture",
    "spaceId": "docspace_a09c96df-e507-4751-89c8-e6a99e496d0d",
    "sectionId": "docsec_9c57d921-baf8-455c-89a0-5abb407cb339",
    "sectionPosition": 0,
    "parentId": null,
    "slug": "rotate-token",
    "title": "Rotate an integration token",
    "summary": "Safely replace an integration token.",
    "status": "review",
    "sourceKind": "native",
    "ownerAppId": null,
    "currentVersionId": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87",
    "publishedVersionId": null,
    "createdByUserId": "usr_fixture",
    "createdAt": "2026-10-03T08:07:30.565Z",
    "updatedAt": "2026-10-03T08:07:30.881Z",
    "publishedAt": null
  }
}

version is the new or deduplicated immutable content and document carries its currentVersionId. Identical locale/title/summary/body content can reuse an existing version. Creating a version does not change the public published pointer. agentGuidance is the separately stored structured layer for that immutable version, or null when absent. Its owner review declaration is not automatic accuracy certification. Human-only version writes clear the layer; non-null guidance requires exact source provenance.

Workflow example

Save the input as payload.json:


{
  "documentId": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
  "title": "Rotate an integration token",
  "summary": "Safely replace an integration token.",
  "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
  "locale": "en"
}

CLI:


topolo actions validate app_topolo_docs.documents.versions.create --data @payload.json --json
topolo actions plan app_topolo_docs.documents.versions.create --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_docs.documents.versions.create --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:


{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_docs.documents.versions.create",
    "input": {
      "documentId": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
      "title": "Rotate an integration token",
      "summary": "Safely replace an integration token.",
      "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
      "locale": "en"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 201:


{
  "version": {
    "id": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a",
    "organizationId": "org_fixture",
    "workspaceId": "ws_fixture",
    "documentId": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
    "locale": "en",
    "title": "Rotate an integration token",
    "summary": "Safely replace an integration token.",
    "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
    "agentGuidance": null,
    "contentHash": "f14fd31c10cbbf734ad4677c8c68f7036d2f3625815ed61465ff8375acd5e0b6",
    "sourceRevision": null,
    "sourcePath": null,
    "createdByUserId": "usr_fixture",
    "createdAt": "2026-10-03T08:07:34.265Z"
  },
  "document": {
    "id": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
    "organizationId": "org_fixture",
    "workspaceId": "ws_fixture",
    "spaceId": "docspace_a0013653-dabf-4831-8c11-6405b39664ca",
    "sectionId": "docsec_37f4c4e1-d416-47d7-ad57-d0a38fb678c4",
    "sectionPosition": 0,
    "parentId": null,
    "slug": "rotate-token",
    "title": "Rotate an integration token",
    "summary": "Safely replace an integration token.",
    "status": "review",
    "sourceKind": "native",
    "ownerAppId": null,
    "currentVersionId": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a",
    "publishedVersionId": null,
    "createdByUserId": "usr_fixture",
    "createdAt": "2026-10-03T08:07:34.003Z",
    "updatedAt": "2026-10-03T08:07:34.265Z",
    "publishedAt": null
  }
}

version is the new or deduplicated immutable content and document carries its currentVersionId. Identical locale/title/summary/body content can reuse an existing version. Creating a version does not change the public published pointer. agentGuidance is the separately stored structured layer for that immutable version, or null when absent. Its owner review declaration is not automatic accuracy certification. Human-only version writes clear the layer; non-null guidance requires exact source provenance.

Verify the result

  • Read $.version.id — you need it to publish this exact version.

  • Confirm the public document is unchanged; creating a version does not publish it.

Errors and recovery

  • HTTP 403 · organization_required: The token carries no organization scope. Re-authenticate against the organization that owns the Docs workspace and retry.

  • HTTP 400 · workspace_required: No Docs workspace resolved for the caller. Call workspace.get to see which workspace is bound, then retry in that context.

  • HTTP 403 · permission_denied: The credential needs docs:write on the selected Docs workspace.

  • HTTP 400 · invalid_json_object: The body was missing, malformed, or carried a key the action does not accept. Send a JSON object matching inputSchema exactly — these routes reject unknown keys.

  • HTTP 404 · not_found: No record in this workspace carries that id. List the resource first and use an id from the response.

Versions remain immutable. To restore authoring content, read the prior reviewed version and create a version with that content and locale. Creating a version does not change the published pointer; plan documents.publish separately only when a public content change is intended.

Evidence boundary

These examples establish local handler behavior and schema validity. They do not establish runtime permission parity, a deployed development/staging result or production completion. Preserve the actual request identifier and perform the verification reads after an authorized live call.