restart_application
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/restart_application, with a bearer credential and the action's payload as the JSON body.
Contract description
Restart one environment's running copy, re-applying the bindings its serving version recorded, never the current manifest's, each reading its secret's current value. A binding the manifest added since takes effect at the next deploy or promote. The restart also applies the settings the platform holds now, such as the new hostname after a rename or the new connection limit after a plan change. The platform re-creates the serving compute from the version it already serves, with no build and no new version. The database keeps its data and its password, and stored files stay as they are.
With `wait_seconds`, up to 45, it holds its answer until the restart ends; without it, it answers at once and completes detached, read to its end through `read_status` or `list_versions`. A restart spends none of the plan's deploys per day. It is refused `deploy_in_flight` while a deploy, promote, or restart of the environment is in flight, and `target_environment_halted` while the environment is halted.
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 restart was made. Read `read_status` with `wait_seconds` first: the restart started where the environment's `deploy` member under `environments` names the kind `restart` with a `started_at` later than your call. Call `restart_application` again only where that read shows it did not start.
Access and action metadata
{
"name": "restart_application",
"resource": "environment",
"tier": "reversible",
"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 answers at once with the state `deploying` 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 plan'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` names the kind `restart` with a `started_at` later than your call. Call `restart_application` again only where that read shows it did not start.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": true
}
}
MCP catalog entry
{
"name": "restart_application",
"tier": "reversible",
"scenario": "CHI-L0-07",
"summary": "Restart one environment's running copy, re-applying the bindings its serving version recorded, never the current manifest's, each reading its secret's current value. A binding the manifest added since takes effect at the next deploy or promote. The restart also applies the settings the platform holds now, such as the new hostname after a rename or the new connection limit after a plan change. The platform re-creates the serving compute from the version it already serves, with no build and no new version. The database keeps its data and its password, and stored files stay as they are.\n\nWith `wait_seconds`, up to 45, it holds its answer until the restart ends; without it, it answers at once and completes detached, read to its end through `read_status` or `list_versions`. A restart spends none of the plan's deploys per day. It is refused `deploy_in_flight` while a deploy, promote, or restart of the environment is in flight, and `target_environment_halted` while the environment is halted.\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` names the kind `restart` with a `started_at` later than your call. Call `restart_application` again only where 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 Required fields: ["application","environment"] |
| / |
The application id, from `list_applications`. Type: string |
| / |
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`. Type: string Pattern: ^(development|production)$ |
| / |
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) | Answered 202 at once 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). Type: object Required fields: ["contract_version","application","environment","version","state","hostname"] |
| / |
Required value: 1 |
| / |
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}$ |
| / |
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 |
| / |
Type: string |
| / |
Type: string Pattern: ^(development|production)$ |
| / |
The number of the version the environment serves, which the restart re-creates; a restart allocates no new number. Type: integer |
| / |
`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)$ |
| / |
The environment's hostname under the application's current label, the value the re-created copy reads as its public host. Type: string |
| / |
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 |
| / |
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 |
| / |
Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started. Type: integer Minimum: 0 |
| / |
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 |
| / |
Present where the wait did not settle: the exact call that reads the row to its end, `read_status` naming the environment restarted, with `wait_seconds` 45. Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: read_status |
| / |
Type: object Required fields: ["application","environment","wait_seconds"] Additional properties: false |
| / |
Type: string |
| / |
Allowed values: ["development","production"] |
| / |
Required value: 45 |
| / |
With the state `deploying`, names 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). 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",
"environment"
],
"properties": {
"application": {
"type": "string",
"description": "The application id, from `list_applications`."
},
"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": "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": "^(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)."
},
"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": {
"enum": [
"development",
"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 the environment restarted, with `wait_seconds` 45."
},
"detail": {
"type": "string",
"description": "With the state `deploying`, names 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). 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": "Answered 202 at once 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: 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