roll_back

Generated automatically from the published contract sources.

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.

A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/roll_back, with a bearer credential and the action's payload as the JSON body.

Contract description

Put an earlier version back into production: a promote with the version named, refused where that version already serves. It works on an application with one environment too, naming one of production's own earlier versions. It moves code only; across a data-model change the customer chooses the data's path, and no action serves the snapshot path yet. It answers and waits as a promote does: with `wait_seconds`, up to 45, it holds its answer until it ends, once every router reaches the version named, typically 33 to 45 seconds.

An 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` names the kind `promote`, which a rollback's row carries, with a `started_at` later than your call. Call `roll_back` again only where that read shows it did not start.

Access and action metadata

{
  "name": "roll_back",
  "resource": "environment",
  "tier": "reversible",
  "summary": "Put an earlier version back into production: a promote with the version named, refused `version_already_serving` where that version already serves; it moves code only. It answers 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, naming 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` names the kind `promote`, which a rollback's row carries, 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

{
  "name": "roll_back",
  "tier": "reversible",
  "scenario": "CHI-L0-09",
  "summary": "Put an earlier version back into production: a promote with the version named, refused where that version already serves. It works on an application with one environment too, naming one of production's own earlier versions. It moves code only; across a data-model change the customer chooses the data's path, and no action serves the snapshot path yet. It answers and waits as a promote does: with `wait_seconds`, up to 45, it holds its answer until it ends, once every router reaches the version named, typically 33 to 45 seconds.\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` names the kind `promote`, which a rollback's row carries, with a `started_at` later than your call. Call `roll_back` again only where 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 Required fields: ["application","version"]
/properties/application	The application id, from `list_applications`. Type: string
/properties/version	The number of a deployed version-history row of the application that is not production's serving version; the serving version is refused `version_already_serving`. Type: integer Minimum: 1
/properties/wait_seconds	Optional. The seconds, 1 to 45, the answer is held until the version-history row this call starts ends, counted from the call's arrival. Absent, the call answers 202 at once with the state `deploying`. The wait takes the application's one held place, so a concurrent held `read_status` answers at once, from its own read. A value outside that range is refused `invalid_request`, its detail naming 45 as the bound. Type: integer Minimum: 1 Maximum: 45

response

JSON pointer	Description and constraints
"" (root)	A rollback is a promote of the version named; it re-mints the production platform credential as every promote does and never the database credential (PLD-L0-43; SEC-L0-07). It answers, and holds a wait, as a promote does. It works on an application with one environment too, where the version it names is one of production's own earlier deployed rows (PLD-L0-43). Type: object Required fields: ["contract_version","application","environment","version","state","hostname"]
/properties/contract_version	Required value: 1
/properties/reference	The short reference the platform recorded this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call. Type: string Pattern: ^[0-9a-f]{10}$
/properties/summary	The answer's first member: one sentence naming 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). Type: string
/properties/application	Type: string
/properties/environment	Always `production`: a promote targets production alone (PLD-L0-43). Type: string Pattern: ^production$
/properties/version	The promoted number, an existing number of the application's history and never a fresh one (PLD-L0-43). Type: integer
/properties/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. Type: string Pattern: ^(deploying\|deployed\|failed)$
/properties/hostname	Type: string
/properties/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 (PLD-L0-63). Type: string
/properties/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` names the call that waits on it (MAPI-04; PLD-L0-63). Type: boolean
/properties/waited_ms	Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started. Type: integer Minimum: 0
/properties/outcome	Present where the wait settled: the row's `outcome` as `list_versions` answers it. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one (PLD-L0-63). Type: object
/properties/next	Present where the wait did not settle: the exact call that reads the row to its end, `read_status` naming `production`, with `wait_seconds` 45. Type: object Required fields: ["action","arguments"] Additional properties: false
/properties/next/properties/action	Required value: read_status
/properties/next/properties/arguments	Type: object Required fields: ["application","environment","wait_seconds"] Additional properties: false
/properties/next/properties/arguments/properties/application	Type: string
/properties/next/properties/arguments/properties/environment	Required value: production
/properties/next/properties/arguments/properties/wait_seconds	Required value: 45
/properties/detail	With the state `deploying`, names 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). With `deployed` or `failed`, names how the row ended; with `deployed`, it also says the health check requested the health path alone, and to request the other routes and read `read_logs` for errors. Type: string

Complete payload contract

{
  "request": {
    "type": "object",
    "required": [
      "application",
      "version"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The application id, from `list_applications`."
      },
      "version": {
        "type": "integer",
        "minimum": 1,
        "description": "The number of a deployed version-history row of the application that is not production's serving version; the serving version is refused `version_already_serving`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Optional. The seconds, 1 to 45, the answer is held until the version-history row this call starts ends, counted from the call's arrival. Absent, the call answers 202 at once with the state `deploying`. The wait takes the application's one held place, so a concurrent held `read_status` answers at once, from its own read. A value outside that range is refused `invalid_request`, its detail naming 45 as the bound."
      }
    }
  },
  "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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "summary": {
        "type": "string",
        "description": "The answer's first member: one sentence naming 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": "^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` names 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` answers 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 wait did not settle: the exact call that reads the row to its end, `read_status` naming `production`, with `wait_seconds` 45."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, names 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). With `deployed` or `failed`, names how the row ended; with `deployed`, it also says the health check requested the health path alone, and to request the other routes and read `read_logs` for errors."
      }
    },
    "description": "A rollback is a promote of the version named; it re-mints the production platform credential as every promote does and never the database credential (PLD-L0-43; SEC-L0-07). It answers, and holds a wait, as a promote does. It works on an application with one environment too, where the version it names is one of production's own earlier deployed rows (PLD-L0-43)."
  }
}

Shared contracts

Refusals: every refusal, by surface, with its cause and its remedy
schemas/wire_error.schema.json
schemas/wire_errors.json
schemas/action_payloads.json (includes shared shapes)
management_api_contract.md