list_storage_files #

On this page

Generated automatically from the published 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 #

{
  "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 #

{
  "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 Required fields: ["application","area"]
/properties/application	The id of the application whose area is listed, from `list_applications`. The area must be bound to it. Type: string
/properties/environment	The environment whose partition of the area is listed; absent, the application's deploy target, where an upload naming none writes. Type: string Pattern: ^(development\|production)$
/properties/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`. Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$
/properties/prefix	Lists only the files whose name starts with it; absent, the whole partition. Type: string
/properties/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`. Type: string
/properties/limit	The most files on this page, capped at the storage listing's configured page bound. If omitted, that bound applies. Type: number

response #

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["contract_version","files"]
/properties/contract_version	Required value: 1
/properties/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. Type: string Pattern: ^[0-9a-f]{10}$
/properties/files	The page's files by name, each as the storage listing route returns it. Type: array
/properties/files/items	Type: object Required fields: ["name","area","size","content_type","created_at","last_written_at","actor","version"]
/properties/files/items/properties/name	Type: string
/properties/files/items/properties/area	Type: string
/properties/files/items/properties/size	Type: integer
/properties/files/items/properties/content_type	Type: string
/properties/files/items/properties/created_at	Type: string
/properties/files/items/properties/last_written_at	Type: string
/properties/files/items/properties/actor	Type: string
/properties/files/items/properties/version	Type: string
/properties/cursor	Present where another page follows: pass it as `cursor` with the same area, environment, and prefix. Type: string
/properties/detail	Type: string

Complete payload contract #

{
  "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: every refusal, by surface, with its cause and its remedy
schemas/wire_error.schema.json
schemas/wire_errors.json
schemas/action_payloads.json (includes shared shapes)
management_api_contract.md