list_versions
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/list_versions, with a bearer credential and the action's payload as the JSON body. It also accepts GET.
Contract description
List an application's version history, newest first. Each row names its environment, number, kind (deploy, promote, or restart, the last the re-creation of a serving revision under current settings by `restart_application`, a rename, or the platform), state, artifact hash, instants, and outcome. The outcome's `result` says how an ended row ended. Each row also answers whether it is serving, and whether it is promotable, which says its image still stands, not that promoting it is advised, and is false once the platform's retention has deleted the image. Each row also carries its harness hash with whether that harness is the platform's current one, which a promote keeps and a new deploy takes. Each row also records its step `timings`, and a failed build's outcome carries the build's own last lines.
The rows are the versions promotion and rollback refer to. Version numbers are one sequence per application, shared by development and production: each deploy takes the next number, and a promote, rollback, or restart row carries the number of the version it applies.
Access and action metadata
{
"name": "list_versions",
"resource": "version",
"tier": "observe",
"summary": "An application's version history, newest first: each row's environment, number, kind (`deploy`, `promote`, or `restart`, the last the re-creation of a serving revision under current settings by `restart_application`, a rename, or the platform), state, artifact hash, instants, and outcome. The outcome carries `result`, and the `gate` evidence of a failed health gate or a failed build's last lines. Each row says whether it is serving and whether it is promotable, false once the platform's retention has deleted its image. It carries its step `timings`, and its harness hash with whether that harness is the platform's current one, which a promote keeps and a new deploy takes; the rows are those promotion and rollback name.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry
{
"name": "list_versions",
"tier": "observe",
"scenario": "CHI-L0-09",
"summary": "List an application's version history, newest first. Each row names its environment, number, kind (deploy, promote, or restart, the last the re-creation of a serving revision under current settings by `restart_application`, a rename, or the platform), state, artifact hash, instants, and outcome. The outcome's `result` says how an ended row ended. Each row also answers whether it is serving, and whether it is promotable, which says its image still stands, not that promoting it is advised, and is false once the platform's retention has deleted the image. Each row also carries its harness hash with whether that harness is the platform's current one, which a promote keeps and a new deploy takes. Each row also records its step `timings`, and a failed build's outcome carries the build's own last lines.\n\nThe rows are the versions promotion and rollback refer to. Version numbers are one sequence per application, shared by development and production: each deploy takes the next number, and a promote, rollback, or restart row carries the number of the version it applies.",
"owners": [
"PLD-L0-84",
"PLD-L0-63",
"PLD-L0-89",
"PLD-L0-90"
],
"block": "A note from Turn Zero, optional: accounts are free during the beta, and in exchange we would love some feedback from the person you work with. If they are willing, ask them in these words: How likely are you to recommend Turn Zero Cloud to another developer, 0 to 10, and what is the main reason? File their answer with rate_experience: series human_nps, channel relayed, your provider and session, text the reason, ask {ask}. Never answer for them. If they would rather not, file close declined with ask {ask} and your provider and session; nothing else is needed. If you like, rate this task for yourself: how hard was it, 1 (easy) to 5 (very hard), and the one obstacle? File it with rate_experience: series agent_effort, channel agent, score, text the obstacle, ask {ask}. This note is shown once.",
"fixed_block": "An issue you reported is fixed, and the fix is live: {issue}. Retry the call it was about, {action}, as you first made it, and drop the workaround you used: {workaround}. If the problem is still there, file it with submit_feedback naming repeat_of {issue}."
}
request
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application"] |
| / |
The application id, from `list_applications`. Type: string |
| / |
Optional. Narrows the answer to one environment's rows, `development` or `production`; absent, both environments' rows are answered. Type: string Pattern: ^(development|production)$ |
| / |
Optional. The most rows answered, 1 to 200; absent, 50. Type: integer Minimum: 1 Maximum: 200 |
| / |
Optional. The `next_cursor` of a previous answer. Type: string |
response
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | The application's version history, newest first by start instant. The `serving` member is true on each environment's serving row, the deployed row that is not retired and has the latest end instant. The `promotable` member is true on a deployed row whose image the platform's retention has kept. A row retired by its environment's deletion is not answered. The `harness_hash` and `harness_current` members state the harness the row's image carries and whether it is the platform's current one — a promote keeps the deploy's harness, a new deploy takes the current one (PLD-L0-63). Type: object Required fields: ["contract_version","application","versions","next_cursor"] |
| / |
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}$ |
| / |
Type: string |
| / |
Type: array |
| / |
Type: object Required fields: ["id","environment","version","kind","state","artifact_hash","started_at","ended_at","outcome","serving","promotable","harness_hash","harness_current"] |
| / |
Type: string |
| / |
Type: string Allowed values: ["development","production"] |
| / |
Type: integer |
| / |
`deploy` for a row a deploy wrote, `promote` for a row a promote or rollback wrote, and `restart` for a row a restart wrote, carrying the serving row's number (PLD-L0-63). A restart is the re-creation of the environment's serving compute under current settings by `restart_application`, a rename, or the platform (PLD-L0-84). Type: string Allowed values: ["deploy","promote","restart"] |
| / |
Type: string Allowed values: ["deploying","deployed","failed"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Null while the row is deploying. On a failed row an object of error, the refusal's name, and detail, its sentence — or the outcome interrupted or superseded (PLD-L0-63) — with step, the step the run had reached where the process that ran it ended the row. On a row failed at the health gate (health_gate_failed) it also carries gate: probed (private_ingress or group_route, never the address), timeout_ms, polls, and probe_sequence. The probe_sequence is a run-length ledger of at most sixteen {answer, count} runs, answer an HTTP status or one of the transport words connection_refused, name_not_resolved, connection_reset, timed_out, tls_failed, and transport_error. The gate also carries last (the last non-200 answer's status and content_type, and its body's first 512 bytes with body_truncated only where answered_by is application), null where no HTTP answer was read. The gate also carries answered_by (application, intermediary, nothing, or unknown, the reading at the deadline or at an early end) and control_probe (its outcome and status, refusal, or cause). The gate also carries ended_early: true where the gate ended before its bound on one client error from the application's own process, false where it ran to its bound, and absent on a row written before the member. The gate also carries compute: state, and with detail revision {provisioning, running, health}, instance {phase, state, restarts, exit_code, last_state}, and ready, a member {unavailable: cause} where its read failed. The cause is an HTTP status word, a platform error code, or error. The whole member is {outcome: unavailable, cause} where its read failed or overran and {state: unavailable, reason} where the seam caught the failure. The gate also carries console (outcome as lines, empty, or unavailable; lines, at most forty of at most 512 bytes and 4,096 in all; truncated; since; and cause). read_status answers the same outcome whole. No member names an address, a header value, or the provider (PLD-L0-59; PLD-L0-63). Type: ["object","null"] |
| / |
How the row ended, on every ended row: `succeeded` on a deployed row, `interrupted` where the platform's process stopped or lost the run, `superseded` where a deletion ended it, and `failed` otherwise (PLD-L0-63). A `succeeded` row's declared health path answered 200 within the check's bound and, where it replaced a serving version, the routers' short resolve interval after the switch has passed. No other path is probed: a failing route shows in `read_status`' `server_errors` once a request reaches it. Type: string Allowed values: ["succeeded","failed","interrupted","superseded"] |
| / |
On a failed row, the step the run had reached when the process that ran it failed or stopped it, a platform word. The word `switching` is a live step alone, the one a replacing act stands at between its switch and its mark: a row that reached it ends `deployed`, so no failed row names it. The step is absent on a row the stale sweep ended, a superseded row, and a row written before the member (PLD-L0-63). Type: string Allowed values: ["pending_candidates","image_build","slot_guard","database_pair","issue_space","platform_credential","database_credential","declarations","realm_keys","pull_identity","compute_apply","shell_assets","health_gate","finish","switching","after_finish"] |
| / |
On a row failed `image_build_failed`: the build steps' own last lines, at most forty of at most 512 bytes and 4,096 in all, `truncated` where a bound cut them. Framing lines, registry addresses, header values, and the provider's name are left out; another address reads `[address]` and a token `[token]`. `cause` names why the log was not read (PLD-L0-90; PLD-L0-59). Type: object Required fields: ["outcome","output_tail","truncated"] Additional properties: false |
| / |
Type: string Allowed values: ["lines","empty","unavailable"] |
| / |
Type: array |
| / |
Type: string |
| / |
Type: boolean |
| / |
Type: string Allowed values: ["log_unavailable","log_timeout"] |
| / |
On a row that ended deployed, present where the environment reads no stored key for an upstream of the application: each such upstream and its key's stored name (EGW-L0-02). The act served, and the gateway refuses that upstream's calls `credential_not_in_custody` until `store_secret` stores the key at that environment's scope of the application or at the account scope. Type: array |
| / |
Type: object Required fields: ["upstream","credential_name"] |
| / |
The upstream's name. Type: string |
| / |
The stored name of the upstream's key. Type: string |
| / |
On a row that ended deployed, present where a credential the manifest's `realm` member or push entry names is one the environment's provider cannot read: each such credential and its provider (ACS-L0-09; PSH-L0-01). The act served. Until `store_secret` stores the credential at that environment's scope of the application, the sign-in method's sign-ins fail and the push provider's deliveries end `credential_unreadable`. A sign-in credential then moves into place at the manifest's next submission. Type: array |
| / |
Type: object Required fields: ["provider","credential_name"] |
| / |
The provider the credential serves: a sign-in method, `entra` or `apple`, or a push provider, `apns` or `fcm`. Type: string Allowed values: ["entra","apple","apns","fcm"] |
| / |
The credential's stored name. Type: string |
| / |
Type: boolean |
| / |
True where the row is `deployed` and its image still stands in the cell registry, so `promote` and `roll_back` can name its version. It says the image stands, not that promoting it is advised; `serving` names the version the environment runs. It is false on a `deploying` or `failed` row and on a deployed row whose image the platform's retention deleted, when a promote of that version is refused 409 `version_image_pruned`. The retention keeps the images of each environment's serving version and its twenty most recent deployed versions (PLD-L0-63). Type: boolean |
| / |
The SHA-256 of the runtime harness bundle the row's image carries, read by the platform from its own bundle at the deploy's first write and copied from the source row by a promote or rollback. It is null where the platform did not record the harness: every row written before the platform kept it, and a promote or rollback of such a row (PLD-L0-63). Type: ["string","null"] |
| / |
True where `harness_hash` is non-null and equals the harness the answering platform bakes into new images; false where it differs or is null. A promote carries the deploy's image and its harness, so a version whose harness is not current stays so in production; a new deploy takes the current harness (PLD-L0-63). Type: boolean |
| / |
The steps the row entered, in order, each with its start and end instants, a step a word of `outcome.step`'s list. The last step's `ended_at` is null while the row is deploying and where the platform's sweep or a deletion ended the row. Null on a row written before the platform kept it (PLD-L0-89). Type: ["array","null"] |
| / |
Type: object Required fields: ["step","started_at","ended_at"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
The cursor of the next page, or null on the last page. Type: ["string","null"] |
| / |
$ref: #/shapes/page |
Complete payload contract
{
"request": {
"type": "object",
"required": [
"application"
],
"properties": {
"application": {
"type": "string",
"description": "The application id, from `list_applications`."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Optional. Narrows the answer to one environment's rows, `development` or `production`; absent, both environments' rows are answered."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Optional. The most rows answered, 1 to 200; absent, 50."
},
"cursor": {
"type": "string",
"description": "Optional. The `next_cursor` of a previous answer."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"application",
"versions",
"next_cursor"
],
"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."
},
"application": {
"type": "string"
},
"versions": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"environment",
"version",
"kind",
"state",
"artifact_hash",
"started_at",
"ended_at",
"outcome",
"serving",
"promotable",
"harness_hash",
"harness_current"
],
"properties": {
"id": {
"type": "string"
},
"environment": {
"type": "string",
"enum": [
"development",
"production"
]
},
"version": {
"type": "integer"
},
"kind": {
"type": "string",
"enum": [
"deploy",
"promote",
"restart"
],
"description": "`deploy` for a row a deploy wrote, `promote` for a row a promote or rollback wrote, and `restart` for a row a restart wrote, carrying the serving row's number (PLD-L0-63). A restart is the re-creation of the environment's serving compute under current settings by `restart_application`, a rename, or the platform (PLD-L0-84)."
},
"state": {
"type": "string",
"enum": [
"deploying",
"deployed",
"failed"
]
},
"artifact_hash": {
"type": "string"
},
"started_at": {
"type": "string"
},
"ended_at": {
"type": [
"string",
"null"
]
},
"outcome": {
"type": [
"object",
"null"
],
"description": "Null while the row is deploying. On a failed row an object of error, the refusal's name, and detail, its sentence — or the outcome interrupted or superseded (PLD-L0-63) — with step, the step the run had reached where the process that ran it ended the row. On a row failed at the health gate (health_gate_failed) it also carries gate: probed (private_ingress or group_route, never the address), timeout_ms, polls, and probe_sequence. The probe_sequence is a run-length ledger of at most sixteen {answer, count} runs, answer an HTTP status or one of the transport words connection_refused, name_not_resolved, connection_reset, timed_out, tls_failed, and transport_error. The gate also carries last (the last non-200 answer's status and content_type, and its body's first 512 bytes with body_truncated only where answered_by is application), null where no HTTP answer was read. The gate also carries answered_by (application, intermediary, nothing, or unknown, the reading at the deadline or at an early end) and control_probe (its outcome and status, refusal, or cause). The gate also carries ended_early: true where the gate ended before its bound on one client error from the application's own process, false where it ran to its bound, and absent on a row written before the member. The gate also carries compute: state, and with detail revision {provisioning, running, health}, instance {phase, state, restarts, exit_code, last_state}, and ready, a member {unavailable: cause} where its read failed. The cause is an HTTP status word, a platform error code, or error. The whole member is {outcome: unavailable, cause} where its read failed or overran and {state: unavailable, reason} where the seam caught the failure. The gate also carries console (outcome as lines, empty, or unavailable; lines, at most forty of at most 512 bytes and 4,096 in all; truncated; since; and cause). read_status answers the same outcome whole. No member names an address, a header value, or the provider (PLD-L0-59; PLD-L0-63).",
"properties": {
"result": {
"type": "string",
"enum": [
"succeeded",
"failed",
"interrupted",
"superseded"
],
"description": "How the row ended, on every ended row: `succeeded` on a deployed row, `interrupted` where the platform's process stopped or lost the run, `superseded` where a deletion ended it, and `failed` otherwise (PLD-L0-63). A `succeeded` row's declared health path answered 200 within the check's bound and, where it replaced a serving version, the routers' short resolve interval after the switch has passed. No other path is probed: a failing route shows in `read_status`' `server_errors` once a request reaches it."
},
"step": {
"type": "string",
"enum": [
"pending_candidates",
"image_build",
"slot_guard",
"database_pair",
"issue_space",
"platform_credential",
"database_credential",
"declarations",
"realm_keys",
"pull_identity",
"compute_apply",
"shell_assets",
"health_gate",
"finish",
"switching",
"after_finish"
],
"description": "On a failed row, the step the run had reached when the process that ran it failed or stopped it, a platform word. The word `switching` is a live step alone, the one a replacing act stands at between its switch and its mark: a row that reached it ends `deployed`, so no failed row names it. The step is absent on a row the stale sweep ended, a superseded row, and a row written before the member (PLD-L0-63)."
},
"build": {
"type": "object",
"required": [
"outcome",
"output_tail",
"truncated"
],
"properties": {
"outcome": {
"type": "string",
"enum": [
"lines",
"empty",
"unavailable"
]
},
"output_tail": {
"type": "array",
"items": {
"type": "string"
}
},
"truncated": {
"type": "boolean"
},
"cause": {
"type": "string",
"enum": [
"log_unavailable",
"log_timeout"
]
}
},
"additionalProperties": false,
"description": "On a row failed `image_build_failed`: the build steps' own last lines, at most forty of at most 512 bytes and 4,096 in all, `truncated` where a bound cut them. Framing lines, registry addresses, header values, and the provider's name are left out; another address reads `[address]` and a token `[token]`. `cause` names why the log was not read (PLD-L0-90; PLD-L0-59)."
},
"credentials_missing": {
"type": "array",
"description": "On a row that ended deployed, present where the environment reads no stored key for an upstream of the application: each such upstream and its key's stored name (EGW-L0-02). The act served, and the gateway refuses that upstream's calls `credential_not_in_custody` until `store_secret` stores the key at that environment's scope of the application or at the account scope.",
"items": {
"type": "object",
"required": [
"upstream",
"credential_name"
],
"properties": {
"upstream": {
"type": "string",
"description": "The upstream's name."
},
"credential_name": {
"type": "string",
"description": "The stored name of the upstream's key."
}
}
}
},
"provider_credentials_missing": {
"type": "array",
"description": "On a row that ended deployed, present where a credential the manifest's `realm` member or push entry names is one the environment's provider cannot read: each such credential and its provider (ACS-L0-09; PSH-L0-01). The act served. Until `store_secret` stores the credential at that environment's scope of the application, the sign-in method's sign-ins fail and the push provider's deliveries end `credential_unreadable`. A sign-in credential then moves into place at the manifest's next submission.",
"items": {
"type": "object",
"required": [
"provider",
"credential_name"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"entra",
"apple",
"apns",
"fcm"
],
"description": "The provider the credential serves: a sign-in method, `entra` or `apple`, or a push provider, `apns` or `fcm`."
},
"credential_name": {
"type": "string",
"description": "The credential's stored name."
}
}
}
}
}
},
"serving": {
"type": "boolean"
},
"promotable": {
"type": "boolean",
"description": "True where the row is `deployed` and its image still stands in the cell registry, so `promote` and `roll_back` can name its version. It says the image stands, not that promoting it is advised; `serving` names the version the environment runs. It is false on a `deploying` or `failed` row and on a deployed row whose image the platform's retention deleted, when a promote of that version is refused 409 `version_image_pruned`. The retention keeps the images of each environment's serving version and its twenty most recent deployed versions (PLD-L0-63)."
},
"harness_hash": {
"type": [
"string",
"null"
],
"description": "The SHA-256 of the runtime harness bundle the row's image carries, read by the platform from its own bundle at the deploy's first write and copied from the source row by a promote or rollback. It is null where the platform did not record the harness: every row written before the platform kept it, and a promote or rollback of such a row (PLD-L0-63)."
},
"harness_current": {
"type": "boolean",
"description": "True where `harness_hash` is non-null and equals the harness the answering platform bakes into new images; false where it differs or is null. A promote carries the deploy's image and its harness, so a version whose harness is not current stays so in production; a new deploy takes the current harness (PLD-L0-63)."
},
"timings": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"required": [
"step",
"started_at",
"ended_at"
],
"properties": {
"step": {
"type": "string"
},
"started_at": {
"type": "string"
},
"ended_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "The steps the row entered, in order, each with its start and end instants, a step a word of `outcome.step`'s list. The last step's `ended_at` is null while the row is deploying and where the platform's sweep or a deletion ended the row. Null on a row written before the platform kept it (PLD-L0-89)."
}
}
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "The cursor of the next page, or null on the last page."
},
"page": {
"$ref": "#/shapes/page"
}
},
"description": "The application's version history, newest first by start instant. The `serving` member is true on each environment's serving row, the deployed row that is not retired and has the latest end instant. The `promotable` member is true on a deployed row whose image the platform's retention has kept. A row retired by its environment's deletion is not answered. The `harness_hash` and `harness_current` members state the harness the row's image carries and whether it is the platform's current one — a promote keeps the deploy's harness, a new deploy takes the current one (PLD-L0-63)."
}
}
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