Read one published documentation record

Outcome

Retrieve the explicitly published Markdown body and immutable citation metadata for one public document. Unpublished locales are unavailable.

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.

• Use an active public documentation space with an explicitly published document. Public retrieval never grants access to application mutations.

Discover the target

topolo actions get app_topolo_docs.public_machine.document --detail --json
Use the public space and document slugs in an existing public reader URL or a verified documents.publish result; discover published documents through public_machine.index.

Input fields

Interpret the response

bodyMarkdown is the exact explicitly published body. Retain url, documentId, versionId and contentHash when grounding an answer or plan. A requested unpublished locale returns not_found rather than draft content. 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:

{
  "spaceSlug": "reference-minimal",
  "documentSlug": "rotate-token",
  "locale": "en"
}

CLI:

topolo actions validate app_topolo_docs.public_machine.document --data @payload.json --json
topolo actions plan app_topolo_docs.public_machine.document --data @payload.json --json
topolo actions call app_topolo_docs.public_machine.document --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_docs.public_machine.document",
    "input": {
      "spaceSlug": "reference-minimal",
      "documentSlug": "rotate-token",
      "locale": "en"
    }
  }
}

Captured local response · HTTP 200:

{
  "formatVersion": 1,
  "url": "https://docs.test/s/reference-minimal/rotate-token",
  "markdownUrl": "https://docs.test/api/public/docs/reference-minimal/rotate-token/content.md",
  "documentId": "doc_de0efe08-781e-4e60-9d7a-2a48b6dd4dd4",
  "versionId": "docver_387e2601-28ef-4d73-8a60-ab3e37fdce87",
  "title": "Rotate an integration token",
  "summary": "Safely replace an integration token.",
  "locale": "en",
  "ownerAppId": null,
  "contentHash": "f14fd31c10cbbf734ad4677c8c68f7036d2f3625815ed61465ff8375acd5e0b6",
  "sourceRevision": null,
  "publishedAt": "2026-10-03T08:07:31.044Z",
  "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
  "agentGuidance": null
}

bodyMarkdown is the exact explicitly published body. Retain url, documentId, versionId and contentHash when grounding an answer or plan. A requested unpublished locale returns not_found rather than draft content. 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:

{
  "spaceSlug": "reference-workflow",
  "documentSlug": "rotate-token",
  "locale": "en"
}

CLI:

topolo actions validate app_topolo_docs.public_machine.document --data @payload.json --json
topolo actions plan app_topolo_docs.public_machine.document --data @payload.json --json
topolo actions call app_topolo_docs.public_machine.document --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_docs.public_machine.document",
    "input": {
      "spaceSlug": "reference-workflow",
      "documentSlug": "rotate-token",
      "locale": "en"
    }
  }
}

Captured local response · HTTP 200:

{
  "formatVersion": 1,
  "url": "https://docs.test/s/reference-workflow/rotate-token",
  "markdownUrl": "https://docs.test/api/public/docs/reference-workflow/rotate-token/content.md",
  "documentId": "doc_453b15f4-06fc-4366-ae42-adf1f10d9d38",
  "versionId": "docver_81f1572d-43ea-45fe-b0dd-0f550c94d80a",
  "title": "Rotate an integration token",
  "summary": "Safely replace an integration token.",
  "locale": "en",
  "ownerAppId": null,
  "contentHash": "f14fd31c10cbbf734ad4677c8c68f7036d2f3625815ed61465ff8375acd5e0b6",
  "sourceRevision": null,
  "publishedAt": "2026-10-03T08:07:34.384Z",
  "bodyMarkdown": "# Rotate a token\n\nOpen credential settings, replace the token and verify a read.",
  "agentGuidance": null
}

bodyMarkdown is the exact explicitly published body. Retain url, documentId, versionId and contentHash when grounding an answer or plan. A requested unpublished locale returns not_found rather than draft content. 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

• Retain url, versionId and contentHash with any answer or execution plan grounded in this document.

Errors and recovery

• HTTP 404 · not_found: Refresh public_machine.index and use its current document slug; request only the published locale.

Captured local refusal · HTTP 404

{
  "input": {
    "spaceSlug": "reference-minimal",
    "documentSlug": "rotate-token",
    "locale": "fr"
  },
  "response": {
    "error": "not_found"
  }
}

Captured local refusal · HTTP 404

{
  "input": {
    "spaceSlug": "reference-workflow",
    "documentSlug": "rotate-token",
    "locale": "fr"
  },
  "response": {
    "error": "not_found"
  }
}

This read does not modify documentation.

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.