request_export #

View this page as Markdown

On this page

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/request_export, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_request_export.

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 #

Export an application's database and stored files. Use export_account for declarations. Pass application, and the environment defaults to production. Read read_export until completed, then pass download: true and export. Run one returned command for your system outside the application's folder. Use your account's credential or an application-bounded token in a session or job. The application's platform credential cannot start or download.

More about this action #

Starting an export creates its area if needed. Starts return 202, an id and running; repeats while running return it. Tables are CSV from one repeatable-read transaction. Stored files are listed with version tags; the deploy area is excluded. A new export replaces earlier ended exports' files for this application and environment: download those first. Export files count in the application's stored data until deleted.

Download a completed export: mint a short-lived, read-only grant and get the one command that downloads every file under it, so no long-lived token is needed. Pass the application and the export's id from request_export. You may also pass local_path, a folder outside the application's folder; without it, the command writes a new folder where it runs, and refuses to run in an application's folder. The answer gives command_npx, or command_npx_windows for Windows, plus the installed forms command and command_windows. Run it once, as given: it writes the manifest and every file the manifest lists, and a second run resumes where the first stopped.

The grant expires after five minutes by default. A running or failed export is refused export_not_completed. For running, read it with read_export until completed; for failed, follow the outcome's next act in read_export. One whose files no longer exist is refused not_found. For either form, use your account's credential or a token bounded to this application, in a session or job. The application's platform credential cannot start an export or request its download grant.

Until the grant expires, it reads, by name, the export's own files and the application's stored files in the export's environment created by the time the export listed them. A file deleted and stored again after the export reads as absent, and the command counts it as failed. A file first stored after the export is in no manifest, so the command does not read it. A fresh export has the application's files as they are now. The grant lists nothing and writes nothing, and a read does not use it up.

The command line passes local_path as its --path, with ./ before a path that opens with a hyphen. The platform never reads the path. A path with a character that deploy_command refuses in its own local_path is refused invalid_request. So is ~, or a path that opens with ~/ or ~\, which no shell expands in double quotes.

Access and action metadata #

{
  "name": "request_export",
  "resource": "application",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Export one application's data from one environment: every table of its database written as one CSV file, all tables read under one repeatable-read transaction. A manifest lists each file of the application's other storage areas with its version tag. The platform's deploy area is left out: its one pending zip per environment is no customer file, and it is deleted within a day. The files are written into the application's export area, `export-<application id>`, which the platform mints bound to the application. Returns 202 at once with the export id and the state `running`; `next`, the `read_export` call, reads its progress and then the manifest. A request while an export of the same application and environment runs returns that export. `request_export` with `download: true` returns the command that downloads a completed export's files, which count in the application's stored data until you delete them. `application` is required; `environment` is production if omitted. With `download: true` it returns the download line: Mint a download grant for one completed export of the named application: a short-lived, read-only bearer credential, expiring after the configured lifetime, five minutes by default. It reads, by `GET` of a named file, the export's own files in the export area and the application's stored files in the export's environment that were created by the time the export listed them, the platform's deploy area excepted. A file stored after the export, or deleted and stored again, reads as an absent name does. A fresh export has the application's files as they are now. Where the export recorded no instant for its stored files, the grant reads the export's own files alone, and `detail` says so. It lists nothing, every other route refuses it, and a read does not spend it. It is admitted to the credentials `read_export` admits for that application, and the application's platform credential is refused.\n\nThe answer carries the export, its environment, the grant's expiry, and four command forms. `command_npx` downloads the export with turnzero's `export download`; `command_npx_windows` is its Windows form. `command` and `command_windows` use the installed turnzero command. The grant is returned inside those four lines alone. An optional `local_path` is the folder the command writes into. An export that is running or failed is refused `export_not_completed`, and one whose files no longer exist `not_found`.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}

MCP catalog entry #

{
  "name": "request_export",
  "title": "Request data export",
  "tier": "reversible",
  "scenario": "API-L0-18",
  "summary": "Export an application's database and stored files. Use `export_account` for declarations. Pass `application`, and the environment defaults to production. Read `read_export` until `completed`, then pass `download: true` and `export`. Run one returned command for your system outside the application's folder. Use your account's credential or an application-bounded token in a session or job. The application's platform credential cannot start or download.",
  "owners": [
    "API-L0-18",
    "API-L0-23",
    "MAPI-21",
    "OST-L0-01",
    "OST-L0-08",
    "OST-L0-03",
    "API-L0-17",
    "SEC-L0-07"
  ]
}

request #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["application"]
/properties/application The id of the application whose database and files the export reads, one of your account's; list_applications returns it.

Type: string
/properties/environment Export environment, default production; omit beside download: true, which takes its environment from the export.

Type: string
Allowed values: ["development","production"]
/properties/download true returns the line that downloads a completed export's files, naming export, in place of starting an export. An application's platform credential is refused it.

Type: boolean
/properties/export The export's id, from request_export. The export must be completed: a running or failed one is refused export_not_completed, and an id the application does not hold, or an export whose files no longer exist, is refused 404 not_found.

Type: string
/properties/local_path Optional: the folder on your machine for the export, absolute or relative to where the line runs. Absent, the line writes export-<export id> where it runs, refused if that folder holds package.json. A path outside the pattern, ~, or one opening ~/ or ~\ is refused invalid_request.

Type: string
Minimum length: 1
Maximum length: 1024
Pattern: ^(?:[^"$`%!&\|<>^\u201c-\u201e\u0000-\u001f\u007f\\]|\\[^"$`%!&\|<>^\u201c-\u201e\u0000-\u001f\u007f\\])+$

response #

JSON pointer Description and constraints
"" (root) Returns 202 at once, before the pass starts writing, on deploy's shape: the export's row was written running and the pass continues after the answer; next, the read_export call, reads its end.

Type: object
Required fields: ["contract_version","export","application","environment"]
/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/export The export's id, the one read_export takes.

Type: string
/properties/application Type: string
/properties/environment Type: string
Allowed values: ["development","production"]
/properties/state running at the answer, which precedes the work; a repeat returns the export already running.

Type: string
Allowed values: ["running"]
/properties/area The export area the files are written into, export-<application id>.

Type: string
/properties/folder The folder under the area that holds this export's files, <export id>/.

Type: string
/properties/requested_at Type: string
/properties/repeated true where an export of the same application and environment was already running and this call returns it; no second export started.

Type: boolean
/properties/next The exact read_export call that reads the export to its end, for the application and the export.

Type: object
Required fields: ["action","arguments"]
Additional properties: false
/properties/next/properties/action Required value: read_export
/properties/next/properties/arguments Type: object
Required fields: ["application","export"]
Additional properties: false
/properties/next/properties/arguments/properties/application Type: string
/properties/next/properties/arguments/properties/export Type: string
/properties/detail Says which line runs where and by when and the folder it writes. Where the export recorded an instant for its stored files, it says what the grant in the line reads: the export's own files and the application's stored files created by the time its export listed them. That form also says that a read does not spend the grant and that a fresh call returns another line once the grant expires. Where the export recorded none, it says that the line downloads the export's own files alone and that each stored file the manifest lists reads as absent and counts as failed. That form then says that a fresh export has the application's stored files as they are now, and gives the two calls that make one.

Type: string
/properties/page $ref: #/shapes/page
/properties/expires_at When the grant stops serving, as an ISO 8601 instant. A read admitted before it is served to its end; a read after it is refused transfer_grant_expired.

Type: string
/properties/command One line, for macOS and Linux, that downloads the export with the turnzero command's export download: echo <grant> | turnzero export download --export <application id>/<export id>, then --origin <origin> off https://turnzero.ai, then --path "<folder>" where the call passed local_path. Run it once, as given, before expires_at. It reads the grant on its standard input and writes the manifest and every file the manifest lists into the folder. It ends 0 where every file is on disk, 1 where a file failed, 2 where it stopped before the end, and 3 where nothing was written. The grant appears in this line and in command_windows, command_npx, and command_npx_windows alone.

Type: string
/properties/command_windows The same line for every Windows shell, with turnzero.cmd where its head says turnzero. On Windows, run this one in command's place, once, as given. The four line members are one command line under one grant.

Type: string
/properties/command_npx The same line run through npx, npx --no-update-notifier -y turnzero@<tag> in place of turnzero, the tag latest on production's platform and next on every other. It is present exactly where command is. Run this line first, or command_npx_windows on Windows; it runs whether or not the command is installed. If npx can't run, use command where turnzero --version responds; else give the person the line to run on their computer. Run npm install -g turnzero@<tag> only if the person wants to keep it. If your tool's permissions blocked the command, tell the person which route you took. A person or a job may run any of the four forms.

Type: string
/properties/command_npx_windows command_npx's line for every Windows shell, with npx.cmd where its head says npx.

Type: string

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The id of the application whose database and files the export reads, one of your account's; `list_applications` returns it."
      },
      "environment": {
        "type": "string",
        "enum": [
          "development",
          "production"
        ],
        "description": "Export environment, default production; omit beside `download: true`, which takes its environment from the export."
      },
      "download": {
        "type": "boolean",
        "description": "`true` returns the line that downloads a completed export's files, naming `export`, in place of starting an export. An application's platform credential is refused it."
      },
      "export": {
        "type": "string",
        "description": "The export's id, from `request_export`. The export must be completed: a running or failed one is refused `export_not_completed`, and an id the application does not hold, or an export whose files no longer exist, is refused 404 `not_found`."
      },
      "local_path": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024,
        "pattern": "^(?:[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\]|\\\\[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\])+$",
        "description": "Optional: the folder on your machine for the export, absolute or relative to where the line runs. Absent, the line writes `export-<export id>` where it runs, refused if that folder holds `package.json`. A path outside the pattern, `~`, or one opening `~/` or `~\\` is refused `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "export",
      "application",
      "environment"
    ],
    "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."
      },
      "export": {
        "type": "string",
        "description": "The export's id, the one `read_export` takes."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "development",
          "production"
        ]
      },
      "state": {
        "type": "string",
        "enum": [
          "running"
        ],
        "description": "`running` at the answer, which precedes the work; a repeat returns the export already running."
      },
      "area": {
        "type": "string",
        "description": "The export area the files are written into, `export-<application id>`."
      },
      "folder": {
        "type": "string",
        "description": "The folder under the area that holds this export's files, `<export id>/`."
      },
      "requested_at": {
        "type": "string"
      },
      "repeated": {
        "type": "boolean",
        "description": "true where an export of the same application and environment was already running and this call returns it; no second export started."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_export"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "export"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "export": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "description": "The exact `read_export` call that reads the export to its end, for the application and the export (MAPI-21)."
      },
      "detail": {
        "type": "string",
        "description": "Says which line runs where and by when and the folder it writes. Where the export recorded an instant for its stored files, it says what the grant in the line reads: the export's own files and the application's stored files created by the time its export listed them. That form also says that a read does not spend the grant and that a fresh call returns another line once the grant expires. Where the export recorded none, it says that the line downloads the export's own files alone and that each stored file the manifest lists reads as absent and counts as failed. That form then says that a fresh export has the application's stored files as they are now, and gives the two calls that make one."
      },
      "page": {
        "$ref": "#/shapes/page"
      },
      "expires_at": {
        "type": "string",
        "description": "When the grant stops serving, as an ISO 8601 instant. A read admitted before it is served to its end; a read after it is refused `transfer_grant_expired`."
      },
      "command": {
        "type": "string",
        "description": "One line, for macOS and Linux, that downloads the export with the turnzero command's `export download`: `echo <grant> | turnzero export download --export <application id>/<export id>`, then `--origin <origin>` off `https://turnzero.ai`, then `--path \"<folder>\"` where the call passed `local_path`. Run it once, as given, before `expires_at`. It reads the grant on its standard input and writes the manifest and every file the manifest lists into the folder. It ends 0 where every file is on disk, 1 where a file failed, 2 where it stopped before the end, and 3 where nothing was written. The grant appears in this line and in `command_windows`, `command_npx`, and `command_npx_windows` alone."
      },
      "command_windows": {
        "type": "string",
        "description": "The same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`. On Windows, run this one in `command`'s place, once, as given. The four line members are one command line under one grant."
      },
      "command_npx": {
        "type": "string",
        "description": "The same line run through npx, `npx --no-update-notifier -y turnzero@<tag>` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other. It is present exactly where `command` is. Run this line first, or `command_npx_windows` on Windows; it runs whether or not the command is installed. If npx can't run, use `command` where `turnzero --version` responds; else give the person the line to run on their computer. Run `npm install -g turnzero@<tag>` only if the person wants to keep it. If your tool's permissions blocked the command, tell the person which route you took. A person or a job may run any of the four forms (PLD-L0-94)."
      },
      "command_npx_windows": {
        "type": "string",
        "description": "`command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
      }
    },
    "description": "Returns 202 at once, before the pass starts writing, on `deploy`'s shape: the export's row was written `running` and the pass continues after the answer; `next`, the `read_export` call, reads its end."
  }
}

Shared contracts #