Publish document version

Publish one exact document version as an immutable public snapshot.

Outcome

Publish one exact document version as an immutable public snapshot.

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:publish; 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.publish --detail --json
topolo resources topolo-docs --json
topolo workspaces list topolo-docs --json
Discover documentId with app_topolo_docs.documents.list.
Use app_topolo_docs.documents.versions.list to select the exact immutable version.

Input fields

Field	Required	Meaning
`documentId`	Yes	Stable document identifier discovered from documents.list, spaces.documents.list or owned_documents.list in the active credential context.
`versionId`	No	Exact immutable version identifier for publication, from documents.versions.list. Omission publishes currentVersionId. The version must belong to the selected document.

Interpret the response

publication contains the space, document and exact version made public, plus publicationId and releaseNumber. publicUrl is the reader address. Compare version.id with the requested versionId and read the public machine record to verify the content hash.

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",
  "versionId": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87"
}

CLI:


topolo actions validate app_topolo_docs.documents.publish --data @payload.json --json
topolo actions plan app_topolo_docs.documents.publish --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_docs.documents.publish --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.publish",
    "input": {
      "documentId": "doc_de0efe08-781e-4e60-9d7a-2a48b6dd4dd4",
      "versionId": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:


{
  "publication": {
    "space": {
      "id": "docspace_a09c96df-e507-4751-89c8-e6a99e496d0d",
      "organizationId": "org_fixture",
      "workspaceId": "ws_fixture",
      "slug": "reference-minimal",
      "title": "minimal integration reference",
      "description": "Reference for rotating integration tokens.",
      "visibility": "public",
      "defaultLocale": "en",
      "brand": {},
      "status": "active",
      "createdByUserId": "usr_fixture",
      "createdAt": "2026-10-03T08:07:30.244Z",
      "updatedAt": "2026-10-03T08:07:30.369Z"
    },
    "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": "published",
      "sourceKind": "native",
      "ownerAppId": null,
      "currentVersionId": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87",
      "publishedVersionId": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87",
      "createdByUserId": "usr_fixture",
      "createdAt": "2026-10-03T08:07:30.565Z",
      "updatedAt": "2026-10-03T08:07:31.044Z",
      "publishedAt": "2026-10-03T08:07:31.044Z"
    },
    "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"
    },
    "publicationId": "docpub_facd0269-2658-47e8-ba62-04e47e44137e",
    "releaseNumber": 1
  },
  "publicUrl": "https://docs.test/s/reference-minimal/rotate-token"
}

Workflow example

Save the input as payload.json:


{
  "documentId": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
  "versionId": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a"
}

CLI:


topolo actions validate app_topolo_docs.documents.publish --data @payload.json --json
topolo actions plan app_topolo_docs.documents.publish --resource-type workspace --resource-id "$DOCS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_docs.documents.publish --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.publish",
    "input": {
      "documentId": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
      "versionId": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:


{
  "publication": {
    "space": {
      "id": "docspace_a0013653-dabf-4831-8c11-6405b39664ca",
      "organizationId": "org_fixture",
      "workspaceId": "ws_fixture",
      "slug": "reference-workflow",
      "title": "workflow integration reference",
      "description": "Reference for rotating integration tokens.",
      "visibility": "public",
      "defaultLocale": "en",
      "brand": {},
      "status": "active",
      "createdByUserId": "usr_fixture",
      "createdAt": "2026-10-03T08:07:33.740Z",
      "updatedAt": "2026-10-03T08:07:33.828Z"
    },
    "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": "published",
      "sourceKind": "native",
      "ownerAppId": null,
      "currentVersionId": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a",
      "publishedVersionId": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a",
      "createdByUserId": "usr_fixture",
      "createdAt": "2026-10-03T08:07:34.003Z",
      "updatedAt": "2026-10-03T08:07:34.384Z",
      "publishedAt": "2026-10-03T08:07:34.384Z"
    },
    "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"
    },
    "publicationId": "docpub_89042cce-4709-4833-a693-8cf681daa190",
    "releaseNumber": 1
  },
  "publicUrl": "https://docs.test/s/reference-workflow/rotate-token"
}

Verify the result

Confirm the published version id is the one you intended, not merely the newest.
Load the public document and confirm it shows the text you meant to expose.

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:publish 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.
HTTP 422 · document_not_publishable: The document has no publishable version, or the versionId you named does not belong to it. Call documents.versions.list and publish an id from that list.

Publish the previous version id to roll the public text back, or call documents.unpublish to remove it from public lookup entirely. Anything read while it was public is already out.

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.