---
title: "deploy"
description: "Generated reference for the management action deploy: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/deploy
order: 21
visibility: public
redirects_from: []
---

# deploy

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/deploy`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `tzcloud_deploy`.

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

Deploy a stored ZIP or start a prepared upload\.

`artifact` deploys a storage ZIP\. `upload` only retries a prepared start\. A tool with no shell uses `deploy_files`\. With a shell and the app's whole folder, use `deploy_command` where it works\. A script passes `artifact` to deploy a stored zip\.

A gateway error, closed connection or non\-platform response leaves the outcome unknown\. A `read_status` row of kind deploy, started after your call, confirms a start\. A retry is allowed only when status shows no start, using `pending_upload.retry` where supplied\.

Details: read\_documentation /cloud/getting\-started/ways\-to\-deploy/\.

## More about this action

A deploy goes to production until `create_environment` adds development, and to development after that; `promote` then moves a version to production\. A deploy past the size's 24\-hour cap, the `deploys-per-day` row of `read_plan_quotas`, is refused `deploys_per_day_exceeded`\. Both sizes have the same cap\.

The request has an artifact form and an upload form\. Pass `artifact` for a stored ZIP\. The turnzero command's preparing call passes `zip_sha256` on the HTTP route, and its start passes `upload`\. Pass `upload` yourself only to retry that start, as `read_status`'s `pending_upload.retry` gives it\. `commit` is optional on a start with `upload` or `artifact`; `wait_seconds` is optional on every start\.

For a folder on your computer, call `deploy_command` and run its returned line\. It writes and starts nothing; the line zips, uploads, and deploys the folder when run\. Choose the route with read\_documentation, page /cloud/getting\-started/ways\-to\-deploy/\.

While a deploy of the environment is in flight, a call that passes the same `artifact` hash, or the `upload` that deploy read, returns that deploy\. Any other call is refused `deploy_in_flight`, even an upload of identical bytes\.

Where the upload arrived and no deploy read it, `read_status` lists it as `pending_upload` on the environment the deploy goes to\. Once the cause of the refusal is cleared, make the call in its `retry`\. Where `retry` is null, call `deploy_command` and run its line; fix the folder first where its zip was refused\. A call that passes `upload` reads the zip the command wrote and deploys it as the artifact form does\. An upload with no such file is refused `upload_not_found`: it was not uploaded yet, it expired unused, a later preparing call replaced it, or a deploy that has ended already read it\.

For a script, use the artifact form\. Upload the zip to a declared storage area under a single\-use grant from `mint_upload_grant`, then pass its area, file name, and SHA\-256 in `artifact`\. The `environment` member of `artifact` says where the file is stored, never where it deploys\.

The command's start passes `commit` where the folder has a Git repository, and an `artifact` start may pass it\. The version keeps the commit, and so do its promote, its rollback, and the build record in the application's issue\-tracking space\. The command's preparing call records `rotate_database_credential` on the upload's grant where its line carries the flag\. A start of that upload that passes no such member still applies it, and a refused start's `retry` includes it\.

The platform then builds the artifact's image with its declared runtime dependencies, starts it, and checks its health\. Development of either size, and production of a `shared-0.5gb` application, run as a pod where the platform has a shared group of that kind open\. Where the cell has no such group, the environment runs as a container app\. Where every such group is full, the deploy is refused `group_full`\. Production of a `shared-1gb` application runs as its own container app\. A deploy to a halted production is refused `target_environment_halted`\. A deploy to a halted development environment ends the halt once it has passed its refusals\.

A deploy typically takes up to about two and a half minutes on a development pod and three and a half on its own container app\. Most of that is the image build: up to about two and a quarter minutes for a first version, and a minute and a half for a later one\. Where the artifact installs nothing and ships no native module, the platform usually assembles the image without running a build\. Such a deploy takes about 15 seconds on a pod and about 45 on its own container app, up to about 80 for its first\. The health check's own limit is 180 seconds\. Each version\-history row records its step `timings`, and a failed build's `outcome` contains its last lines\.

An answer that did not settle gives the `next` call, `read_status`, whose environment's deploy member gives the `step`\. After an answer that is not this platform's own, make that read first\. Call `deploy` again only where that member shows no row of kind deploy with a `started_at` later than your call\. An upload still listed in `pending_upload` was not started\. Each server holds one wait per application\. This call's wait takes that place\. A concurrent held `read_status` for that application on the same server returns at once, from its own read\.

An external API's stored key goes through `declare_outbound_api`, whose `sdk_settings` let an unchanged SDK reach the API\. A value your code reads itself is bound in the manifest's `settings`\.

The `environment` argument: left out, the deploy goes to the application's deploy target: production with one environment, development with two\.

The `artifact` argument: an absent file or a hash mismatch is refused by name\. So is the platform's deploy area, which only the upload form reads\.

The `upload` argument: the upload's id, which the turnzero command's `prepared:` line prints and its start passes\. Pass it yourself only to start that upload again, where its start was refused or never made, as the `retry` of `pending_upload` in `read_status` shows\.

The `wait_seconds` argument: the seconds, 1 to 45, counted from the call's arrival, that the call waits for the version\-history row it started\. It replies when that row ends or the seconds pass\. A value outside that range is refused `invalid_request`, and its detail gives 45 as the bound\.

The `commit` argument: on a start you make yourself, one that passes `upload` or `artifact`, the commit the code was built from\. It is 7 to 64 lower\-case hexadecimal characters, as `git rev-parse HEAD` prints\. On the upload path, leave it out: the turnzero command reads the folder's commit, where it has a Git repository, and passes it on its start\.

The `rotate_database_credential` argument: on production, `true` rotates the database credential\. The preparing call records it on the upload's grant, and its start applies it\.

## Access and action metadata

```json
{
  "name": "deploy",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Deploy a built artifact to the environment the application's deploys go to: production on an application with one environment, and development on one with two, where production receives a version through `promote`. The command alone passes `zip_sha256`, on the HTTP action route, and over this connection a call that passes it is refused `local_route_required`. Called with that `upload`, by the command's start or by a retry of a start refused or never made, it starts the deploy. So does a call with an `artifact` in a storage area bound to the application. It returns 202 `deploying`, or, with `wait_seconds` up to 45, holds its answer until the deploy ends. The compute grain is chosen before any compute act: a development environment of either size, and the production environment of a `shared-0.5gb` application, run as a pod in the hosting cell's admitting group of its kind with headroom, and as a container app where the cell has none. The production environment of a `shared-1gb` or unlimited application runs as its own container app. A full group is refused `group_full` and a row in a group of another kind `group_kind_mismatch`. A grain that differs from the existing compute's is the grain migration, the previous compute deleted after its hold. The hosts a manifest's `egress` member declares are reached in the tunnel mode with no key applied; a host called on a stored key is a declared upstream (`declare_outbound_api`), its key applied at the gateway's edge, and the container holding at most the upstream's egress key. The start may pass `commit`, the commit the code was built from. The version keeps it, its promote and rollback carry it, and so does the build row the platform writes into the application's own issue-tracking space. On a deploy to production, `rotate_database_credential` true also sets a new production database password, as a promote does; the command's preparing call records it for the upload's start. Its answer leads with a `summary`; unsettled, it gives the `next` call, a `read_status` that shows the `step`.\n\nAn answer that is not this platform's own, such as a gateway's error page or a closed connection, says nothing about whether the deploy started. Read `read_status` with `wait_seconds` first: the deploy started only where the environment's deploy member shows the kind deploy with a `started_at` later than your call. Where `pending_upload` still lists the upload, its start was not made: make the call its `retry` carries. Call again only where that read shows no start.\n\nChoose the route with read_documentation, page /cloud/getting-started/ways-to-deploy/.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "deploy",
  "title": "Deploy application",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Deploy a stored ZIP or start a prepared upload.\n\n`artifact` deploys a storage ZIP. `upload` only retries a prepared start. A tool with no shell uses `deploy_files`. With a shell and the app's whole folder, use `deploy_command` where it works. A script passes `artifact` to deploy a stored zip.\n\nA gateway error, closed connection or non-platform response leaves the outcome unknown. A `read_status` row of kind deploy, started after your call, confirms a start. A retry is allowed only when status shows no start, using `pending_upload.retry` where supplied.\n\nDetails: read_documentation /cloud/getting-started/ways-to-deploy/.",
  "owners": [
    "PLD-L0-43",
    "PLD-L0-127",
    "PLD-L0-136",
    "MAN-09",
    "EGW-L0-01",
    "EGW-L0-11",
    "PLD-L0-63",
    "PLD-L0-40",
    "PLD-L0-41",
    "PRC-L0-16",
    "OST-L0-01",
    "MAPI-04",
    "OST-L0-08",
    "PLD-L0-86",
    "PLD-L0-89",
    "PLD-L0-90",
    "MAN-14",
    "SEC-L0-18",
    "ITS-L0-02"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | With one environment, default production\. Development needs `create_environment`, else `environment_not_created`\. With two, default development, and production is refused `environment_unavailable`; production changes use `promote`\.<br><br>Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>artifact | Stored ZIP\. Missing file, hash mismatch or the platform deploy area is refused by name\. Excludes `upload`, else `invalid_request`\.<br><br>Type: object<br>Required fields: \["area","name","hash"\] |
| /<wbr>properties/<wbr>artifact/<wbr>properties/<wbr>area | Type: string |
| /<wbr>properties/<wbr>artifact/<wbr>properties/<wbr>name | Type: string |
| /<wbr>properties/<wbr>artifact/<wbr>properties/<wbr>hash | SHA\-256 of ZIP bytes, hexadecimal\.<br><br>Type: string<br>Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /<wbr>properties/<wbr>artifact/<wbr>properties/<wbr>environment | Storage partition, not deploy target\. Default the deployment's environment\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>upload | Prepared upload id from the command's `prepared:` line, only for retrying its start\. No file gives `upload_not_found`\. Changed SHA\-256 gives `upload_hash_mismatch`, which retries cannot start\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ |
| /<wbr>properties/<wbr>zip\_sha256 | Taken on the HTTP action route alone, from the turnzero command's preparing call: the SHA\-256 of the zip the command made and will upload, 64 lower\-case hexadecimal characters\. The MCP tool has no `zip_sha256` member, and a call that passes it there is refused `local_route_required`\. From a tool, call `deploy_command` and run the line it returns\. A value of another form, or one passed with `artifact` or `upload`, is refused `invalid_request`\.<br><br>Type: string<br>HTTP action route only, never an MCP tool argument: true |
| /<wbr>properties/<wbr>wait\_seconds | Seconds to wait for the deploy to end\. Out of range gives `invalid_request`\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 45 |
| /<wbr>properties/<wbr>commit | Build commit from `git rev-parse HEAD`, on a self\-made start only\. Malformed or supplied during preparation gives `invalid_request`\. Omitted records no commit\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{7,64\}$ |
| /<wbr>properties/<wbr>rotate\_database\_credential | True also changes the production database\-role password\. Other values, or development, give `invalid_request`\.<br><br>Type: boolean |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | With `artifact` or `upload`, 202 at once with `next`, before the build starts: the environment's version\-history row was inserted `deploying`, and the build, the apply, the publish, and the health gate continue after the answer\. With `wait_seconds`, the answer is held until the row ends: settled, it is 200 with the state `deployed` or `failed` and the row's `outcome`; unsettled, it is 202 with `next`\. While a deploy of the environment is in flight, a second deploy with `artifact` returns it for the same artifact hash and is refused `deploy_in_flight` for a different one\. A call passing `upload` returns it only where that deploy read the same upload, and any other upload is refused `deploy_in_flight`, identical bytes included\. On the HTTP action route alone, the command's preparing call passes `zip_sha256` and returns 200 with the state `awaiting_upload` and `upload`\.<br><br>Type: object<br>Required fields: \["contract\_version","application","environment","state"\] |
| /<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>summary | The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended\. Absent with `awaiting_upload`\.<br><br>Where this call's held answer ends `deployed` on production, the summary may close with an invitation warning\. This applies to an `invited` audience whose production realm is absent, or holds no end user other than test end users and no standing invitation\. The warning says no invited user can sign in to production yet and tells the caller to use `invite_end_user`\. It is added last, only if the whole summary fits its budget\. A failed realm read adds no warning\.<br><br>Type: string |
| /<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>environment | Type: string |
| /<wbr>properties/<wbr>version | The version number the deploy's history row carries: returned with `deploying`, `deployed`, and `failed`, and absent with the other states\.<br><br>Type: integer |
| /<wbr>properties/<wbr>state | `deploying` on the 202 answer, which precedes the row's end\. The state is `deployed` or `failed` on the 200 answer, where the request's `wait_seconds` saw the row end\. The state is `awaiting_upload` on the 200 answer to the turnzero command's preparing call on the HTTP action route, which passes `zip_sha256`; it inserts no version row and starts nothing\.<br><br>Type: string<br>Pattern: ^\(deploying\|deployed\|failed\|awaiting\_upload\)$ |
| /<wbr>properties/<wbr>hostname | The hostname of the environment the deploy goes to: returned with `deploying`, `deployed`, and `failed`, and absent with the other states\.<br><br>Type: string |
| /<wbr>properties/<wbr>health\_path | The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it\. It is returned where this call starts the deploy\. It is absent with `awaiting_upload`, which starts no deploy, the preparing answer carrying `recorded_health_path` instead, and on an answer that joins a deploy already in flight\.<br><br>Type: string |
| /<wbr>properties/<wbr>recorded\_health\_path | With the state `awaiting_upload`: the recorded manifest's health path, whole and never cut\. It is absent for a serverless application\. It is absent too where no manifest exists, a case the preparing call refuses\. The turnzero command reads it before its upload, refusing where the start's health check would\.<br><br>Type: string |
| /<wbr>properties/<wbr>served\_version | Present with the state `awaiting_upload`: the environment's serving version as `read_status` shows it, null where none serves\. With `recorded_health_path` it tells the turnzero command whether the start's health check would read the zip\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>settled | Present where the request carried `wait_seconds`\. True where the one read after the wait found the row this call started ended, whatever ended the wait\. False means that read found the row still deploying, or could not read it, and not that it failed: `next` gives the call that waits on it\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>waited\_ms | Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>outcome | Present where the wait settled: the row's `outcome` as `list_versions` returns it\. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one\.<br><br>Type: object |
| /<wbr>properties/<wbr>server\_errors\_since | Present where the wait saw the row end `deployed`: the router's 5xx responses since the version began serving, as `check_deploy`'s `last_release` counts them\. `count` runs from `since`, the later of the row's end and seven days before the read\. It is capped at 500, and `capped` is true where the cap was met, the count then a floor\. It covers only the routes requested in that time, so a route nobody requested counts nothing\. A route listed in the manifest's `smoke_paths` is checked before each deploy and promote switches, and that check is not in this count\. Where the read failed, `unread` carries its reason\. Absent on every other response\.<br><br> |
| /<wbr>properties/<wbr>server\_errors\_since/<wbr>oneOf/<wbr>0 | Type: object<br>Required fields: \["count","since","capped"\] |
| /<wbr>properties/<wbr>server\_errors\_since/<wbr>oneOf/<wbr>0/<wbr>properties/<wbr>count | Type: integer<br>Minimum: 0<br>Maximum: 500 |
| /<wbr>properties/<wbr>server\_errors\_since/<wbr>oneOf/<wbr>0/<wbr>properties/<wbr>since | Type: string |
| /<wbr>properties/<wbr>server\_errors\_since/<wbr>oneOf/<wbr>0/<wbr>properties/<wbr>capped | Type: boolean |
| /<wbr>properties/<wbr>server\_errors\_since/<wbr>oneOf/<wbr>1 | Type: object<br>Required fields: \["unread"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>server\_errors\_since/<wbr>oneOf/<wbr>1/<wbr>properties/<wbr>unread | Why the count was not read: `failed`, `timed_out`, or `read_status`'s own word for its `server_errors` member, such as `unavailable`\.<br><br>Type: string |
| /<wbr>properties/<wbr>upload | Present with the state `awaiting_upload` alone, the answer to the turnzero command's preparing call on the HTTP action route: one pending upload of the zip whose SHA\-256 the call passed, under a short\-lived grant for that one zip, returned in `grant`\. Its one write puts the zip, and its one start deploys it\. After that start, the same grant serves the command's own progress reads of that deploy, until five minutes after it ends and never past fifteen minutes after the start\. The same zip sent again under the grant before `expires_at`, once its write landed and while no later call replaced the upload, receives 200 with the file's name, area, size, and SHA\-256 and writes nothing; other bytes under the spent grant are refused `transfer_grant_spent`\. A later preparing call for the application replaces an upload no deploy has read\.<br><br>Type: object<br>Required fields: \["id","expires\_at","max\_bytes","grant"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>upload/<wbr>properties/<wbr>id | The upload's id, which the turnzero command's `prepared:` line prints and its start passes as `upload`\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ |
| /<wbr>properties/<wbr>upload/<wbr>properties/<wbr>expires\_at | When the upload's grant stops serving, as an ISO 8601 instant\. A write or a start under the grant after it is refused `transfer_grant_expired`, and a `deploy_command` call returns a new line\.<br><br>Type: string |
| /<wbr>properties/<wbr>upload/<wbr>properties/<wbr>max\_bytes | The most bytes the zip may carry, the configured bound\.<br><br>Type: integer |
| /<wbr>properties/<wbr>upload/<wbr>properties/<wbr>grant | The upload's grant, its value alone\. The deploy command from 0\.8\.0 reads it here and presents it as the bearer of the upload, the start, and the progress read\. It is returned on the HTTP action route alone, in the answer to the preparing call\.<br><br>Type: string |
| /<wbr>properties/<wbr>next | The exact `read_status` call that reads the deploy to its end\. With the state `awaiting_upload` it is made where the command returned before the outcome, or to read the whole record\. It carries the request's `wait_seconds`, which that answer did not wait on; where the command ended 3, nothing started, and its printed refusal is the way on\. With `deploying`, it is present at once without `wait_seconds`, and where the wait did not settle\.<br><br>Type: object<br>Required fields: \["action","arguments"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>action | Required value: read\_status |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments | Type: object<br>Required fields: \["application","environment","wait\_seconds"\]<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>environment | Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments/<wbr>properties/<wbr>wait\_seconds | The read's wait: 45, or the preparing call's own `wait_seconds`, 45 where it gave none\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 45 |
| /<wbr>properties/<wbr>detail | With the state `deploying`, says how the deploy's step and end are read: the `next` call, `read_status` with `wait_seconds` 45, or a read every ten seconds\.<br><br>With `deployed` or `failed`, says how the row ended\. For a deployed run that entered `health_gate`, it says the check requested the health path and any smoke paths the manifest lists\. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors\. It closes that form by saying the health path returned status 200 three times in a row, so that path needs no further request\.<br><br>With `deployed` and a run that entered no `health_gate`, it says no health check or smoke check ran and to request its pages or routes and read `read_logs` for errors\. A row with no step list uses the health\-check form\.<br><br>With `awaiting_upload`, identifies the upload's grant, which deploys to the answer's `environment` only the zip whose SHA\-256 the call passed, and gives no line to run\.<br><br>Type: string |
| /<wbr>properties/<wbr>manifest\_notice | present where the zip's manifest\.json, less its application member, differs or does not parse, or a lib/ copy is unread, uncompared, or unpaired\.<br><br>Type: string |
| /<wbr>properties/<wbr>artifact\_notice | present where the build will not run an install script or rebuild a binding\.gyp of the root or a workspace member, listing each and each member package\.json left unread\.<br><br>Type: string |
| /<wbr>properties/<wbr>client\_notice | present where the zip's client/ folder holds a file beyond the shell or a name the publish skips: counts the files the router serves at their own paths, listing twenty beyond the shell and twenty skipped, then counting the rest\.<br><br>Type: string |
| /<wbr>properties/<wbr>database\_notice | present where the target environment declares or holds a database and the deploy serves APP\_DATABASE\_URL on the pooler's port\. The fixed notice describes transaction pooling's limits and APP\_DATABASE\_DIRECT\_URL for work requiring one held server connection\. It rides an at\-once answer and a held answer, and deploy\_files with check\_only, but no preparing answer\. It refuses nothing\.<br><br>Type: string |
| /<wbr>properties/<wbr>usage\_notice | Present while the application's usage state is over, absent otherwise\. For a size, the daily check found stored data at or past its served quantity\. It lists the over measures and what each refuses\. A size has no backend\-actions or data\-transfer quantity\. It lists file puts on bound storage areas for stored data until the next successful daily pass or a raised quantity\. It also says that the deploy proceeded\. The deploy itself is never refused for usage\.<br><br>Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "enum": [
          "development",
          "production"
        ],
        "description": "With one environment, default production. Development needs `create_environment`, else `environment_not_created`. With two, default development, and production is refused `environment_unavailable`; production changes use `promote`."
      },
      "artifact": {
        "type": "object",
        "required": [
          "area",
          "name",
          "hash"
        ],
        "properties": {
          "area": {
            "type": "string",
            "description": ""
          },
          "name": {
            "type": "string",
            "description": ""
          },
          "hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "SHA-256 of ZIP bytes, hexadecimal."
          },
          "environment": {
            "type": "string",
            "pattern": "^(development|production)$",
            "description": "Storage partition, not deploy target. Default the deployment's environment."
          }
        },
        "description": "Stored ZIP. Missing file, hash mismatch or the platform deploy area is refused by name. Excludes `upload`, else `invalid_request`."
      },
      "upload": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
        "description": "Prepared upload id from the command's `prepared:` line, only for retrying its start. No file gives `upload_not_found`. Changed SHA-256 gives `upload_hash_mismatch`, which retries cannot start."
      },
      "zip_sha256": {
        "type": "string",
        "x-wire-only": true,
        "description": "Taken on the HTTP action route alone, from the turnzero command's preparing call: the SHA-256 of the zip the command made and will upload, 64 lower-case hexadecimal characters. The MCP tool has no `zip_sha256` member, and a call that passes it there is refused `local_route_required`. From a tool, call `deploy_command` and run the line it returns. A value of another form, or one passed with `artifact` or `upload`, is refused `invalid_request`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Seconds to wait for the deploy to end. Out of range gives `invalid_request`."
      },
      "commit": {
        "type": "string",
        "pattern": "^[0-9a-f]{7,64}$",
        "description": "Build commit from `git rev-parse HEAD`, on a self-made start only. Malformed or supplied during preparation gives `invalid_request`. Omitted records no commit."
      },
      "rotate_database_credential": {
        "type": "boolean",
        "description": "True also changes the production database-role password. Other values, or development, give `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "state"
    ],
    "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."
      },
      "summary": {
        "type": "string",
        "description": "The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended (PLD-L0-63). Absent with `awaiting_upload`.\n\nWhere this call's held answer ends `deployed` on production, the summary may close with an invitation warning. This applies to an `invited` audience whose production realm is absent, or holds no end user other than test end users and no standing invitation. The warning says no invited user can sign in to production yet and tells the caller to use `invite_end_user`. It is added last, only if the whole summary fits its budget. A failed realm read adds no warning."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string"
      },
      "version": {
        "type": "integer",
        "description": "The version number the deploy's history row carries: returned with `deploying`, `deployed`, and `failed`, and absent with the other states."
      },
      "state": {
        "type": "string",
        "pattern": "^(deploying|deployed|failed|awaiting_upload)$",
        "description": "`deploying` on the 202 answer, which precedes the row's end. The state is `deployed` or `failed` on the 200 answer, where the request's `wait_seconds` saw the row end. The state is `awaiting_upload` on the 200 answer to the turnzero command's preparing call on the HTTP action route, which passes `zip_sha256`; it inserts no version row and starts nothing."
      },
      "hostname": {
        "type": "string",
        "description": "The hostname of the environment the deploy goes to: returned with `deploying`, `deployed`, and `failed`, and absent with the other states."
      },
      "health_path": {
        "type": "string",
        "description": "The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is returned where this call starts the deploy. It is absent with `awaiting_upload`, which starts no deploy, the preparing answer carrying `recorded_health_path` instead, and on an answer that joins a deploy already in flight (PLD-L0-63)."
      },
      "recorded_health_path": {
        "type": "string",
        "description": "With the state `awaiting_upload`: the recorded manifest's health path, whole and never cut. It is absent for a serverless application. It is absent too where no manifest exists, a case the preparing call refuses. The turnzero command reads it before its upload, refusing where the start's health check would (PLD-L0-86; PLD-L0-94)."
      },
      "served_version": {
        "type": [
          "integer",
          "null"
        ],
        "description": "Present with the state `awaiting_upload`: the environment's serving version as `read_status` shows it, null where none serves. With `recorded_health_path` it tells the turnzero command whether the start's health check would read the zip (PLD-L0-86)."
      },
      "settled": {
        "type": "boolean",
        "description": "Present where the request carried `wait_seconds`. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: `next` gives the call that waits on it (MAPI-04; PLD-L0-63)."
      },
      "waited_ms": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started."
      },
      "outcome": {
        "type": "object",
        "description": "Present where the wait settled: the row's `outcome` as `list_versions` returns it. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one (PLD-L0-63)."
      },
      "server_errors_since": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "count",
              "since",
              "capped"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 500
              },
              "since": {
                "type": "string"
              },
              "capped": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "unread"
            ],
            "properties": {
              "unread": {
                "type": "string",
                "description": "Why the count was not read: `failed`, `timed_out`, or `read_status`'s own word for its `server_errors` member, such as `unavailable`."
              }
            },
            "additionalProperties": false
          }
        ],
        "description": "Present where the wait saw the row end `deployed`: the router's 5xx responses since the version began serving, as `check_deploy`'s `last_release` counts them. `count` runs from `since`, the later of the row's end and seven days before the read. It is capped at 500, and `capped` is true where the cap was met, the count then a floor. It covers only the routes requested in that time, so a route nobody requested counts nothing. A route listed in the manifest's `smoke_paths` is checked before each deploy and promote switches, and that check is not in this count. Where the read failed, `unread` carries its reason. Absent on every other response."
      },
      "upload": {
        "type": "object",
        "required": [
          "id",
          "expires_at",
          "max_bytes",
          "grant"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
            "description": "The upload's id, which the turnzero command's `prepared:` line prints and its start passes as `upload`."
          },
          "expires_at": {
            "type": "string",
            "description": "When the upload's grant stops serving, as an ISO 8601 instant. A write or a start under the grant after it is refused `transfer_grant_expired`, and a `deploy_command` call returns a new line."
          },
          "max_bytes": {
            "type": "integer",
            "description": "The most bytes the zip may carry, the configured bound."
          },
          "grant": {
            "type": "string",
            "description": "The upload's grant, its value alone. The deploy command from 0.8.0 reads it here and presents it as the bearer of the upload, the start, and the progress read. It is returned on the HTTP action route alone, in the answer to the preparing call."
          }
        },
        "additionalProperties": false,
        "description": "Present with the state `awaiting_upload` alone, the answer to the turnzero command's preparing call on the HTTP action route: one pending upload of the zip whose SHA-256 the call passed, under a short-lived grant for that one zip, returned in `grant`. Its one write puts the zip, and its one start deploys it. After that start, the same grant serves the command's own progress reads of that deploy, until five minutes after it ends and never past fifteen minutes after the start. The same zip sent again under the grant before `expires_at`, once its write landed and while no later call replaced the upload, receives 200 with the file's name, area, size, and SHA-256 and writes nothing; other bytes under the spent grant are refused `transfer_grant_spent`. A later preparing call for the application replaces an upload no deploy has read."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_status"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "environment",
              "wait_seconds"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "environment": {
                "type": "string",
                "pattern": "^(development|production)$"
              },
              "wait_seconds": {
                "type": "integer",
                "minimum": 1,
                "maximum": 45,
                "description": "The read's wait: 45, or the preparing call's own `wait_seconds`, 45 where it gave none."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "description": "The exact `read_status` call that reads the deploy to its end. With the state `awaiting_upload` it is made where the command returned before the outcome, or to read the whole record. It carries the request's `wait_seconds`, which that answer did not wait on; where the command ended 3, nothing started, and its printed refusal is the way on. With `deploying`, it is present at once without `wait_seconds`, and where the wait did not settle."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, says how the deploy's step and end are read: the `next` call, `read_status` with `wait_seconds` 45, or a read every ten seconds (MAPI-04).\n\nWith `deployed` or `failed`, says how the row ended. For a deployed run that entered `health_gate`, it says the check requested the health path and any smoke paths the manifest lists. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors. It closes that form by saying the health path returned status 200 three times in a row, so that path needs no further request.\n\nWith `deployed` and a run that entered no `health_gate`, it says no health check or smoke check ran and to request its pages or routes and read `read_logs` for errors. A row with no step list uses the health-check form.\n\nWith `awaiting_upload`, identifies the upload's grant, which deploys to the answer's `environment` only the zip whose SHA-256 the call passed, and gives no line to run."
      },
      "manifest_notice": {
        "type": "string",
        "description": "present where the zip's manifest.json, less its application member, differs or does not parse, or a lib/ copy is unread, uncompared, or unpaired (PLD-L0-63)."
      },
      "artifact_notice": {
        "type": "string",
        "description": "present where the build will not run an install script or rebuild a binding.gyp of the root or a workspace member, listing each and each member package.json left unread (PLD-L0-60)."
      },
      "client_notice": {
        "type": "string",
        "description": "present where the zip's client/ folder holds a file beyond the shell or a name the publish skips: counts the files the router serves at their own paths, listing twenty beyond the shell and twenty skipped, then counting the rest (SVC-L0-26)."
      },
      "database_notice": {
        "type": "string",
        "description": "present where the target environment declares or holds a database and the deploy serves APP_DATABASE_URL on the pooler's port (PLD-L0-63; DBS-L0-02). The fixed notice describes transaction pooling's limits and APP_DATABASE_DIRECT_URL for work requiring one held server connection. It rides an at-once answer and a held answer, and deploy_files with check_only, but no preparing answer. It refuses nothing."
      },
      "usage_notice": {
        "type": "string",
        "description": "Present while the application's usage state is over, absent otherwise. For a size, the daily check found stored data at or past its served quantity (ACB-L0-26). It lists the over measures and what each refuses. A size has no backend-actions or data-transfer quantity. It lists file puts on bound storage areas for stored data until the next successful daily pass or a raised quantity. It also says that the deploy proceeded. The deploy itself is never refused for usage."
      }
    },
    "description": "With `artifact` or `upload`, 202 at once with `next`, before the build starts: the environment's version-history row was inserted `deploying`, and the build, the apply, the publish, and the health gate continue after the answer. With `wait_seconds`, the answer is held until the row ends: settled, it is 200 with the state `deployed` or `failed` and the row's `outcome`; unsettled, it is 202 with `next` (MAPI-04; PLD-L0-63). While a deploy of the environment is in flight, a second deploy with `artifact` returns it for the same artifact hash and is refused `deploy_in_flight` for a different one (PLD-L0-63; MAPI-04). A call passing `upload` returns it only where that deploy read the same upload, and any other upload is refused `deploy_in_flight`, identical bytes included (PLD-L0-86). On the HTTP action route alone, the command's preparing call passes `zip_sha256` and returns 200 with the state `awaiting_upload` and `upload`."
  }
}
```

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