---
title: "request_export"
description: "Generated reference for the management action request_export: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/request-export
order: 89
visibility: public
redirects_from: ["/reference/actions/mint-download-grant"]
---

# request\_export

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

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

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

```json
{
  "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<br>Required fields: \["application"\] |
| /<wbr>properties/<wbr>application | The id of the application whose database and files the export reads, one of your account's; `list_applications` returns it\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | Export environment, default production; omit beside `download: true`, which takes its environment from the export\.<br><br>Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>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\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>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`\.<br><br>Type: string |
| /<wbr>properties/<wbr>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`\.<br><br>Type: string<br>Minimum length: 1<br>Maximum length: 1024<br>Pattern: ^\(?:\[^"$\`%\!&amp;\\\|&lt;&gt;^\\u201c\-\\u201e\\u0000\-\\u001f\\u007f\\\\\]\|\\\\\[^"$\`%\!&amp;\\\|&lt;&gt;^\\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\.<br><br>Type: object<br>Required fields: \["contract\_version","export","application","environment"\] |
| /<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>export | The export's id, the one `read_export` takes\.<br><br>Type: string |
| /<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>environment | Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>state | `running` at the answer, which precedes the work; a repeat returns the export already running\.<br><br>Type: string<br>Allowed values: \["running"\] |
| /<wbr>properties/<wbr>area | The export area the files are written into, `export-<application id>`\.<br><br>Type: string |
| /<wbr>properties/<wbr>folder | The folder under the area that holds this export's files, `<export id>/`\.<br><br>Type: string |
| /<wbr>properties/<wbr>requested\_at | Type: string |
| /<wbr>properties/<wbr>repeated | true where an export of the same application and environment was already running and this call returns it; no second export started\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>next | The exact `read_export` call that reads the export to its end, for the application and the export\.<br><br>Type: object<br>Required fields: \["action","arguments"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>action | Required value: read\_export |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments | Type: object<br>Required fields: \["application","export"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments/<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments/<wbr>properties/<wbr>export | Type: string |
| /<wbr>properties/<wbr>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\.<br><br>Type: string |
| /<wbr>properties/<wbr>page | $ref: \#/shapes/page |
| /<wbr>properties/<wbr>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`\.<br><br>Type: string |
| /<wbr>properties/<wbr>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\.<br><br>Type: string |
| /<wbr>properties/<wbr>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\.<br><br>Type: string |
| /<wbr>properties/<wbr>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\.<br><br>Type: string |
| /<wbr>properties/<wbr>command\_npx\_windows | `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx`\.<br><br>Type: string |

## Complete payload contract

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

- [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/)
