create_application #

View this page as Markdown

On this page

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/create_application, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_create_application.

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 #

Creates your application. Hostnames are <label> (production) and <label>-dev (development).

A site of static files alone takes kind serverless and no size, with the reason told to the owner in one line. It runs no code. Code takes the owner's size, shared-0.5gb or shared-1gb, chosen before this call. With nobody to ask and no size in the task, shared-0.5gb is passed and the choice reported.

Both sizes cost by use. Each draws the account's monthly free usage, shared by all its applications and every other line. No money is charged while credits are not sold. read_rate_card gives rates and read_balance what remains.

submit_manifest precedes the first deploy. Production alone exists at creation. Development is added with create_environment only if the owner asks to try versions first. account-application-limit applies except under the super-admin grant or for unbilled accounts.

More about this action #

This call creates the application's record only. Its services are declared with submit_manifest before the first deploy. A new application has production alone, so that deploy serves production. Production alone is used unless the owner asks to try versions on development first, added with create_environment.

For a site of static files alone, the choice is serverless, with the reason told to the owner in one line. A serverless application is charged only for what it serves. A serverless creation takes name and kind set to serverless, with no size. It serves the files under client/ and runs no code. A serverless manifest submission declaring a database, schedule or egress host refuses 403 serverless_static_only. A deploy refuses the same declarations in the recorded manifest, or a functions/ or migrations/ folder, with that error. A storage area may be declared.

An application running code on the platform takes a server. A server has its own container and draws usage for the time it is awake. The account's owner chooses size before a server is created. With nobody to ask and no size in the task, shared-0.5gb is passed and the choice reported. A server creation takes size with kind set to server or omitted. shared-0.5gb is smaller; shared-1gb gives more memory or CPU. Each size draws the account's monthly free usage first, at its own rate. Size sets replica memory, CPU and production placement. read_plan_quotas returns the sizes' quota rows.

Both sizes cost by use. The account's monthly free usage is shared by all its applications and every other line, including storage, data transfer, email, AI and monthly items. read_balance shows what remains, including any launch bonus. During the introduction period, while credits are not sold, nothing is charged in money. When a billed account uses its whole balance, its applications pause, except unlimited and operated applications. The next month or a live grant ends the pause. An application within the account's monthly free usage needs no card.

On read_rate_card, monthly-free-usage is dollars for an account for a UTC month. Production's awake time draws server-shared-0.5gb or server-shared-1gb, each dollars for a month of awake time. A server awake for part of the month draws that part of its monthly rate. Development's awake time draws server-shared-0.5gb whatever the production size. A shared database adds database-shared, a monthly item per application. One added during a month draws for the days left; removing it gives nothing back. The server keys, any database and all other lines share the account's balance.

On production, shared-0.5gb sleeps when idle by default. On production, shared-1gb has sleep off by default, so it keeps one warm replica and is awake the whole month. The owner can change production's sleep setting. An application moved from the old Standard plan keeps that setting off. A sleeping environment stops after the idle period and takes a cold first request. An environment with sleep off is awake the whole month. Development always sleeps when idle and has no switch.

name is the readable name. label is name plus a unique key. Hostnames are <label> for production and <label>-dev for development on the platform's domain. The answer's id is the application value for later calls. The answer includes size for a server and omits it for a serverless application.

An unknown kind, a plan, a serverless creation with size, or a request naming neither size nor serverless kind refuses invalid_request before any write. A size whose quantity is unset refuses plan_quantity_unset. A creation past account-application-limit refuses account_application_limit. That limit does not apply under the super-admin grant or on an unbilled account. The answer then includes application_limit_exemption, super_admin or unbilled; otherwise that member is absent.

Access and action metadata #

{
  "name": "create_application",
  "resource": "application",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Create an application for the account.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}

MCP catalog entry #

{
  "name": "create_application",
  "title": "Create application",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Creates your application. Hostnames are `<label>` (production) and `<label>-dev` (development).\n\nA site of static files alone takes `kind` `serverless` and no `size`, with the reason told to the owner in one line. It runs no code. Code takes the owner's `size`, `shared-0.5gb` or `shared-1gb`, chosen before this call. With nobody to ask and no size in the task, `shared-0.5gb` is passed and the choice reported.\n\nBoth sizes cost by use. Each draws the account's monthly free usage, shared by all its applications and every other line. No money is charged while credits are not sold. `read_rate_card` gives rates and `read_balance` what remains.\n\n`submit_manifest` precedes the first deploy. Production alone exists at creation. Development is added with `create_environment` only if the owner asks to try versions first. `account-application-limit` applies except under the super-admin grant or for unbilled accounts.",
  "owners": [
    "ACB-L0-22",
    "PRC-L0-04",
    "ACB-L0-83",
    "ACB-L0-84",
    "PRC-L0-05",
    "ACB-L0-26"
  ]
}

request #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["name"]
Retired members: plan: plan is no longer passed: use size, shared-0.5gb or shared-1gb.
/properties/name A lowercase slug such as todo-api. Use 1 to 40 characters. Start with a lowercase letter, then use lowercase letters, digits, or hyphens. The slug becomes the readable part of the application's hostname. The platform adds a unique key.

Type: string
Pattern: ^[a-z][a-z0-9-]{0,39}$
/properties/size A server's size: shared-0.5gb or shared-1gb. It sets replica memory, CPU and production placement. read_plan_quotas returns the sizes' quota rows. The owner chooses it. With none chosen and nobody to ask, shared-0.5gb is passed and reported. A serverless application takes no size.

Type: string
Allowed values: ["shared-0.5gb","shared-1gb"]
/properties/kind The kind is server or serverless. A server has its own container and takes a size. A serverless application serves static files alone, runs no code and takes no size. Leaving kind out selects server, which also requires size.

Type: string
Allowed values: ["serverless","server"]

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","application","outcome"]
/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/application id, name, label, created_at, size, and kind. A server includes the size passed at creation. A serverless application omits size. The kind is server or serverless.

Type: object
/properties/outcome Type: string
Pattern: ^created$
/properties/application_limit_exemption Present only where the call's credential and account pass the account's application limit: super_admin under the super-admin grant, unbilled for an account carrying the mark. Absent otherwise.

Type: string
Allowed values: ["super_admin","unbilled"]
/properties/detail Says the next step, the manifest then the deploy, and that the new application has production alone, so taking it to production is a deploy. It directs the caller to use production alone unless the owner asks to try versions before they serve; only then is create_environment called before deploying, followed by promote. The page at page explains each step.

Type: string
/properties/page $ref: #/shapes/page
/properties/dashboard The full address of the new application’s dashboard page. The person who holds its account can open it after signing in.

Type: string
/properties/next Calls with action and arguments, in order: submit_manifest, deploy_command, then read_rate_card for costs. Add manifest to the first call. Read rates before deploying. A serverless creation omits deploy_command.

Type: array
/properties/next/items Type: object
Required fields: ["action","arguments"]
Additional properties: false
/properties/next/items/properties/action Allowed values: ["submit_manifest","deploy_command","read_rate_card"]
/properties/next/items/properties/arguments Type: object
Additional properties: false
/properties/next/items/properties/arguments/properties/application Type: string

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]{0,39}$",
        "description": "A lowercase slug such as `todo-api`. Use 1 to 40 characters. Start with a lowercase letter, then use lowercase letters, digits, or hyphens. The slug becomes the readable part of the application's hostname. The platform adds a unique key."
      },
      "size": {
        "type": "string",
        "enum": [
          "shared-0.5gb",
          "shared-1gb"
        ],
        "description": "A server's size: shared-0.5gb or shared-1gb. It sets replica memory, CPU and production placement. `read_plan_quotas` returns the sizes' quota rows. The owner chooses it. With none chosen and nobody to ask, shared-0.5gb is passed and reported. A serverless application takes no size."
      },
      "kind": {
        "type": "string",
        "enum": [
          "serverless",
          "server"
        ],
        "description": "The kind is server or serverless. A server has its own container and takes a size. A serverless application serves static files alone, runs no code and takes no size. Leaving kind out selects server, which also requires `size`."
      }
    },
    "x-retired": {
      "plan": "`plan` is no longer passed: use `size`, `shared-0.5gb` or `shared-1gb`."
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "outcome"
    ],
    "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."
      },
      "application": {
        "type": "object",
        "description": "id, name, label, created_at, size, and kind (ACB-L0-22). A server includes the size passed at creation. A serverless application omits size. The kind is server or serverless."
      },
      "outcome": {
        "type": "string",
        "pattern": "^created$"
      },
      "application_limit_exemption": {
        "type": "string",
        "enum": [
          "super_admin",
          "unbilled"
        ],
        "description": "Present only where the call's credential and account pass the account's application limit: `super_admin` under the super-admin grant, `unbilled` for an account carrying the mark. Absent otherwise (ACB-L0-84)."
      },
      "detail": {
        "type": "string",
        "description": "Says the next step, the manifest then the deploy, and that the new application has production alone, so taking it to production is a deploy. It directs the caller to use production alone unless the owner asks to try versions before they serve; only then is create_environment called before deploying, followed by promote (PLD-L0-96). The page at `page` explains each step."
      },
      "page": {
        "$ref": "#/shapes/page"
      },
      "dashboard": {
        "type": "string",
        "description": "The full address of the new application’s dashboard page. The person who holds its account can open it after signing in."
      },
      "next": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "action",
            "arguments"
          ],
          "properties": {
            "action": {
              "enum": [
                "submit_manifest",
                "deploy_command",
                "read_rate_card"
              ]
            },
            "arguments": {
              "type": "object",
              "properties": {
                "application": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "description": "Calls with `action` and `arguments`, in order: `submit_manifest`, `deploy_command`, then `read_rate_card` for costs. Add `manifest` to the first call. Read rates before deploying. A serverless creation omits `deploy_command`."
      }
    }
  }
}

Shared contracts #