---
title: "declare_storage_area"
description: "Generated reference for the management action declare_storage_area: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/declare-storage-area
order: 46
visibility: public
redirects_from: ["/reference/actions/declare-area","/reference/actions/undeclare-area","/reference/actions/undeclare-storage-area"]
---

# declare\_storage\_area

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/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](/cloud/concepts/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

```json
{
  "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

```json
{
  "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<br>Required fields: \["name"\] |
| /<wbr>properties/<wbr>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\.<br><br>Type: string<br>Pattern: ^\[a\-zA\-Z0\-9\]\[a\-zA\-Z0\-9\_\-\]\{0,63\}$ |
| /<wbr>properties/<wbr>account\_keyed | 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\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>version\_keeping | 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`\.<br><br>Type: boolean<br>Required value: false |
| /<wbr>properties/<wbr>application | Your application id from `list_applications`, required to declare, else `application_required`\. Fixed per area; use a new name for another application\.<br><br>Type: string |
| /<wbr>properties/<wbr>remove | 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\.<br><br>Type: boolean |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","area","outcome"\] |
| /<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>area | The area as declared; with `remove: true`, the declaration removed, as it was, or null where no area by the name was declared\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>outcome | `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\.<br><br>Type: string<br>Pattern: ^\(created\|unchanged\|removed\)$ |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "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](/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/)
