Get Compose document

Read one document in the authorized organization and workspace, including current markdown, provenance, approval metadata and archival state. This read can initialize the local workspace mirror.

Outcome

Read one document in the authorized organization and workspace, including current markdown, provenance, approval metadata and archival state. This read can initialize the local workspace mirror.

Before you start

Verify the authenticated identity, environment and pinned organization before preparing an action.
The published application permission is workspace:read. Discover and select a granted Compose workspace separately from action input. A supplied identifier does not grant access.
Document reads require a read workspace grant; mirror initialization does not confer new access.
Authorize the documented effects or private-data export before CLI --confirm or MCP confirm:true. HTTP method alone does not establish a read-only operation.

Discover the target

topolo whoami --json
topolo actions get app_topolo_compose.documents.get --detail --json
topolo resources topolo-compose --json
topolo workspaces list topolo-compose --json

Select the granted workspace id as COMPOSE_WORKSPACE_ID. Use document and version ids returned by accessible reads; fixture ids confer no live access.

Request

GET /api/documents/{documentId}

Save action input as payload.json. Inspect the plan for the exact path, query and body. Set COMPOSE_WORKSPACE_ID from granted resource discovery.

Inspect and test this action in the signed action console, then perform the verification below.

Input fields

Field	Required	Type	Constraints
`documentId`	Required	string	{"minLength":1}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "documentId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "documentId"
  ],
  "additionalProperties": false
}

Effects

Ensures the local authorized workspace mirror exists.
Returns a document only when its identifier belongs to the selected organization and workspace.
Returns archived documents by identifier; unlike documents.list, this read is not restricted to the creator filter.

Interpret the response

Use response path $.document.id for compose_document. An empty list does not discover a target.

Expect HTTP 200 and compare document.id to the discovered target. Inspect markdown, approvalStatus, archivedAt and updatedAt. Approval metadata alone is not proof of a review decision or signed agreement.

The success schema below was checked against captured handler responses. Optional structured generation metadata and integration-dependent values can vary. Error examples retain their actual refusal shapes.

Success schema:

{
  "type": "object",
  "required": [
    "document"
  ],
  "properties": {
    "document": {
      "type": "object",
      "required": [
        "id",
        "title",
        "type",
        "style",
        "audience",
        "markdown",
        "sourceMaterial",
        "generationContract",
        "provider",
        "model",
        "approvalStatus",
        "approvalOwner",
        "approvalDueAt",
        "approvalNotes",
        "archivedAt",
        "createdByUserId",
        "createdByEmail",
        "createdAt",
        "updatedAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "style": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "audience": {
          "type": "string"
        },
        "markdown": {
          "type": "string"
        },
        "sourceMaterial": {
          "type": "null"
        },
        "generationContract": {
          "type": "null"
        },
        "provider": {
          "type": "null"
        },
        "model": {
          "type": "null"
        },
        "approvalStatus": {
          "type": "string"
        },
        "approvalOwner": {
          "type": "null"
        },
        "approvalDueAt": {
          "type": "null"
        },
        "approvalNotes": {
          "type": "null"
        },
        "archivedAt": {
          "type": "null"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdByEmail": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      }
    }
  }
}

Worked examples

Responses were captured from the actual Compose Worker using synthetic users, organizations, content and identifiers. Tests simulate Auth, Nexus, Notify, metering and platform workspace transport and use an in-memory D1 adapter or local SQLite. They prove local handler behavior, not live model correctness, provider cost, notification delivery, real workspace grants or cross-store atomicity. HTTP 204 responses are exactly empty strings in the SDK transport. Replace fixture identifiers through credential-scoped discovery. Refused examples demonstrate boundaries and must not be executed as successful workflows.

Successful request

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: compose workspace data isolation > a cross-workspace mutation (PATCH/DELETE) fails closed with 404.

Input · payload.json:

{
  "documentId": "ac3e2f43-0367-41aa-b862-584e02aa5f9f"
}

CLI:

topolo actions validate app_topolo_compose.documents.get --data @payload.json --json
topolo actions plan app_topolo_compose.documents.get --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.get --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_compose.documents.get",
    "input": {
      "documentId": "ac3e2f43-0367-41aa-b862-584e02aa5f9f"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "document": {
    "id": "ac3e2f43-0367-41aa-b862-584e02aa5f9f",
    "title": "Alpha Brief",
    "type": "general",
    "style": null,
    "audience": "",
    "markdown": "# Alpha Brief",
    "sourceMaterial": null,
    "generationContract": null,
    "provider": null,
    "model": null,
    "approvalStatus": "draft",
    "approvalOwner": null,
    "approvalDueAt": null,
    "approvalNotes": null,
    "archivedAt": null,
    "createdByUserId": "user_test_1",
    "createdByEmail": "writer@stg.topolo.us",
    "createdAt": "2026-10-04T02:26:27.250Z",
    "updatedAt": "2026-10-04T02:26:27.250Z"
  }
}

HTTP 200. Expect HTTP 200 and compare document.id to the discovered target. Inspect markdown, approvalStatus, archivedAt and updatedAt. Approval metadata alone is not proof of a review decision or signed agreement.

Another supported request

Input · payload.json:

{
  "documentId": "3603bac7-838e-41db-ad5a-1385228c6926"
}

CLI:

topolo actions validate app_topolo_compose.documents.get --data @payload.json --json
topolo actions plan app_topolo_compose.documents.get --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.get --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_compose.documents.get",
    "input": {
      "documentId": "3603bac7-838e-41db-ad5a-1385228c6926"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "document": {
    "id": "3603bac7-838e-41db-ad5a-1385228c6926",
    "title": "Policy",
    "type": "policy",
    "style": "legal",
    "audience": "staff",
    "markdown": "# Policy\n\nText",
    "sourceMaterial": null,
    "generationContract": null,
    "provider": null,
    "model": null,
    "approvalStatus": "draft",
    "approvalOwner": null,
    "approvalDueAt": null,
    "approvalNotes": null,
    "archivedAt": null,
    "createdByUserId": "user_test_1",
    "createdByEmail": "writer@stg.topolo.us",
    "createdAt": "2026-10-04T02:26:27.251Z",
    "updatedAt": "2026-10-04T02:26:27.251Z"
  }
}

Refused request · HTTP 404

Actual Compose Worker response. Auth, Nexus, notifications, metering and platform workspace transport are simulated. D1 is an in-memory adapter or local SQLite as stated by the test. This does not prove a live model completion or notification delivery. No request credentials are captured. Captured scenario: compose workspace data isolation > documents are isolated per workspace: workspace A never sees workspace B's document.

Input · payload.json:

{
  "documentId": "0de350e6-f71c-48c4-a906-66244ce07848"
}

CLI:

topolo actions validate app_topolo_compose.documents.get --data @payload.json --json
topolo actions plan app_topolo_compose.documents.get --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 404:

{
  "error": "not_found"
}

HTTP 404. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.

Verify the result

Expect HTTP 200 and compare document.id to the discovered target.
Inspect markdown, approvalStatus, archivedAt and updatedAt. Approval metadata alone is not proof of a review decision or signed agreement.

Errors and recovery

not_found (HTTP 404): Discover the accessible document and version in the selected workspace. A missing or inaccessible id is not permission to create a replacement.

Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.

Recovery boundary

No document content is changed by this read. Discover the correct accessible identifier and context after a 404; do not create a replacement to bypass isolation.

List saved Compose document versions: Read the 25 newest saved snapshots of an accessible document. This read can initialize the local workspace mirror and exposes no continuation cursor.
Update Compose document: Update one document from supplied fields. Omitted values retain existing state; the operation creates no version snapshot, and approval fields do not complete the review workflow.

Evidence

Responses were captured from the actual Compose Worker using synthetic users, organizations, content and identifiers. Tests simulate Auth, Nexus, Notify, metering and platform workspace transport and use an in-memory D1 adapter or local SQLite. They prove local handler behavior, not live model correctness, provider cost, notification delivery, real workspace grants or cross-store atomicity. HTTP 204 responses are exactly empty strings in the SDK transport. Replace fixture identifiers through credential-scoped discovery. Capture digests and test scenarios are retained in the source fixture records.

Get Compose document

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked examples

Successful request

Another supported request

Refused request · HTTP 404

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence