declare_storage_area

{
  "name": "declare_storage_area",
  "resource": "area",
  "tier": "reversible",
  "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. An area holding no file is undeclared with undeclare_storage_area, which frees its name for a new area. A file is uploaded from a shell under a single-use grant that mint_upload_grant answers, with a ready command; in Windows PowerShell, Invoke-WebRequest needs -UseBasicParsing.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

{
  "name": "declare_storage_area",
  "tier": "reversible",
  "scenario": "OST-L0-01",
  "summary": "Declare a file-storage area before putting files in it. Three declarations are fixed at declaration and cannot change afterwards: whether files are keyed by end user, whether earlier versions are kept (version keeping is refused at this version), and the one application of your account the area binds to. The binding is required: every area belongs to one application. A matching `object_storage` entry in the manifest records the use and is not required: the area works with or without it.\n\nDeclare an area once, with this tool or with the Storage client's `mintArea` when the backend starts; doing both with the same values is safe, the second answering already declared. The backend's Storage client reaches the area's files over a transport it builds, which sends each call to the gateway origin with the application's platform credential, `TURNZERO_CLOUD_TOKEN`, as the bearer; the Store files guide's sample builds it.\n\nDeclaring the same area again with the same values answers as already declared; different values are refused. An area that holds no file can be undeclared with `undeclare_storage_area`, which frees the name for a new area under other declarations. To upload a file from a shell, call `mint_upload_grant` and run the command it answers; in Windows PowerShell, `Invoke-WebRequest` needs `-UseBasicParsing`.",
  "owners": [
    "STO-01",
    "OST-L0-01",
    "OST-L0-03",
    "OST-L0-08"
  ]
}

{
  "request": {
    "type": "object",
    "required": [
      "name",
      "account_keyed",
      "version_keeping",
      "application"
    ],
    "properties": {
      "name": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
        "description": "The area's name: a letter or digit first, then letters, digits, `-` or `_`, up to 64 characters. Stable for the area's life."
      },
      "account_keyed": {
        "type": "boolean",
        "description": "`true` declares that files are keyed by end user, each end user's files kept apart, `false` a shared area. The declaration is recorded and compared on redeclaration; at this version no route reads it — every area is partitioned to the calling account either way."
      },
      "version_keeping": {
        "type": "boolean",
        "const": false,
        "description": "Whether earlier versions of a file are kept. Only `false` is accepted at this version."
      },
      "application": {
        "type": "string",
        "description": "Required: the id of the one application of the acting account the area binds to, fixed at declaration. Every credential that reaches this action is the account’s own — a session or an account-scoped token — so the member is always required here. The call is refused 400 `application_required` without it. An area is never re-pointed, unbound, or re-bound, and an area wanted under another binding is a new area. `list_applications` answers the identifier."
      }
    }
  },
  "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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "area": {
        "type": "object"
      },
      "outcome": {
        "type": "string",
        "pattern": "^(created|unchanged)$",
        "description": "`created` where the area is new, `unchanged` where identical declarations were repeated."
      },
      "detail": {
        "type": "string"
      }
    }
  }
}