list_applications #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/list_applications, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_list_applications.
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).
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 #
List your account's applications with each one's id, size, deployment history and feature flags. The history includes successful deploys, promotes and rollbacks, and excludes restarts and failures. Rows give the label and each environment's hostname and halted_at, null while not halted. The company's own applications have size null and unlimited true. Application states are deployed, failed after a failed first production deploy or promote, and never_deployed. Environment states are deploying, deployed, failed, never_deployed, halted or deleting, as read_status returns them. Each environment's grain is container for its own container app, or pod for a cluster shared with other applications. With function, it is a serverless environment with no compute of its own. Other tools take the id as application.
Access and action metadata #
{
"name": "list_applications",
"resource": "application",
"tier": "observe",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "The account's applications with deployment history, declared feature flags and environments. Each environment gives its state (deploying, deployed, `failed`, never_deployed, halted or deleting, as read_status returns), serving version, hostname, compute grain and halted_at, null while not halted. Deployment history includes successful deploys, promotes and rollbacks, and excludes restarts and failures.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "list_applications",
"title": "List applications",
"tier": "observe",
"scenario": "CHI-L0-09",
"summary": "List your account's applications with each one's id, `size`, deployment history and feature flags. The history includes successful deploys, promotes and rollbacks, and excludes restarts and failures. Rows give the `label` and each environment's hostname and halted_at, null while not halted. The company's own applications have size null and unlimited true. Application states are deployed, `failed` after a failed first production deploy or promote, and never_deployed. Environment states are deploying, deployed, `failed`, never_deployed, halted or deleting, as read_status returns them. Each environment's grain is container for its own container app, or pod for a cluster shared with other applications. With function, it is a serverless environment with no compute of its own. Other tools take the id as application.",
"owners": [
"PLD-L0-127",
"PLD-L0-40"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","applications"] |
| / |
Required value: 1 |
| / |
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. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
Type: array |
| / |
Type: object Required fields: ["id","name","label","created_at","kind","environments","state","version","first_live_at","last_deployed_at","deploy_count","production_deploy_count","features"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
|
| / |
$ref: #/shapes/app_size |
| / |
Type: null |
| / |
True on the company's own applications, where size is null. Absent on every other application.Type: boolean |
| / |
The application’s recorded kind, server or serverless. Earlier applications and creation with no kind use server. Serverless is not yet available. Type: string Allowed values: ["server","serverless"] |
| / |
One object per environment, development then production: its name, state, serving version, hostname, compute grain and halted_at, the halt instant or null. Type: array |
| / |
Type: object Required fields: ["name","state","version","hostname","halted_at"] |
| / |
Type: string Allowed values: ["development","production"] |
| / |
The first of these that holds: deleting while a deletion of the application or of the environment is in flight, halted where you or the platform halted the environment. Then deploying while a deploy, promote, or restart of the environment is in flight, deployed where a serving version exists, and failed where none serves and the environment's latest version row not retired by a deletion failed. It is never_deployed otherwise. These are the words read_status returns as the environment's state, read through one function; the compute provider's own word is read_status's compute_state.Type: string Allowed values: ["deploying","deployed","failed","never_deployed","halted","deleting"] |
| / |
The environment's serving version, or null. Type: ["integer","null"] |
| / |
The environment's hostname as read_status returns it: the label under the serving suffix for production, the label with -dev appended for development.Type: string |
| / |
The environment's placement grain is container, pod or function. A container is its own container app. A pod is one pod on the hosting cell's cluster, in a group of the environment's kind. A shared-1gb or unlimited production environment is container. A development environment of either size, and a shared-0.5gb production environment, is pod where its cell registers an admitting group of its kind. It is container where the cell registers none. A full group refuses the act group_full. A serverless application, not yet available to customers, has function grain with no compute before or after a version serves.Type: string Allowed values: ["container","pod","function"] |
| / |
The instant this environment was halted, in ISO 8601 form. Null while it is not halted. Type: ["string","null"] |
| / |
The application's own state: failed where production's environment reads failed, a first production deploy or promote having failed with nothing serving; otherwise deployed once production's compute exists and never_deployed before.Type: string Pattern: ^(deployed|failed|never_deployed)$ |
| / |
Type: ["integer","null"] |
| / |
The earliest non-null ended_at of a deploy or promote row that ended deployed, across both environments. Rollbacks count. Restarts and failures do not. Null before one.Type: ["string","null"] |
| / |
The latest non-null ended_at of a deploy or promote row that ended deployed, across both environments. Rollbacks count. Restarts and failures do not. Null before one.Type: ["string","null"] |
| / |
The number of deploy or promote rows that ended deployed with a non-null ended_at, across both environments. Rollbacks count. Restarts and failures do not. Zero before one.Type: integer Minimum: 0 |
| / |
The number of production deploy or promote rows that ended deployed with a non-null ended_at. Rollbacks count. Restarts and failures do not. Zero before one.Type: integer Minimum: 0 |
| / |
Feature flags from the current recorded manifest, the application's own resource rows and its environment count. Type: object Required fields: ["database","schedules","end_user_sign_in","storage","custom_domain","development_environment"] Additional properties: false |
| / |
True when the current recorded manifest declares a database. Type: boolean |
| / |
True when the current recorded manifest declares schedules. Type: boolean |
| / |
True when the current recorded manifest declares the accounts service or has a non-public audience. Type: boolean |
| / |
True when the application has a storage area of its own. Platform-held areas do not count. Type: boolean |
| / |
True when the application has a custom domain that is not being detached. Type: boolean |
| / |
True when the application has two environments. Type: boolean |
| / |
Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"properties": {}
},
"response": {
"type": "object",
"required": [
"contract_version",
"applications"
],
"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."
},
"applications": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"label",
"created_at",
"kind",
"environments",
"state",
"version",
"first_live_at",
"last_deployed_at",
"deploy_count",
"production_deploy_count",
"features"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"label": {
"type": "string"
},
"created_at": {
"type": "string"
},
"size": {
"anyOf": [
{
"$ref": "#/shapes/app_size"
},
{
"type": "null"
}
]
},
"unlimited": {
"type": "boolean",
"description": "True on the company's own applications, where `size` is null. Absent on every other application."
},
"kind": {
"type": "string",
"enum": [
"server",
"serverless"
],
"description": "The application’s recorded kind, server or serverless. Earlier applications and creation with no kind use server. Serverless is not yet available."
},
"environments": {
"type": "array",
"description": "One object per environment, development then production: its name, state, serving version, hostname, compute grain and halted_at, the halt instant or null (PLD-L0-40).",
"items": {
"type": "object",
"required": [
"name",
"state",
"version",
"hostname",
"halted_at"
],
"properties": {
"name": {
"type": "string",
"enum": [
"development",
"production"
]
},
"state": {
"type": "string",
"enum": [
"deploying",
"deployed",
"failed",
"never_deployed",
"halted",
"deleting"
],
"description": "The first of these that holds: `deleting` while a deletion of the application or of the environment is in flight, `halted` where you or the platform halted the environment (PLD-L0-66; PLD-L0-41). Then `deploying` while a deploy, promote, or restart of the environment is in flight, `deployed` where a serving version exists, and `failed` where none serves and the environment's latest version row not retired by a deletion failed. It is `never_deployed` otherwise. These are the words `read_status` returns as the environment's `state`, read through one function; the compute provider's own word is `read_status`'s `compute_state` (PLD-L0-40; PLD-L0-63)."
},
"version": {
"type": [
"integer",
"null"
],
"description": "The environment's serving version, or null."
},
"hostname": {
"type": "string",
"description": "The environment's hostname as `read_status` returns it: the label under the serving suffix for production, the label with `-dev` appended for development (SVC-L0-07)."
},
"grain": {
"type": "string",
"enum": [
"container",
"pod",
"function"
],
"description": "The environment's placement grain is `container`, `pod` or `function` (PLD-L0-127; PLD-L0-130). A `container` is its own container app. A `pod` is one pod on the hosting cell's cluster, in a group of the environment's kind. A `shared-1gb` or unlimited production environment is `container`. A development environment of either size, and a `shared-0.5gb` production environment, is `pod` where its cell registers an admitting group of its kind. It is `container` where the cell registers none. A full group refuses the act `group_full`. A serverless application, not yet available to customers, has `function` grain with no compute before or after a version serves."
},
"halted_at": {
"type": [
"string",
"null"
],
"description": "The instant this environment was halted, in ISO 8601 form. Null while it is not halted."
}
}
}
},
"state": {
"type": "string",
"pattern": "^(deployed|failed|never_deployed)$",
"description": "The application's own state: `failed` where production's environment reads `failed`, a first production deploy or promote having failed with nothing serving; otherwise `deployed` once production's compute exists and `never_deployed` before (WEB-L0-17)."
},
"version": {
"type": [
"integer",
"null"
]
},
"first_live_at": {
"type": [
"string",
"null"
],
"description": "The earliest non-null `ended_at` of a deploy or promote row that ended `deployed`, across both environments. Rollbacks count. Restarts and failures do not. Null before one."
},
"last_deployed_at": {
"type": [
"string",
"null"
],
"description": "The latest non-null `ended_at` of a deploy or promote row that ended `deployed`, across both environments. Rollbacks count. Restarts and failures do not. Null before one."
},
"deploy_count": {
"type": "integer",
"minimum": 0,
"description": "The number of deploy or promote rows that ended `deployed` with a non-null `ended_at`, across both environments. Rollbacks count. Restarts and failures do not. Zero before one."
},
"production_deploy_count": {
"type": "integer",
"minimum": 0,
"description": "The number of production deploy or promote rows that ended `deployed` with a non-null `ended_at`. Rollbacks count. Restarts and failures do not. Zero before one."
},
"features": {
"type": "object",
"description": "Feature flags from the current recorded manifest, the application's own resource rows and its environment count.",
"required": [
"database",
"schedules",
"end_user_sign_in",
"storage",
"custom_domain",
"development_environment"
],
"additionalProperties": false,
"properties": {
"database": {
"type": "boolean",
"description": "True when the current recorded manifest declares a database."
},
"schedules": {
"type": "boolean",
"description": "True when the current recorded manifest declares schedules."
},
"end_user_sign_in": {
"type": "boolean",
"description": "True when the current recorded manifest declares the accounts service or has a non-public audience."
},
"storage": {
"type": "boolean",
"description": "True when the application has a storage area of its own. Platform-held areas do not count."
},
"custom_domain": {
"type": "boolean",
"description": "True when the application has a custom domain that is not being detached."
},
"development_environment": {
"type": "boolean",
"description": "True when the application has two environments."
}
}
}
}
}
},
"detail": {
"type": "string"
}
}
}
}
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