--- title: "start" description: "Generated reference for the management action start: its description, access metadata, payload contract, and registration status." slug: /reference/actions/start order: 1 visibility: public redirects_from: [] --- # start Generated automatically from the [published contract sources](/reference/about#contract-sources). A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/start`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. **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 Call this first on a connection: in one read it returns the account your connection represents, the products the account holds, and its tzCloud applications with each environment's state\. Read the overview \(`read_context`, id `overview`\) when you need a platform rule\. For the account's sign\-in identities and your session's own details, call `read_account`; for one application's live health, call `read_status`\. ## Access and action metadata ```json { "name": "start", "resource": "account", "tier": "observe", "summary": "A connection's first read: the acting account (`id` and `standing`), the products the account holds under the profile rule (`products`), and its tzCloud applications as `list_applications` returns them (`applications`, absent where the account does not hold tzCloud), with `product_lines`, a line for each other product whose tools the connection lists and whose state `start` reads, empty where it lists none.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true } } ``` ## MCP catalog entry ```json { "name": "start", "title": "Start here", "tier": "observe", "scenario": "CHI-L0-04", "summary": "Call this first on a connection: in one read it returns the account your connection represents, the products the account holds, and its tzCloud applications with each environment's state. Read the overview (`read_context`, id `overview`) when you need a platform rule. For the account's sign-in identities and your session's own details, call `read_account`; for one application's live health, call `read_status`.", "owners": [ "MCP-08" ] } ``` ## request | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Additional properties: false | ## response | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["contract\_version","account","products","product\_lines","detail"\] | | /properties/contract\_version | Required value: 1 | | /properties/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\.

Type: string
Pattern: ^\[0\-9a\-f\]\{10\}$ | | /properties/account | The account your connection represents\. `read_account` returns the rest of its record\.

Type: object
Required fields: \["id","standing"\]
Additional properties: false | | /properties/account/properties/id | Type: string | | /properties/account/properties/standing | The account's standing, `active` or `suspended`, as `read_account` returns it\.

Type: string | | /properties/products | The products the account holds, each by the product name `read_account` lists under `profiles`\.

Type: array | | /properties/products/items | Type: string | | /properties/applications | The account's tzCloud applications as `list_applications` returns them, each with its environments and their states; absent where the account does not hold tzCloud\.

$ref: \#/shapes/list\_applications | | /properties/product\_lines | For a person's sign\-in connection, a line for each other product whose tools the connection lists and whose state start reads, read from that product's own server; empty for every other connection\.

Type: array | | /properties/product\_lines/items | Type: object
Required fields: \["product","state","door","detail"\]
Additional properties: false | | /properties/product\_lines/items/properties/product | The product, by the name `read_account` lists under `profiles`\.

Type: string | | /properties/product\_lines/items/properties/state | `read` where the product's own server returned the line's read; `refused` where it refused it, its reason in `detail`; `unavailable` where it could not be read, so the line holds no state\.

Allowed values: \["read","refused","unavailable"\] | | /properties/product\_lines/items/properties/door | The address of the product's own MCP server the line was read from, which you may also connect to directly\.

Type: string | | /properties/product\_lines/items/properties/space | Where the product keeps issues: the id of the account's default issue space, as its server gave it; null where the server refused the read\.

Type: \["string","null"\] | | /properties/product\_lines/items/properties/waiting\_for\_person | Where the product keeps issues: how many issues in the default space wait for your person, counted on a first page of at most 100; null where the server refused the read\.

Type: \["integer","null"\]
Minimum: 0 | | /properties/product\_lines/items/properties/more\_waiting | True where more issues wait for your person beyond the counted page\.

Type: boolean | | /properties/product\_lines/items/properties/detail | Type: string | | /properties/detail | Type: string | ## Complete payload contract ```json { "request": { "type": "object", "properties": {}, "additionalProperties": false }, "response": { "type": "object", "required": [ "contract_version", "account", "products", "product_lines", "detail" ], "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." }, "account": { "type": "object", "required": [ "id", "standing" ], "properties": { "id": { "type": "string" }, "standing": { "type": "string", "description": "The account's standing, `active` or `suspended`, as `read_account` returns it." } }, "additionalProperties": false, "description": "The account your connection represents. `read_account` returns the rest of its record." }, "products": { "type": "array", "items": { "type": "string" }, "description": "The products the account holds, each by the product name `read_account` lists under `profiles`." }, "applications": { "description": "The account's tzCloud applications as `list_applications` returns them, each with its environments and their states; absent where the account does not hold tzCloud.", "$ref": "#/shapes/list_applications" }, "product_lines": { "type": "array", "items": { "type": "object", "required": [ "product", "state", "door", "detail" ], "properties": { "product": { "type": "string", "description": "The product, by the name `read_account` lists under `profiles`." }, "state": { "enum": [ "read", "refused", "unavailable" ], "description": "`read` where the product's own server returned the line's read; `refused` where it refused it, its reason in `detail`; `unavailable` where it could not be read, so the line holds no state." }, "door": { "type": "string", "description": "The address of the product's own MCP server the line was read from, which you may also connect to directly." }, "space": { "type": [ "string", "null" ], "description": "Where the product keeps issues: the id of the account's default issue space, as its server gave it; null where the server refused the read." }, "waiting_for_person": { "type": [ "integer", "null" ], "minimum": 0, "description": "Where the product keeps issues: how many issues in the default space wait for your person, counted on a first page of at most 100; null where the server refused the read." }, "more_waiting": { "type": "boolean", "description": "True where more issues wait for your person beyond the counted page." }, "detail": { "type": "string" } }, "additionalProperties": false }, "description": "For a person's sign-in connection, a line for each other product whose tools the connection lists and whose state start reads, read from that product's own server; empty for every other connection." }, "detail": { "type": "string" } } } } ``` ## Shared contracts - [Refusals](/reference/refusals): every refusal, by surface, with its cause and its remedy - [schemas/wire\_error\.schema\.json](/reference/sources/schemas/wire-error-schema) - [schemas/wire\_errors\.json](/reference/sources/schemas/wire-errors) - [schemas/action\_payloads\.json](/reference/sources/schemas/action-payloads) (includes shared shapes) - [management\_api\_contract\.md](/reference/sources/management-api-contract)