declare_storage_area #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/declare_storage_area, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_declare_storage_area.
OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).
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 #
Declare a file-storage area before uploading, or remove an empty one with remove: true. Its application, whether files are keyed by end user, and version keeping cannot change. Different declarations are refused differing_redeclaration.
A matching manifest object_storage entry records its use but is optional. Its areas list declares them on submission, needing neither this tool nor mintArea. Otherwise declare with this tool or the Storage client's mintArea at backend start. Repeating identical values is safe and changes nothing.
Then upload with mint_upload_grant and its command. With no shell, get the page's address from read_status's dashboard, passing brief: false. Ask your user to sign in there and use Upload a file. To remove, pass only remove: true and name. Files in either environment cause area_not_empty. Otherwise removal frees the name.
More about this action #
The backend's Storage client reaches the area's files over a transport it builds. The transport sends each call to the gateway origin, with the application's platform credential, TURNZERO_CLOUD_APP_TOKEN, as the bearer. The Store files guide's sample builds it.
The manifest's object_storage entry may record the area. That entry may instead list the area in areas, and each submission then declares it for that application, so neither this tool nor mintArea is needed.
Declaring the same area again with the same values changes nothing and returns outcome: unchanged; different values are refused. An area that contains no file can be removed with remove: true, which frees the name for a new area with other declarations. To upload a file from a shell, call mint_upload_grant and run the command it returns. In Windows PowerShell, Invoke-WebRequest needs -UseBasicParsing.
The application argument: required to declare, because every area belongs to one of your applications. Only the account's own credentials reach this action, a session or a token scoped to the whole account, so you always pass it. Without it, a declaration is refused 400 application_required. An area's application cannot change: an area for another application is a new area.
The account_keyed argument: required to declare, either true or false. A declaration without it is refused 400 invalid_request. The value cannot change on redeclaration. Files are not yet separated by end user, so your backend checks who may read each file. Leave it out with remove: true.
The version_keeping argument: required to declare, false alone. A declaration without it is refused 400 invalid_request. Asking to keep earlier versions is refused version_keeping_unsupported. Leave it out with remove: true.
The remove argument: with true, the call takes name alone, and account_keyed, version_keeping, or application beside it is refused invalid_request. An area with a file in either environment's partition is refused area_not_empty: delete its files first through the storage routes, or keep the area. For a name you have not declared, the call returns the outcome unchanged. A later declaration under a freed name is a new area and may have different values.
With no shell, ask your user to use Upload a file on the application's page. Removing an area that still holds files needs a client able to delete them over the storage routes; this call and the Upload a file page cannot empty it. Otherwise keep the area.
Access and action metadata #
{
"name": "declare_storage_area",
"resource": "area",
"tier": "reversible",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"summary": "Declare or re-declare a storage area: the three minting declarations — whether files are keyed by end user, whether earlier versions are kept, and the one application of the account the area binds to, required under the account's own credential — idempotent on identical declarations, refused on differing ones; versionKeeping true refuses at v0. The manifest's `object_storage` entry may instead list the area in `areas`, and each submission then declares it for that application, so neither this action nor `mintArea` is needed. With `remove: true` and `name` alone, an area holding no file in either environment partition is undeclared, which frees its name for a new area; an area holding a file refuses `area_not_empty`, and an absent name returns `unchanged`. A file is uploaded from a shell under a single-use grant that mint_upload_grant returns, with a ready command; in Windows PowerShell, Invoke-WebRequest needs -UseBasicParsing.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "declare_storage_area",
"title": "Add or remove storage area",
"tier": "reversible",
"scenario": "OST-L0-01",
"summary": "Declare a file-storage area before uploading, or remove an empty one with `remove: true`. Its application, whether files are keyed by end user, and version keeping cannot change. Different declarations are refused `differing_redeclaration`.\n\nA matching manifest `object_storage` entry records its use but is optional. Its `areas` list declares them on submission, needing neither this tool nor `mintArea`. Otherwise declare with this tool or the Storage client's `mintArea` at backend start. Repeating identical values is safe and changes nothing.\n\nThen upload with `mint_upload_grant` and its command. With no shell, get the page's address from `read_status`'s `dashboard`, passing `brief: false`. Ask your user to sign in there and use Upload a file. To remove, pass only `remove: true` and `name`. Files in either environment cause `area_not_empty`. Otherwise removal frees the name.",
"owners": [
"STO-01",
"OST-L0-01",
"OST-L0-03",
"OST-L0-08"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["name"] |
| / |
Area name: a letter or digit, then letters, digits, - or _, at most 64 characters. The export- and deploy- prefixes, from request_export and deploy, and images-<application id> are reserved (area_name_reserved). Stable for the area's life.Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$ |
| / |
Required to declare: true or false; without it a declaration is refused 400 invalid_request. Leave it out with remove: true. The platform records the value and compares it on redeclaration. It does not yet separate files by end user, so your backend checks who may read each file.Type: boolean |
| / |
Required to declare: whether earlier versions of a file are kept, false alone at this version. Without it a declaration is refused 400 invalid_request. Leave it out with remove: true.Type: boolean Required value: false |
| / |
Your application id from list_applications, required to declare, else application_required. Fixed per area; use a new name for another application.Type: string |
| / |
Pass true, with name alone, to remove the area: it must hold no file in either environment, and its name is then free. Absent or false, the call declares.Type: boolean |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","area","outcome"] |
| / |
Required value: 1 |
| / |
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}$ |
| / |
The area as declared; with remove: true, the declaration removed, as it was, or null where no area by the name was declared.Type: ["object","null"] |
| / |
created where the area is new, unchanged where identical declarations were repeated or, with remove: true, where no area by the name was declared; removed where the declaration was removed and the name freed.Type: string Pattern: ^(created|unchanged|removed)$ |
| / |
Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "Area name: a letter or digit, then letters, digits, `-` or `_`, at most 64 characters. The `export-` and `deploy-` prefixes, from `request_export` and `deploy`, and `images-<application id>` are reserved (`area_name_reserved`). Stable for the area's life."
},
"account_keyed": {
"type": "boolean",
"description": "Required to declare: `true` or `false`; without it a declaration is refused 400 `invalid_request`. Leave it out with `remove: true`. The platform records the value and compares it on redeclaration. It does not yet separate files by end user, so your backend checks who may read each file."
},
"version_keeping": {
"type": "boolean",
"const": false,
"description": "Required to declare: whether earlier versions of a file are kept, `false` alone at this version. Without it a declaration is refused 400 `invalid_request`. Leave it out with `remove: true`."
},
"application": {
"type": "string",
"description": "Your application id from `list_applications`, required to declare, else `application_required`. Fixed per area; use a new name for another application."
},
"remove": {
"type": "boolean",
"description": "Pass `true`, with `name` alone, to remove the area: it must hold no file in either environment, and its name is then free. Absent or `false`, the call declares."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"area",
"outcome"
],
"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."
},
"area": {
"type": [
"object",
"null"
],
"description": "The area as declared; with `remove: true`, the declaration removed, as it was, or null where no area by the name was declared."
},
"outcome": {
"type": "string",
"pattern": "^(created|unchanged|removed)$",
"description": "`created` where the area is new, `unchanged` where identical declarations were repeated or, with `remove: true`, where no area by the name was declared; `removed` where the declaration was removed and the name freed."
},
"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