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

# restart\_application

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

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

Restart one environment's running copy\. It re\-applies the bindings its serving version recorded, not the current manifest's\. Each binding reads its secret's current value\. The database keeps its data and password\. Stored files stay as they are\. No build or new version is made, and no daily deploy is spent\. A new manifest binding needs a deploy or promote\. Resume a halted environment first\. Wait for any deploy, promote or restart in flight to end\.

An answer not from this platform does not show whether the restart started\. Examples are gateway error pages or closed connections\. Call `read_status` with `wait_seconds` first\. The restart started if the environment's deploy member under `environments` shows kind `restart` with a `started_at` later than your call\. Repeat `restart_application` only if that read shows it did not start\.

## More about this action

The platform re\-creates the serving compute from the version it already serves, with no build and no new version\. The restart applies the settings the platform has now, such as the new hostname after a rename\. A binding the manifest added since that version takes effect at the next deploy or promote\.

With `wait_seconds`, the call waits to reply until the restart ends\. Without it, the call returns 202 at once with the state `deploying` and `next`, and the restart finishes in the background\. Read its end with `read_status` or `list_versions`\. A restart does not count against the application's deploys per day\.

The `wait_seconds` argument: optional, a whole number of seconds from 1 to 45, counted from the call's arrival\. The call waits for the version\-history row it started, and replies when that row ends or the seconds pass\. 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\. A value outside 1 to 45 is refused `invalid_request`, and its detail gives 45 as the bound\.

An environment never deployed is refused `environment_never_deployed`; deploy or promote to it first\. `deploy_in_flight` means a deploy, promote or restart is running: read `read_status` with `wait_seconds` until it ends, then restart only if still needed\. A halted environment is refused `target_environment_halted`; use `halt_environment` with `resume: true`, which starts the compute the halt stopped\. You may need no restart after that resume\.

## Access and action metadata

```json
{
  "name": "restart_application",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "product": "cloud",
  "summary": "Restart one environment's running copy, re-applying the bindings its serving version recorded, each reading its secret's current value; a binding the manifest added since takes effect at the next deploy or promote. The platform re-creates its serving compute from the version it already serves, under the settings the platform holds now, the application's current hostname among them, with no build and no new version. It replies at once with the state `deploying` and `next`, and completes detached, read to its end through `read_status` and `list_versions`. With `wait_seconds` up to 45 it holds its answer until the restart ends. A restart spends none of the application's deploys per day, and it is refused `deploy_in_flight` while any deploy, promote, or restart of the environment is in flight.\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 restart was made. Read `read_status` with `wait_seconds` first: the restart started where the environment's deploy member under `environments` shows the kind `restart` with a `started_at` later than your call. Call `restart_application` again only where that read shows it did not start. Under the super_admin grant the call also takes `placement`, `standing` or `rule`, over any account's application. `rule` runs the placement rule once for the application's size and sleep setting. This operator act moves an existing `shared-0.5gb` production environment onto the shared grain.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "restart_application",
  "title": "Restart application",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Restart one environment's running copy. It re-applies the bindings its serving version recorded, not the current manifest's. Each binding reads its secret's current value. The database keeps its data and password. Stored files stay as they are. No build or new version is made, and no daily deploy is spent. A new manifest binding needs a deploy or promote. Resume a halted environment first. Wait for any deploy, promote or restart in flight to end.\n\nAn answer not from this platform does not show whether the restart started. Examples are gateway error pages or closed connections. Call `read_status` with `wait_seconds` first. The restart started if the environment's deploy member under `environments` shows kind `restart` with a `started_at` later than your call. Repeat `restart_application` only if that read shows it did not start.",
  "owners": [
    "PLD-L0-84",
    "PLD-L0-63",
    "MAPI-04"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application","environment"\] |
| /<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 | The environment whose running copy is restarted, `development` or `production`\. It must hold a serving version with compute; an environment never deployed is refused `environment_never_deployed`\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>wait\_seconds | The seconds the answer is held until this call's version\-history row ends\. A value out of range is refused `invalid_request`\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 45 |
| /<wbr>properties/<wbr>placement | Super\-admin only, for any account's application\. `standing` \(default\) re\-creates compute in place\. `rule` runs the placement rule once for its size and sleep setting, moving a standing `shared-0.5gb` production environment to shared compute\. Other callers passing it are refused `invalid_request`\.<br><br>Type: string<br>Allowed values: \["standing","rule"\] |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Returns 202 at once with `next` where the request carries no `wait_seconds`: the restart's history row, of kind `restart`, is inserted and the work continues detached; its end is read through `read_status` and `list_versions`, never through the action record\. 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`\.<br><br>Type: object<br>Required fields: \["contract\_version","application","environment","version","state","hostname"\] |
| /<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\.<br><br>Type: string |
| /<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>environment | Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>version | The number of the version the environment serves, which the restart re\-creates; a restart allocates no new number\.<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\.<br><br>Type: string<br>Pattern: ^\(deploying\|deployed\|failed\)$ |
| /<wbr>properties/<wbr>hostname | The environment's hostname under the application's current label, the value the re\-created copy reads as its public host\.<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 absent only where the recorded manifest holds no health path, which the manifest's schema admits nowhere, and on the operator's restart of another account's application\.<br><br>Type: string |
| /<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, cut where the operator restarts another account's application\. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one\.<br><br>Type: object |
| /<wbr>properties/<wbr>next | Present where the answer is 202 with the state `deploying`: at once without `wait_seconds`, and where the wait did not settle\. It is the exact call that reads the row to its end, `read_status` for the environment restarted, with `wait_seconds` 45\.<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 | Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments/<wbr>properties/<wbr>wait\_seconds | Required value: 45 |
| /<wbr>properties/<wbr>detail | With the state `deploying`, says how the restart'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 alone, with no smoke path requested\. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors\. That form also says the new copy took each bound setting's current stored value\.<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>Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application",
      "environment"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "The environment whose running copy is restarted, `development` or `production`. It must hold a serving version with compute; an environment never deployed is refused `environment_never_deployed`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "The seconds the answer is held until this call's version-history row ends. A value out of range is refused `invalid_request`."
      },
      "placement": {
        "type": "string",
        "enum": [
          "standing",
          "rule"
        ],
        "description": "Super-admin only, for any account's application. `standing` (default) re-creates compute in place. `rule` runs the placement rule once for its size and sleep setting, moving a standing `shared-0.5gb` production environment to shared compute. Other callers passing it are refused `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "version",
      "state",
      "hostname"
    ],
    "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)."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$"
      },
      "version": {
        "type": "integer",
        "description": "The number of the version the environment serves, which the restart re-creates; a restart allocates no new number."
      },
      "state": {
        "type": "string",
        "pattern": "^(deploying|deployed|failed)$",
        "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."
      },
      "hostname": {
        "type": "string",
        "description": "The environment's hostname under the application's current label, the value the re-created copy reads as its public host."
      },
      "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 absent only where the recorded manifest holds no health path, which the manifest's schema admits nowhere (PLD-L0-63), and on the operator's restart of another account's application (MAPI-20)."
      },
      "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, cut where the operator restarts another account's application. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one (PLD-L0-63)."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_status"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "environment",
              "wait_seconds"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "environment": {
                "enum": [
                  "development",
                  "production"
                ]
              },
              "wait_seconds": {
                "const": 45
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "description": "Present where the answer is 202 with the state `deploying`: at once without `wait_seconds`, and where the wait did not settle. It is the exact call that reads the row to its end, `read_status` for the environment restarted, with `wait_seconds` 45."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, says how the restart'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 alone, with no smoke path requested. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors. That form also says the new copy took each bound setting's current stored value (PLD-L0-84).\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."
      }
    },
    "description": "Returns 202 at once with `next` where the request carries no `wait_seconds`: the restart's history row, of kind `restart`, is inserted and the work continues detached; its end is read through `read_status` and `list_versions`, never through the action record. 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-84)."
  }
}
```

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