---
title: "list_storage_files"
description: "Generated reference for the management action list_storage_files: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/list-storage-files
order: 43
visibility: public
redirects_from: []
---

# list\_storage\_files

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/list_storage_files`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `tzcloud_list_storage_files`.

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

List the files of a storage area bound to your application, one page at a time: each file's name, size, content type, times, acting identity, and version, never its content\. Pass `environment` to choose the partition, the application's deploy target where absent, `prefix` to narrow, and the answer's `cursor` for the next page\.

## Access and action metadata

```json
{
  "name": "list_storage_files",
  "resource": "environment",
  "tier": "observe",
  "surface": "tzcloud",
  "product": "cloud",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "listing": "admitted",
  "summary": "List one page of files in a declared storage area bound to the given application. `environment` selects the partition, by default the application's deploy target, where an upload with no environment writes; `prefix` keeps the files whose name starts with it.\n\nEach file gives its name, size, content type, creation and last-write times, acting identity and version, with no content. The storage listing's page bound applies. The action and the file listing route accept each other's cursors for the same listing. An undeclared area refuses `undeclared_area`, another application's or the platform's deploy area `area_scope_refused`, and a cursor for another listing `invalid_cursor`.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "list_storage_files",
  "title": "List stored files",
  "tier": "observe",
  "scenario": "OST-L0-02",
  "summary": "List the files of a storage area bound to your application, one page at a time: each file's name, size, content type, times, acting identity, and version, never its content. Pass `environment` to choose the partition, the application's deploy target where absent, `prefix` to narrow, and the answer's `cursor` for the next page.",
  "owners": [
    "OST-L0-02",
    "OST-L0-03",
    "OST-L0-04"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application","area"\] |
| /<wbr>properties/<wbr>application | The id of the application whose area is listed, from `list_applications`\. The area must be bound to it\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | The environment whose partition of the area is listed; absent, the application's deploy target, where an upload naming none writes\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>area | The declared storage area listed; an area the account has not declared is refused `undeclared_area`, and one bound to another application `area_scope_refused`\.<br><br>Type: string<br>Pattern: ^\[a\-zA\-Z0\-9\]\[a\-zA\-Z0\-9\_\-\]\{0,63\}$ |
| /<wbr>properties/<wbr>prefix | Lists only the files whose name starts with it; absent, the whole partition\.<br><br>Type: string |
| /<wbr>properties/<wbr>cursor | The `cursor` the previous page of this same listing returned, to read the next page; one from another area, environment, or prefix is refused `invalid_cursor`\.<br><br>Type: string |
| /<wbr>properties/<wbr>limit | The most files on this page, capped at the storage listing's configured page bound\. If omitted, that bound applies\.<br><br>Type: number |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","files"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>files | The page's files by name, each as the storage listing route returns it\.<br><br>Type: array |
| /<wbr>properties/<wbr>files/<wbr>items | Type: object<br>Required fields: \["name","area","size","content\_type","created\_at","last\_written\_at","actor","version"\] |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>name | Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>area | Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>size | Type: integer |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>content\_type | Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>created\_at | Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>last\_written\_at | Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>actor | Type: string |
| /<wbr>properties/<wbr>files/<wbr>items/<wbr>properties/<wbr>version | Type: string |
| /<wbr>properties/<wbr>cursor | Present where another page follows: pass it as `cursor` with the same area, environment, and prefix\.<br><br>Type: string |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application",
      "area"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The id of the application whose area is listed, from `list_applications`. The area must be bound to it."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "The environment whose partition of the area is listed; absent, the application's deploy target, where an upload naming none writes."
      },
      "area": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
        "description": "The declared storage area listed; an area the account has not declared is refused `undeclared_area`, and one bound to another application `area_scope_refused`."
      },
      "prefix": {
        "type": "string",
        "description": "Lists only the files whose name starts with it; absent, the whole partition."
      },
      "cursor": {
        "type": "string",
        "description": "The `cursor` the previous page of this same listing returned, to read the next page; one from another area, environment, or prefix is refused `invalid_cursor`."
      },
      "limit": {
        "type": "number",
        "description": "The most files on this page, capped at the storage listing's configured page bound. If omitted, that bound applies."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "files"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "files": {
        "type": "array",
        "description": "The page's files by name, each as the storage listing route returns it.",
        "items": {
          "type": "object",
          "required": [
            "name",
            "area",
            "size",
            "content_type",
            "created_at",
            "last_written_at",
            "actor",
            "version"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "area": {
              "type": "string"
            },
            "size": {
              "type": "integer"
            },
            "content_type": {
              "type": "string"
            },
            "created_at": {
              "type": "string"
            },
            "last_written_at": {
              "type": "string"
            },
            "actor": {
              "type": "string"
            },
            "version": {
              "type": "string"
            }
          }
        }
      },
      "cursor": {
        "type": "string",
        "description": "Present where another page follows: pass it as `cursor` with the same area, environment, and prefix."
      },
      "detail": {
        "type": "string"
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)