Topolo Docs Topolo Platform
Open workspace

List files

List one page of files and directories in the verified workspace; eligible files can have derived thumbnails generated during listing.

Outcome

List one page of files and directories in the verified workspace; eligible files can have derived thumbnails generated during listing.

Before you start

  • Verify identity, pin environment and organization, and discover a granted Bytes workspace before choosing file keys.
  • The action requires files:read. Select a verified workspace resource separately from action input; a body field cannot supply a workspace grant.
  • Scope org uses the verified workspace shared root; private uses the caller’s private subtree. The accepted legacy all value resolves to org and does not grant cross-organization browsing. The bucket input cannot switch the configured R2 binding.
  • Authorize the described effect or private-data export before passing CLI --confirm or MCP confirm:true. GET listing/search can persist derived data; HTTP method alone does not establish a read-only action.

Discover the target

topolo whoami --json
topolo actions get app_topolo_bytes.files.list --detail --json
topolo resources topolo-bytes --json
topolo workspaces list topolo-bytes --json
  • File keys are paths returned by files.list/search in the selected workspace and scope. Discover the granted workspace id; do not derive access from fixture ids.

Request

GET /api/list

Save action input as payload.json. The reviewed plan separates path identifiers, query fields and the HTTP body. Set BYTES_WORKSPACE_ID from granted resource discovery.

Inspect and test this action in the signed action console. A test response still requires the verification below.

Input fields

FieldRequiredTypeConstraints
prefixOptionalstring{}
cursorOptionalstring{}
fileTypeOptionalstring{}
sizeMinOptionalstring{}
sizeMaxOptionalstring{}
dateFromOptionalstring{}
dateToOptionalstring{}
durationMinOptionalstring{}
durationMaxOptionalstring{}
searchOptionalstring{}
sortByOptionalstring{}
sortOrderOptionalstring{}
bucketOptionalstring{"minLength":1}
scopeOptionalstring{"enum":["org","private","all"]}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "prefix": {
      "type": "string"
    },
    "cursor": {
      "type": "string"
    },
    "fileType": {
      "type": "string"
    },
    "sizeMin": {
      "type": "string"
    },
    "sizeMax": {
      "type": "string"
    },
    "dateFrom": {
      "type": "string"
    },
    "dateTo": {
      "type": "string"
    },
    "durationMin": {
      "type": "string"
    },
    "durationMax": {
      "type": "string"
    },
    "search": {
      "type": "string"
    },
    "sortBy": {
      "type": "string"
    },
    "sortOrder": {
      "type": "string"
    },
    "bucket": {
      "type": "string",
      "minLength": 1
    },
    "scope": {
      "type": "string",
      "enum": [
        "org",
        "private",
        "all"
      ]
    }
  },
  "additionalProperties": false
}

Effects

  • Reads R2 objects and can persist missing derived thumbnails. Signed thumbnail URLs carry temporary access; the listing does not grant another workspace.

Interpret the response

The response identifier path is $.files[].key for file. An empty list does not discover a target.

Follow next while truncated is true. Verify the listed keys and filters; totalFound is not proof of a complete inventory.

The schema describes supported success fields; optional metadata and integration-dependent values may vary. Errors have the exact shapes shown in refused examples.

Success schema:

{
  "type": "object",
  "required": [
    "dirs",
    "files",
    "next",
    "truncated",
    "totalFound",
    "appliedFilters"
  ],
  "properties": {
    "dirs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "key",
          "originalKey",
          "size",
          "uploaded",
          "etag",
          "url",
          "type",
          "thumb"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "originalKey": {
            "type": "string"
          },
          "size": {
            "type": "number"
          },
          "uploaded": {
            "type": "string"
          },
          "etag": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "thumb": {
            "type": "string"
          }
        }
      }
    },
    "next": {
      "type": "null"
    },
    "truncated": {
      "type": "boolean"
    },
    "totalFound": {
      "type": "number"
    },
    "appliedFilters": {
      "type": "object",
      "required": [
        "fileType",
        "sizeMin",
        "sizeMax",
        "dateFrom",
        "dateTo",
        "durationMin",
        "durationMax",
        "searchText",
        "sortBy",
        "sortOrder"
      ],
      "properties": {
        "fileType": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "sizeMin": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "sizeMax": {
          "type": "null"
        },
        "dateFrom": {
          "type": "null"
        },
        "dateTo": {
          "type": "null"
        },
        "durationMin": {
          "type": "null"
        },
        "durationMax": {
          "type": "null"
        },
        "searchText": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "string"
            }
          ]
        },
        "sortBy": {
          "type": "string"
        },
        "sortOrder": {
          "type": "string"
        }
      }
    }
  }
}

Worked examples

Actual exported Worker handlers with local Miniflare R2/KV. Auth, workspace grants, R2 multipart, notification, usage and semantic integrations are simulated at their configured test boundaries. Synthetic ids, timestamps and signed URLs confer no live access. No deployed provider outcome, external delivery or live grant is established. Upload-session credential values are explicitly redacted; binary responses use the tested SDK transport envelope. Replace synthetic identifiers through credential-scoped discovery. Refused scenarios document failure boundaries; they are not successful workflows.

Successful request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_bytes.files.list",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "dirs": [],
  "files": [],
  "next": null,
  "truncated": false,
  "totalFound": 0,
  "appliedFilters": {
    "fileType": null,
    "sizeMin": null,
    "sizeMax": null,
    "dateFrom": null,
    "dateTo": null,
    "durationMin": null,
    "durationMax": null,
    "searchText": null,
    "sortBy": "name",
    "sortOrder": "asc"
  }
}

HTTP 200. Follow next while truncated is true. Verify the listed keys and filters; totalFound is not proof of a complete inventory.

Another supported request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "search": "invoice"
}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_bytes.files.list",
    "input": {
      "search": "invoice"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "dirs": [],
  "files": [
    {
      "key": "invoice-2024.pdf",
      "originalKey": "invoice-2024.pdf",
      "size": 1,
      "uploaded": "2026-10-04T01:57:57.226Z",
      "etag": "8277e0910d750195b448797616e091ad",
      "url": "/download/invoice-2024.pdf?bucket=topolo-bytes-test&scope=org",
      "type": "pdf",
      "thumb": "/api/thumbnail/invoice-2024.pdf?bucket=topolo-bytes-test&scope=org"
    }
  ],
  "next": null,
  "truncated": false,
  "totalFound": 1,
  "appliedFilters": {
    "fileType": null,
    "sizeMin": null,
    "sizeMax": null,
    "dateFrom": null,
    "dateTo": null,
    "durationMin": null,
    "durationMax": null,
    "searchText": "invoice",
    "sortBy": "name",
    "sortOrder": "asc"
  }
}

HTTP 200. Follow next while truncated is true. Verify the listed keys and filters; totalFound is not proof of a complete inventory.

Another supported request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "fileType": "images"
}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_bytes.files.list",
    "input": {
      "fileType": "images"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "dirs": [],
  "files": [
    {
      "key": "a.png",
      "originalKey": "a.png",
      "size": 1,
      "uploaded": "2026-10-04T01:57:57.351Z",
      "etag": "c4ca4238a0b923820dcc509a6f75849b",
      "url": "/download/a.png?bucket=topolo-bytes-test&scope=org",
      "type": "image",
      "thumb": "https://bytes-api.test.local/api/signed-download?data=%7B%22key%22%3A%22organizations%2Forg_acme%2Fworkspaces%2Fworkspace_acme%2Fa.png%22%2C%22expiresAt%22%3A%222026-10-04T02%3A57%3A57.352Z%22%2C%22downloadFilename%22%3A%22a.png%22%7D&sig=48bd41bc87adbc70505baeb714b90d90ef84c62cc31ba0a75141a029990857d8"
    }
  ],
  "next": null,
  "truncated": false,
  "totalFound": 1,
  "appliedFilters": {
    "fileType": "images",
    "sizeMin": null,
    "sizeMax": null,
    "dateFrom": null,
    "dateTo": null,
    "durationMin": null,
    "durationMax": null,
    "searchText": null,
    "sortBy": "name",
    "sortOrder": "asc"
  }
}

HTTP 200. Follow next while truncated is true. Verify the listed keys and filters; totalFound is not proof of a complete inventory.

Refused request · HTTP 403

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "error": "workspace_forbidden"
}

HTTP 403. This request was refused; preserve the exact response and correct its cause before retrying.

Refused request · HTTP 403

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "error": "Forbidden",
  "message": "You do not have access to this folder"
}

HTTP 403. This request was refused; preserve the exact response and correct its cause before retrying.

Refused request · HTTP 401

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 401:

{
  "error": "No token"
}

HTTP 401. This request was refused; preserve the exact response and correct its cause before retrying.

Refused request · HTTP 403

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_bytes.files.list --data @payload.json --json
topolo actions plan app_topolo_bytes.files.list --resource-type workspace --resource-id "$BYTES_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

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

HTTP 403. This request was refused; preserve the exact response and correct its cause before retrying.

Verify the result

  • Follow next while truncated is true. Verify the listed keys and filters; totalFound is not proof of a complete inventory.

Errors and recovery

  • workspace_forbidden (HTTP 403): Verify the pinned organization, granted workspace resource and required application permission. Inspect the exact refusal before requesting narrower access; never switch scope to bypass the denial.
  • Forbidden (HTTP 403): Verify the pinned organization, granted workspace resource and required application permission. Inspect the exact refusal before requesting narrower access; never switch scope to bypass the denial.
  • No token (HTTP 401): Refresh the authorized credential in the same environment and organization. A failed authentication is not a successful handler effect.
  • action_permission_required (HTTP 403): Verify the pinned organization, granted workspace resource and required application permission. Inspect the exact refusal before requesting narrower access; never switch scope to bypass the denial.

Authentication, the action-input validator or resource middleware can refuse a request before this handler. Preserve the exact request id, error and selected credential context. The fixtures establish no live credentials or configured provider.

Recovery boundary

Listing may have created derived thumbnails; it provides no undo action for those derived objects.

Evidence

Actual exported Worker handlers with local Miniflare R2/KV. Auth, workspace grants, R2 multipart, notification, usage and semantic integrations are simulated at their configured test boundaries. Synthetic ids, timestamps and signed URLs confer no live access. No deployed provider outcome, external delivery or live grant is established. Upload-session credential values are explicitly redacted; binary responses use the tested SDK transport envelope. Capture digests and test scenarios are retained in the source fixture records.