Topolo Docs Topolo Platform
Open workspace

List Compose documents

List up to 200 documents created by the authenticated user in the selected authorized workspace, optionally including archived records. The read can initialize the local workspace mirror.

Outcome

List up to 200 documents created by the authenticated user in the selected authorized workspace, optionally including archived records. The 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.list --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

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

FieldRequiredTypeConstraints
limitOptionalinteger{"minimum":1,"maximum":200}
includeArchivedOptionalstring{"enum":["0","1","true","false"]}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "includeArchived": {
      "type": "string",
      "enum": [
        "0",
        "1",
        "true",
        "false"
      ]
    }
  },
  "additionalProperties": false
}

Effects

  • Ensures a local mirror exists for the platform-authorized workspace.
  • Reads only documents created by the authenticated user in this workspace, newest updated first.
  • Defaults to 50 results and has no cursor/offset continuation; limit is capped at 200. includeArchived accepts 1, true, 0 or false as strings.

Interpret the response

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

Inspect documents[].id, archivedAt and updatedAt; an empty result does not discover a target. Do not infer complete workspace inventory from the limit or from this creator-filtered list; organization export has a separate privacy permission and wider boundary.

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": [
    "documents"
  ],
  "properties": {
    "documents": {
      "type": "array",
      "items": {
        "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": {
            "type": "null"
          },
          "audience": {
            "type": "string",
            "maxLength": 0
          },
          "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": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              }
            ]
          },
          "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 > documents are isolated per workspace: workspace A never sees workspace B's document.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_compose.documents.list --data @payload.json --json
topolo actions plan app_topolo_compose.documents.list --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.list --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.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "documents": [
    {
      "id": "0de350e6-f71c-48c4-a906-66244ce07848",
      "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.245Z",
      "updatedAt": "2026-10-04T02:26:27.245Z"
    }
  ]
}

HTTP 200. Inspect documents[].id, archivedAt and updatedAt; an empty result does not discover a target. Do not infer complete workspace inventory from the limit or from this creator-filtered list; organization export has a separate privacy permission and wider boundary.

Another supported 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: document CRUD > list honours includeArchived and limit.

Input · payload.json:

{
  "includeArchived": "1"
}

CLI:

topolo actions validate app_topolo_compose.documents.list --data @payload.json --json
topolo actions plan app_topolo_compose.documents.list --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.list --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.list",
    "input": {
      "includeArchived": "1"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "documents": [
    {
      "id": "dfbf6606-0e88-4863-83df-9e63f24d99c2",
      "title": "Keep",
      "type": "general",
      "style": null,
      "audience": "",
      "markdown": "# Keep",
      "sourceMaterial": null,
      "generationContract": null,
      "provider": null,
      "model": null,
      "approvalStatus": "draft",
      "approvalOwner": null,
      "approvalDueAt": null,
      "approvalNotes": null,
      "archivedAt": "2026-10-04T02:26:27.269Z",
      "createdByUserId": "user_test_1",
      "createdByEmail": "writer@stg.topolo.us",
      "createdAt": "2026-10-04T02:26:27.269Z",
      "updatedAt": "2026-10-04T02:26:27.269Z"
    }
  ]
}

HTTP 200. Inspect documents[].id, archivedAt and updatedAt; an empty result does not discover a target. Do not infer complete workspace inventory from the limit or from this creator-filtered list; organization export has a separate privacy permission and wider boundary.

Another supported 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: document CRUD > list honours includeArchived and limit.

Input · payload.json:

{
  "includeArchived": "true"
}

CLI:

topolo actions validate app_topolo_compose.documents.list --data @payload.json --json
topolo actions plan app_topolo_compose.documents.list --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.list --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.list",
    "input": {
      "includeArchived": "true"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "documents": [
    {
      "id": "dfbf6606-0e88-4863-83df-9e63f24d99c2",
      "title": "Keep",
      "type": "general",
      "style": null,
      "audience": "",
      "markdown": "# Keep",
      "sourceMaterial": null,
      "generationContract": null,
      "provider": null,
      "model": null,
      "approvalStatus": "draft",
      "approvalOwner": null,
      "approvalDueAt": null,
      "approvalNotes": null,
      "archivedAt": "2026-10-04T02:26:27.269Z",
      "createdByUserId": "user_test_1",
      "createdByEmail": "writer@stg.topolo.us",
      "createdAt": "2026-10-04T02:26:27.269Z",
      "updatedAt": "2026-10-04T02:26:27.269Z"
    }
  ]
}

HTTP 200. Inspect documents[].id, archivedAt and updatedAt; an empty result does not discover a target. Do not infer complete workspace inventory from the limit or from this creator-filtered list; organization export has a separate privacy permission and wider boundary.

Another supported 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: a document listing initializes only the authorized local workspace mirror.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_compose.documents.list --data @payload.json --json
topolo actions plan app_topolo_compose.documents.list --resource-type workspace --resource-id "$COMPOSE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_compose.documents.list --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.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "documents": []
}

HTTP 200. Inspect documents[].id, archivedAt and updatedAt; an empty result does not discover a target. Do not infer complete workspace inventory from the limit or from this creator-filtered list; organization export has a separate privacy permission and wider boundary.

Refused request · HTTP 403

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: auth failure paths > organization-less auth is forbidden from org routes.

Input · payload.json:

{}

CLI:

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

Captured local response · HTTP 403:

{
  "error": "organization_required"
}

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

Refused request · HTTP 403

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: auth failure paths > insufficient permission is forbidden.

Input · payload.json:

{}

CLI:

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

Captured local response · HTTP 403:

{
  "success": false,
  "error": {
    "code": "action_permission_required",
    "message": "Action \"documents.list\" requires permission \"workspace:read\".",
    "action": "documents.list"
  }
}

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

Refused request · HTTP 401

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 scoping > a workspace the key holds no binding for is refused, with no fallback.

Input · payload.json:

{}

CLI:

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

Captured local response · HTTP 401:

{
  "error": "API key validation failed"
}

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

Refused request · HTTP 400

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 scoping > a request naming no workspace at all is refused, not defaulted.

Input · payload.json:

{}

CLI:

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

Captured local response · HTTP 400:

{
  "error": "workspace_required"
}

HTTP 400. 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

  • Inspect documents[].id, archivedAt and updatedAt; an empty result does not discover a target.
  • Do not infer complete workspace inventory from the limit or from this creator-filtered list; organization export has a separate privacy permission and wider boundary.

Errors and recovery

  • organization_required (HTTP 403): Verify the authenticated organization, application permission and granted workspace. For reviewer_required, use the legitimately assigned reviewer; requesting review grants no access.
  • action_permission_required (HTTP 403): Verify the authenticated organization, application permission and granted workspace. For reviewer_required, use the legitimately assigned reviewer; requesting review grants no access.
  • API key validation failed (HTTP 401): Refresh the authorized credential in the same environment and pinned organization; do not switch scope to bypass this refusal.
  • workspace_required (HTTP 400): Correct the exact discovered input fields; refused fixtures are not successful requests.

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

Listing changes no document content. Local mirror initialization does not have a published removal action other than empty-workspace archival, which is a separate authorized operation.

  • 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.
  • Export Compose organization data: Export Compose-owned documents, versions, comments, review requests, export attempts and workspace mirrors across the authenticated organization. This private-data export requires privacy:read and explicit authorization.

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.