--- title: "read_storage_file" description: "Generated reference for the management action read_storage_file: its description, access metadata, payload contract, and registration status." slug: /reference/actions/read-storage-file order: 44 visibility: public redirects_from: [] --- # read\_storage\_file 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/read_storage_file`, 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_read_storage_file`. **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 Read the fields of one of your stored files: its size, content type, times, acting identity, and version, the value a metadata read returns as its ETag\. The content is never returned\. Pass `environment` to choose the partition, the application's deploy target where absent\. ## Access and action metadata ```json { "name": "read_storage_file", "resource": "environment", "tier": "observe", "surface": "tzcloud", "product": "cloud", "clients": [ "bearer", "browser_session" ], "listing": "admitted", "summary": "Read one stored file's fields in a declared area bound to the given application. `environment` selects the partition, by default the application's deploy target, where an upload with no environment writes. The fields are its name, size, content type, creation and last-write times, acting identity and version, the storage metadata read's ETag. No content is returned; download through the storage routes. An absent file refuses `no_such_file`, an undeclared area `undeclared_area`, and another application's or the platform's deploy area `area_scope_refused`.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true } } ``` ## MCP catalog entry ```json { "name": "read_storage_file", "title": "Read stored file details", "tier": "observe", "scenario": "OST-L0-02", "summary": "Read the fields of one of your stored files: its size, content type, times, acting identity, and version, the value a metadata read returns as its ETag. The content is never returned. Pass `environment` to choose the partition, the application's deploy target where absent.", "owners": [ "OST-L0-02", "OST-L0-03", "STO-04" ] } ``` ## request | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["application","area","name"\] | | /properties/application | The id of the application whose area holds the file, from `list_applications`\. The area must be bound to it\.

Type: string | | /properties/environment | The environment whose partition of the area holds the file; absent, the application's deploy target, where an upload naming none writes\.

Type: string
Pattern: ^\(development\|production\)$ | | /properties/area | The declared storage area holding the file; 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/name | The file's name within the area, verbatim, slashes included; a name holding a `.` or `..` segment is refused\.

Type: string
Minimum length: 1 | ## response | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["contract\_version","file"\] | | /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/file | The file's fields as the storage metadata read returns them, never its content; `version` is the read's ETag\.

Type: object
Required fields: \["name","area","size","content\_type","created\_at","last\_written\_at","actor","version"\] | | /properties/file/properties/name | Type: string | | /properties/file/properties/area | Type: string | | /properties/file/properties/size | Type: integer | | /properties/file/properties/content\_type | Type: string | | /properties/file/properties/created\_at | Type: string | | /properties/file/properties/last\_written\_at | Type: string | | /properties/file/properties/actor | Type: string | | /properties/file/properties/version | Type: string | | /properties/detail | Type: string | ## Complete payload contract ```json { "request": { "type": "object", "required": [ "application", "area", "name" ], "properties": { "application": { "type": "string", "description": "The id of the application whose area holds the file, from `list_applications`. The area must be bound to it." }, "environment": { "type": "string", "pattern": "^(development|production)$", "description": "The environment whose partition of the area holds the file; 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 holding the file; an area the account has not declared is refused `undeclared_area`, and one bound to another application `area_scope_refused`." }, "name": { "type": "string", "minLength": 1, "description": "The file's name within the area, verbatim, slashes included; a name holding a `.` or `..` segment is refused." } } }, "response": { "type": "object", "required": [ "contract_version", "file" ], "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." }, "file": { "type": "object", "description": "The file's fields as the storage metadata read returns them, never its content; `version` is the read's ETag.", "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" } } }, "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/)