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

# roll\_back

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

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

Put earlier deployed code on production with that version's setting bindings and plain values\. The serving version draws `version_already_serving`, a newer one `version_newer_than_serving`\. With none serving, no comparison is made\. With one or two environments, take a `promotable` number from `list_versions`\. Across model changes, the account owner decides on data\. No action offers snapshots yet\. If halted, it refuses `target_environment_halted`\. First use `halt_environment` with `resume: true`\. The owner must agree or have asked\.

An answer not from this platform does not show whether the rollback started\. Examples are gateway error pages or closed connections\. Call `read_status` with `wait_seconds` first\. It started if `environments.production.deploy` shows kind promote with a `started_at` later than your call\. Rollbacks use that kind\. Repeat `roll_back` only if that read shows it did not start\.

## More about this action

A rollback works on an application with one environment too: pass one of production's own earlier versions\.

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\. Without `wait_seconds`, the call returns 202 at once with the state `deploying`\.

With `wait_seconds`, up to 45, it waits to reply until the rollback ends, as a promote does\. A rollback ends once every router serves that version, typically after 33 to 45 seconds\. Choose a version whose image is kept, marked `promotable` by `list_versions`\. A version whose image retention deleted is refused `version_image_pruned`; choose a kept version or deploy that code again\. If `version_newer_than_serving` refuses the rollback, use `promote` with two environments, or deploy that code again with one\. To re\-mint the serving version's platform credential, use `promote` on two environments, or deploy again on one\.

## Access and action metadata

```json
{
  "name": "roll_back",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "product": "cloud",
  "summary": "Put an earlier version back into production with that version's code, setting bindings and plain values. The serving version is refused `version_already_serving`, and a newer one `version_newer_than_serving`. It replies and waits as a promote does, `wait_seconds` up to 45 holding its answer until it ends. It works on an application with one environment too, where you pass one of production's own earlier versions.\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 rollback was made. Read `read_status` with `wait_seconds` first: the rollback started where `environments.production.deploy` shows the kind promote, which a rollback's row has, with a `started_at` later than your call. Call `roll_back` again only where that read shows it did not start.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "roll_back",
  "title": "Roll back production",
  "tier": "reversible",
  "scenario": "CHI-L0-09",
  "summary": "Put earlier deployed code on production with that version's setting bindings and plain values. The serving version draws `version_already_serving`, a newer one `version_newer_than_serving`. With none serving, no comparison is made. With one or two environments, take a `promotable` number from `list_versions`. Across model changes, the account owner decides on data. No action offers snapshots yet. If halted, it refuses `target_environment_halted`. First use `halt_environment` with `resume: true`. The owner must agree or have asked.\n\nAn answer not from this platform does not show whether the rollback started. Examples are gateway error pages or closed connections. Call `read_status` with `wait_seconds` first. It started if `environments.production.deploy` shows kind promote with a `started_at` later than your call. Rollbacks use that kind. Repeat `roll_back` only if that read shows it did not start.",
  "owners": [
    "PLD-L0-57",
    "PLD-L0-43",
    "MAPI-04"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application","version"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>version | A deployed number from `list_versions` with `promotable` true\. Where production serves a version, choose an earlier number: the serving version is refused `version_already_serving`, and a newer one `version_newer_than_serving`\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>wait\_seconds | Seconds to hold the answer until the version\-history row this call starts ends\. A value out of range is refused `invalid_request`\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 45 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | A rollback is a promote of the version you pass; it re\-mints the production platform credential as every promote does and never the database credential\. It replies, and holds a wait, as a promote does\. It works on an application with one environment too, where the version you pass is one of production's own earlier deployed rows\.<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>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 | Always `production`: a promote targets production alone\.<br><br>Type: string<br>Pattern: ^production$ |
| /<wbr>properties/<wbr>version | The promoted number, an existing number of the application's history and never a fresh one\.<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 | 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\.<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\. 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 `production`, 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 | Required value: 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 rollback'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\.<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",
      "version"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "version": {
        "type": "integer",
        "minimum": 1,
        "description": "A deployed number from `list_versions` with `promotable` true. Where production serves a version, choose an earlier number: the serving version is refused `version_already_serving`, and a newer one `version_newer_than_serving`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Seconds to hold the answer until the version-history row this call starts ends. A value out of range is 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).\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",
        "pattern": "^production$",
        "description": "Always `production`: a promote targets production alone (PLD-L0-43)."
      },
      "version": {
        "type": "integer",
        "description": "The promoted number, an existing number of the application's history and never a fresh one (PLD-L0-43)."
      },
      "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"
      },
      "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)."
      },
      "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)."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_status"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "environment",
              "wait_seconds"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "environment": {
                "const": "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 `production`, with `wait_seconds` 45."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, says how the rollback'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.\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": "A rollback is a promote of the version you pass; it re-mints the production platform credential as every promote does and never the database credential (PLD-L0-43; SEC-L0-07). It replies, and holds a wait, as a promote does. It works on an application with one environment too, where the version you pass is one of production's own earlier deployed rows (PLD-L0-43)."
  }
}
```

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