---
title: Author the manifest
description: Write or change your application's manifest, submit it, declare scheduled work, and correct a refusal at the path it names.
slug: /guides/author-the-manifest
order: 1
visibility: public
redirects_from: []
---

# Author the manifest

Declare the services and settings your app needs in its manifest, the configuration you submit to Turn Zero Cloud. Read this page before the first deploy, when adding a service, or when a manifest submission is rejected.

Prompt:

> Get this app ready to deploy. It has a database, users sign in, it calls Stripe, and anyone can use it.

Also works:

- "Let users upload their receipts."
- "Run the daily report every morning at 6am UTC, and show me how to tell whether it ran."

The manifest declares your application's services, allowed outbound hosts, and audience. A server also declares its health path. For static files alone, follow [Publish a static site](/cloud/guides/publish-a-static-site/); that route needs no health path or start command. In a local project, your AI tool keeps it in `manifest.json` and submits it with `submit_manifest`. In an AI chat without a project folder, submit the manifest directly; see [Deploy from a chat](/cloud/getting-started/build-an-app-from-a-chat/#3-declare-the-services-and-libraries).

Read [What you need](#what-you-need) and [Before your AI starts](#before-your-ai-starts), then follow [Steps](#steps) to write and submit the manifest. The steps also cover [health paths](#choosing-the-health-path), [stored settings](#bind-a-stored-value-to-a-setting), [WebSockets](#accept-websocket-connections) and [scheduled work](#run-scheduled-work). [Expected result](#expected-result) explains the response; [Refusals](#refusals) gives the remedies.

## What your AI tool does

- Reads the `manifest-author` [skill](/cloud/concepts/glossary/#skill) (`read_context`, id `skill:manifest-author`) and follows it, with the `schedule` skill for scheduled work and the `add-service` skill for a service added later.
- Reads the manifest schema, published as the `context://manifest_schema` [resource](/cloud/concepts/glossary/#resource). Without that connection, it reads the same file at `https://turnzero.ai/cloud/reference/sources/schemas/manifest.schema.json`.
- In a local project, writes the `packages` member from the project's `system/manifest.json`, as [Use the library](/cloud/guides/use-the-library/#7-the-rows-in-the-manifest-member) describes.
- In a local project, keeps the manifest as `manifest.json`, and submits it again after each edit, except an edit to its `application` member alone, which declares nothing.
- To preview an edit, calls `check_manifest` with the whole manifest. It changes nothing and lists the paths added, removed, and changed. Unlike a submission, this check returns no `next` calls or `settings` rows.
- Asks you what the application uses before it writes the manifest, and asks for no browser approval.

## What you need

- A description, in your own words, of what your application uses: which managed services, the outside services it calls, and who is allowed to use it. For a server, include its health check address.

## Before your AI starts

**For the AI tool:** Check the following before starting.

- A connected, signed-in AI tool ([Connect your AI assistant](/cloud/getting-started/connect-your-tool/)).
- The application's identifier from `list_applications`. A new application is created with `create_application`, as step 1 (Create the application) of [Deploy from your computer](/cloud/getting-started/deploy-an-application/) describes.
- For scheduled work, the common limits: 25 schedules at least one minute apart. `read_plan_quotas` returns them for either size.

## Steps

For a refused submission, see [Refusals](#refusals). For a failed deployment, see [Deploys](/cloud/troubleshooting/deploys/).

Add the service a feature needs and resubmit the whole manifest. [The manifest](/cloud/concepts/the-manifest/) explains each field. For a server, the manifest sets neither a start command nor a port: the image build installs runtime dependencies when present, `npm start` runs the server, and the server listens on `PORT`.

A server application runs on Node.js 24; the platform ignores `engines` in `package.json`. The manifest accepts no `name`, `runtime` or `start` field. The install command is `npm install --omit=dev`.

Without a `start` script in the root `package.json`, npm uses the root `server.js`. The platform sets `PORT=8080`, and `PORT` is reserved. [What a deployed application needs](/cloud/concepts/what-a-deployed-application-needs/) describes these requirements together.

### A manifest that works

This manifest declares a database and sign-in, the health path, one outside host, an audience open to everyone, two library packages, and a stored value bound to a setting.

```json
{
  "manifest_version": 1,
  "services": [
    { "kind": "database" },
    { "kind": "accounts" }
  ],
  "health": "/health",
  "region": "usa",
  "egress": ["api.stripe.com"],
  "audience": { "kind": "public" },
  "packages": [
    { "name": "database", "version": "0.15.0" },
    { "name": "account", "version": "0.23.3" }
  ],
  "settings": {
    "STRIPE_WEBHOOK_SECRET": { "secret": "stripe-webhook-secret" }
  }
}
```

For a server that needs no managed services, outside hosts or library packages, this is a complete manifest:

```json
{
  "manifest_version": 1,
  "services": [],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": []
}
```

This complete manifest declares a database with no library package; [connect with a PostgreSQL driver](/cloud/guides/add-a-database/#without-the-database-package).

```json
{
  "manifest_version": 1,
  "services": [
    { "kind": "database" }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": []
}
```

This complete manifest declares a database, an invited audience with sign-in by email code, and the non-secret setting `SITE_TITLE` as a plain `value`. Invite each person as [Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/) describes.

```json
{
  "manifest_version": 1,
  "services": [
    { "kind": "database" },
    { "kind": "accounts" }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "invited" },
  "realm": { "sign_in_methods": ["email"] },
  "packages": [],
  "settings": {
    "SITE_TITLE": { "value": "Team notes" }
  }
}
```

The server must still answer at `/health`, as [Choosing the health path](#choosing-the-health-path) explains.

Your AI tool submits the chosen manifest with `submit_manifest`, giving the application's identifier as `application` and this object as `manifest`. Each submission records the whole manifest, so your AI tool always sends all of it. The platform reads no file on your computer, so the call carries the manifest itself. [Expected result](#expected-result) describes the response.

A deploy runs under the manifest `submit_manifest` recorded. The project's `manifest.json` goes into the [artifact](/cloud/concepts/glossary/#artifact) the deploy uploads. The copy in the artifact is optional: the deploy compares it with the recorded manifest and never uses it. Where the two differ, the deploy returns `manifest_notice` and refuses nothing. The optional `application` member, the lowercase UUID of the application the folder deploys to, declares nothing: the platform checks its form alone, and the comparison leaves it out on both sides.

`submit_manifest`, `deploy`, and `run_schedule` are [reversible-tier](/cloud/concepts/glossary/#management-action-tier) actions, so none needs your approval in the browser. `deploy` and `run_schedule` start work that finishes in the background. With `wait_seconds`, each response waits until that work ends, for at most 45 seconds; otherwise the tool reads the outcome with `read_status` and `read_schedules`.

In a local project, your AI tool writes the `packages` member from `system/manifest.json` at each submission; [Use the library](/cloud/guides/use-the-library/#7-the-rows-in-the-manifest-member) describes the copy and shows a row beside its entry. The platform keeps the member as you submit it and never reads `system/manifest.json`, so a list written by hand stands until your AI tool's next copy replaces it; keep none by hand. Without a folder manifest, your AI tool enters the names and versions from `read_library` with no `entry` instead, as [Use the library](/cloud/guides/use-the-library/#7-the-rows-in-the-manifest-member) describes.

The required `packages` member lists copied library packages, not the services the application calls. An application using the [storage HTTP routes](/cloud/guides/store-files/) without the Storage package lists no Storage row; with no library packages, it declares `"packages": []`.

#### Resolve a package notice

Each deploy compares the list with the package copies under the zip's `lib/`. Its `manifest_notice` lists each copy whose `turnzero.entry` and `version` the list does not contain, and each copy it left unread or could not compare ([What the deploy zip holds](/cloud/concepts/what-the-deploy-zip-holds/#what-the-zip-contains)). A `package.json` object with no `turnzero`, or with a `turnzero` object that has no `entry`, such as your own package's, triggers no notice.

Where the zip's manifest matches the recorded one and every package copy can be read, compared, and paired with its recorded row, the deploy returns no `manifest_notice`.

When the notice names a copy absent from `packages`, your AI tool checks whether the application still uses it. A direct HTTP call to the platform's [AI Allowance route](/cloud/backend-packages/ai-allowance/#direct-http-requests) uses no package copy, so removing the copy does not remove that route.

The package's Lifecycle, Migration, and Removal section is in `features/<name>/<name>.md`, under the project's library folder (normally `system/`). Before deleting that folder, read any removal directions in the prose before the section's first Migration entry. Read its Migration entries when changing versions. Without a library folder, read the document through `read_library` with `entry` and `file` ([Read what is published](/cloud/guides/use-the-library/#1-read-what-is-published)).

For a copy the application still uses, your AI tool compares the copy's version with its row in `system/manifest.json`. If the versions differ, it gets the entry's `library take` command from `read_library` and runs it again ([Use the library, step 3: Add an entry to the library folder](/cloud/guides/use-the-library/#3-add-an-entry-to-the-library-folder)). It then writes `packages` from `system/manifest.json`, calls `submit_manifest`, and deploys again.

Without a folder manifest, your AI tool corrects `packages` using the names and versions from `read_library`, then submits the manifest and deploys again.

For a package the application no longer uses, your AI tool removes its `lib/<name>/` folder, its `file:` dependency from `package.json`, and any imports of it. Where the project has a library folder, it also removes the entry's `system/features/<name>/` folder and its row in `system/manifest.json` together. It then rewrites `packages` from the remaining rows. Without a folder manifest, it removes the package's row from `packages` directly.

Removing the copy changes no other manifest member or platform resource. Follow any removal directions in the prose before that section's first Migration entry for the services, upstreams, or egress declarations it needed. Keep those another part of the application still uses.

After removing a package from a local project, your AI tool runs `npm install` in the application folder to refresh `package-lock.json` and `node_modules`. If it fails, correct the cause its error names and run it again before submitting. In Windows PowerShell, run npm as [What your computer needs](/cloud/getting-started/prerequisites/#windows-powershell) describes.

Once the install succeeds, it calls `submit_manifest` with the corrected manifest. A notice belongs to the deploy that returned it. The correction may be submitted while it runs and changes no deploy already started. That deploy uses the package copy in its zip under the previously recorded manifest. Follow the package's Migration entry for any step the version change needs.

Wait for that deploy to end through `read_status` with `wait_seconds` before deploying the correction. A new deploy counts toward the daily quota. A refusal adds no version. Repeating the same accepted deploy while it is in flight can return that run. After it ends, a fresh accepted deploy creates a new version, even from the same zip ([Checks before a deploy](/cloud/getting-started/deploy-an-application/#checks-before-a-deploy)).

`turnzero library take` updates `packages` in the application manifest after each download. If no manifest exists, it creates one in the [application folder](/cloud/guides/use-the-library/#7-the-rows-in-the-manifest-member). Where that member differs from the recorded manifest, a zip carrying it also draws a `manifest_notice` naming `packages`. Submit the updated manifest before deploying.

The manifest declares no environments. A new application has one, `production`, and `create_environment` adds `development` ([Test in development, then promote](/cloud/guides/turn-on-development-and-promote/#turn-the-development-environment-on)). A manifest with an `environments` member is refused `environment_unsupported`.

Paths that begin with `/__account/` or `/__router/` belong to the platform on every application address, so build no routes under them. The platform reads a request's path as your code might, with its escapes decoded, its `..` segments resolved, and its letter case ignored. So a request naming either prefix in another form never reaches your application. A manifest that names such a path, as a scheduled job's handler, the health path, or a path open without sign-in, is refused.

### Reading a refusal

A refusal before the manifest is recorded changes nothing. A validation refusal, `manifest_invalid`, lists the JSON paths to correct in its `violations` member, such as `/egress/3` for a malformed hostname. Your AI tool corrects each path and submits the whole manifest again.

The platform checks each service entry and the audience against the rules for its `kind`. It reports only those rules' violations. For example, a schedule named `Hourly Tick` is refused with one line, at `/services/0/schedules/0/name`, giving the naming rule. Where no kind matches, one line at its `kind` path lists the available kinds.

An entry of the audience's `session_free_paths`, or of `upstreams`, that breaks a rule is refused at its own path, such as `/audience/session_free_paths/0` or `/upstreams/openai/base_url`. The line names the rule, or for an upstream the refusal `declare_outbound_api` would give, such as `refused_platform_host`. Every entry's line comes in the same response, and nothing is recorded.

Some refusals give a cause instead of a path, before anything is provisioned: `region_unavailable`, `declared_tenant_contradicts_route`, `declared_audience_contradicts_route`, and the refusals of a binding in `settings`. The one region available is `usa`. The schema also lists `europe`, `uk`, and `global`, and a submission naming one is refused `region_unavailable`.

Some refusals come after the manifest is recorded, such as `database_provisioning_failed` when the database setup did not finish. The response says the manifest is recorded, and its `detail` lists what was set up and what was not. Read it, then submit again to complete the setup. A submission is safe to repeat, after a partial failure among other cases: it records the manifest again, confirms what stands, and mints nothing it already minted.

### The guide for each part of the manifest

Each part of the manifest below has a guide for its task, which shows that part in use. The [manifest schema's reference page](/cloud/reference/sources/schemas/manifest-schema/) gives the rules for each.

| In the manifest | Guide for the task |
| --- | --- |
| The `database` service | [Add a database](/cloud/guides/add-a-database/) |
| The `accounts` service, with `audience` and `realm` | [Add sign-in to your app](/cloud/guides/add-sign-in-to-your-app/) |
| The `object_storage` service | [Store files](/cloud/guides/store-files/) |
| The `push` service | [Send push notifications](/cloud/guides/send-push-notifications/) |
| The `schedule` service | [Add a scheduled job](/cloud/guides/add-a-scheduled-job/), and [Run scheduled work](#run-scheduled-work) below |
| The `issue_tracking` service | [Issue Tracking](/cloud/backend-packages/tztrack/) |
| The `health` path | [Choosing the health path](#choosing-the-health-path) below |
| The `smoke_paths` member | [Listing smoke paths](#listing-smoke-paths) below |
| The `egress` list | [Writing the egress list](#writing-the-egress-list) below |
| The `settings` member | [Bind a stored value to a setting](#bind-a-stored-value-to-a-setting) and [Set a value that is not secret](#set-a-value-that-is-not-secret) below |
| The `upstreams` member | [Call an external API with an API key](/cloud/guides/call-an-external-api-with-an-api-key/) |
| The `websockets` member | [Use WebSockets](/cloud/guides/use-websockets/) |
| The `packages` member | [Use the library](/cloud/guides/use-the-library/) |
| The AI allowance needs no member of its own, `egress` entry or upstream. Its package needs a `packages` entry; a direct call needs none. | [Call an AI model](/cloud/guides/call-an-ai-model-under-the-allowance/) |
| The `application` member | [The members](/cloud/concepts/the-manifest/#the-members) of the manifest concept page |

### Choosing the health path

An application whose zip declares its own start must declare `health`. That means a root `package.json` with `scripts.start`, or a root `server.js`. Without `health`, a deploy, promote, rollback or redeploy is refused 400 `health_path_undeclared`. If either environment has a server, running or halted, or a server application's deploy, promote or redeploy is in flight, `submit_manifest` and `check_manifest` refuse a manifest without `health` the same way. No version is recorded, no deploy is counted, and no build or compute act runs.

The health path is an absolute path on the application's own address, conventionally `/health`, and never a full URL. At each deploy and promote, the platform requests it every three seconds until it returns status 200 exactly three times in a row, for up to 180 seconds, and follows no redirect. A 503 or a connection error between them starts the count again. [The deploy health check](/cloud/concepts/the-deploy-health-check/) describes the probes, when the check ends early, and the evidence a failed check keeps.

The check reads only the status code. The body can hold `APP_VERSION`, other fields, or nothing. Where the check fails, the deploy's record keeps the first 512 bytes of the last non-200 body as evidence.

The path in the manifest must be the path your server routes, character for character. `/health` and `/healthz` are two different paths, and a server that routes one fails the check for the other.

Serve the path from the backend's own server, from the moment the server listens. Return 503 until the application can take requests, never a 4xx, then 200. A route mounted late then never ends the check early, because a 503 never counts toward it. A server with a database waits to listen until its migrations finish, so a failed migration ends the process before it serves: until it listens, the check treats it as starting and keeps waiting.

For an environment that runs no version yet, the platform refuses the deploy `health_path_unserved` before anything is built, where no source file of the zip names the path's last segment. The turnzero command makes that reading before its upload: it prints the same refusal and ends with status 3, with nothing uploaded. For an environment that already runs a version, the command only warns.

The segment counts with its slash, as in `'/health'`, or bare inside quotes, as in `@Controller('health')`. A file whose own path holds it, such as `routes/health.js`, counts too. `package.json` and the lock files never count. Documentation counts only where its own path ends with the whole health path, such as `public/health.txt` for `/health.txt`. Any source file that names the path passes, a comment included.

Under an `invited` or `workforce` audience, the platform's own check still reaches the health path. It calls your application from inside the platform and never passes through the sign-in check. A request to the health path from outside, without a session, is treated like a request to any other path. It is refused 401 `authentication_required`, or sent to the sign-in page in a browser.

To open the health path to everyone, list it in the audience's `session_free_paths`. Anyone can then read whatever the path returns, so return nothing there you would not publish. Two limits apply to the list: `/` alone is refused, and a listed path also opens every path below it. [Make sign-up invitation-only, step 1 (Choose who may sign up)](/cloud/guides/make-sign-up-invitation-only/#1-choose-who-may-sign-up) gives the list's other rules.

Where the manifest declares `health`, the `health` member of `submit_manifest`'s response says whether the path is gated: its `gated` is `true` where a request from outside without a session is refused. It is not the deploy's own check, the `health_gate` step `read_status` shows, which calls the path from inside the platform whatever `gated` says.

### Listing smoke paths

`smoke_paths` is an optional list of routes to check before a deploy or promote sends traffic to the new version. Use it for important `GET` routes that read data without changing it, for example `"smoke_paths": ["/api/items", "/account"]`. After the health check passes, the platform requests each listed path in order. Leave it out to check only the health path.

Each entry is a path written like the health path: it starts with `/`, holds no space, and is never a full URL. The list holds one to five different paths. A path under `/__account/` or `/__router/` is refused, because those prefixes belong to the platform.

Smoke checks share one 30-second deadline across all listed paths. A probe fails on 404, a status of 500 or above, or no response; other statuses, including redirects, 400, and 401, pass. Failed probes are retried every three seconds while time remains.

Choose the routes whose crash should stop a deploy or a promote before it switches:

- List only routes that answer `GET`. A route with no `GET` handler often answers 404, which fails the check.
- List only routes that change nothing on `GET`. On a promote they run against production's data and secrets.
- List routes that begin their response within ten seconds.

The smoke requests reach the new copy directly, as the health check's do, so an `invited` or `workforce` audience needs no `session_free_paths` entry for them. A rollback, a restart, and a promote of the version production already serves request no smoke path. [Checking your other routes](/cloud/concepts/the-deploy-health-check/#checking-your-other-routes) describes the check and the evidence a failed one keeps.

Where a deploy fails with `smoke_path_failed`, fix the route and deploy again. Or remove the path from `smoke_paths` and submit the manifest again.

### Writing the egress list

List every host the backend calls on the open network. Write each as an exact lowercase hostname, or as a host family with one leading wildcard label. `*.example.com` covers every name below `example.com` at any depth, but not `example.com` itself; list that separately if the backend calls it.

Write no scheme, port, path, or IP address: the tunnel reaches port 443 only ([Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/)). For an API's stored key, use a [declared upstream](/cloud/guides/call-an-external-api-with-an-api-key/) by default. The gateway connects to that host, so it needs no entry in `egress`.

For a client whose host is fixed in code the task forbids changing, bind its key and list that host in `egress`. Follow [the binding exception](/cloud/getting-started/store-a-secret/#the-rule-in-code). If an entry admits a declared upstream's host, `tzcloud_submit_manifest` names it in `egress_notice`. The platform's own endpoints need no entry: the database and storage the manifest's services provision, and the platform's origin, which serves the egress gateway, sign-in verification, and the actions available to the platform credential.

While the application is in observe mode, `read_logs` with `source: "egress"` and `filter: "undeclared"` shows the hosts it reached that the list does not include. Add the ones that belong before platform staff move the application to enforce mode.

### Bind a stored value to a setting

Your code reads some stored values directly, such as the sample's Stripe webhook signing secret. The optional `settings` member binds each one to a setting. Each key is the setting name, and `secret` is the name the value is stored under. `settings` has at most fifty entries. A value that is not secret takes the `value` form instead, as [Set a value that is not secret](#set-a-value-that-is-not-secret) describes.

Store the value with `store_secret` under the same name, at each environment's scope of the application, as [Store a secret](/cloud/getting-started/store-a-secret/#2-supply-the-value-without-exposing-it) describes. Each deploy and promote reads the value stored for its environment and sets it in the container. A replaced value takes effect at the environment's next deploy or promote, or at a `restart_application` where the [running copy](/cloud/concepts/glossary/#running-copy) already has the binding. [Replace a value](/cloud/getting-started/store-a-secret/#3-replace-a-value) gives a replacement's steps and how to check that it reached the running copy.

The sample's binding has three parts, the same example [Store a secret](/cloud/getting-started/store-a-secret/#worked-example-a-webhook-signing-secret) follows. First your AI tool stores the secret: it calls `store_secret` with these members and runs the command the call returns.

```json
{
  "name": "stripe-webhook-secret",
  "application": "<application id>",
  "environment": "production",
  "value_file": "../secrets/stripe-webhook-secret.txt"
}
```

Then the manifest's `settings` binds the stored name to the setting, as the sample above does.

```json
"settings": {
  "STRIPE_WEBHOOK_SECRET": { "secret": "stripe-webhook-secret" }
}
```

From the next deploy, the code reads the value from its setting.

```js
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
```

The submission's `settings` rows say, per setting and environment the application has, whether the name is stored there yet. A deploy or promote is refused `setting_secret_missing` while its environment's value is missing.

A setting name is an upper-case letter, then upper-case letters, digits, or underscores, ending in a letter or a digit, at most 64 characters. A name the platform reserves is refused `manifest_invalid` at the setting's own path. That covers any name under `TURNZERO_`, `APP_`, `HOSTING_`, `EGRESS_`, `ROUTER_`, `NODE_`, or `NPM_`, and `PORT`, `PATH`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`.

Some stored names are never bound, and the [Refusals](#refusals) table gives each cause:

- a name at account scope or at another application's scope;
- a name the platform created, such as the platform credential;
- an upstream's key, which the gateway applies and never gives to the application;
- a sign-in method's or a push provider's credential.

The same rule applies when configuring a credential. `configure_app_sign_in` and `configure_push` refuse a stored name bound to a setting, with `name_bound_to_setting`. `declare_outbound_api` refuses it with `upstream_key_is_bound`. A binding counts while the manifest's `settings` names it, and while a running copy has it, until that environment's next deploy or promote of a manifest without it. A deploy, promote, or redeploy in flight that recorded it counts too, until it ends.

A local run gets no bound value, because no call returns a stored value: the provision command writes the platform's own settings alone. Give a bound setting a local value on a line of your own in `.env`, or in your shell.

For an outbound API key, use a declared upstream by default. The gateway keeps the key out of the container, and a replacement needs no redeploy. Bind the key only for [the fixed-host exception](/cloud/getting-started/store-a-secret/#the-rule-in-code).

### Set a value that is not secret

A setting your code reads that is not secret, such as a page title or a feature flag, goes in `settings` as `{"value": "<text>"}`. Each deploy and promote sets the value in the container as a plain setting. The value is the same in every environment.

```json
"settings": {
  "SITE_TITLE": { "value": "Receipts" }
}
```

The code reads it from its setting, `process.env.SITE_TITLE`, as it reads a bound one.

Each entry of `settings` holds exactly one of `secret` and `value`. A value is text of at most 4,096 characters, and it may be empty. It holds no line break and no other control character: a value of several lines, such as a key or a certificate, is a secret. An entry that is not exactly one of the two forms, or whose value breaks these bounds, is refused `manifest_invalid` at its own path, such as `/settings/SITE_TITLE`. Its violation names both forms and never repeats the value.

The setting name follows a binding's rules above, and it may not be a name an upstream's `sdk_settings` sets. A name that breaks either rule is also refused `manifest_invalid` at its own path.

Never put a secret in `value`. The recorded manifest and the record of each version that applied the value keep it as written, so a credential put there stays on those records after the manifest is corrected. Store a secret with `store_secret` and bind its name, as [Bind a stored value to a setting](#bind-a-stored-value-to-a-setting) describes. If a credential was put in `value`, store it under a name, bind that name, and replace the credential with its provider.

To use different values in development and production, store each environment's value under the same name at its own application scope. Bind that name even if the value is not secret. Your code can also choose a value by `APP_ENVIRONMENT`.

A changed plain value takes effect at that environment's next deploy or promote. A restart reapplies the running version's recorded value. A rollback reapplies the value the selected version last used in production. If production never ran that version, the rollback uses the value recorded by its deploy.

Until the next deploy or promote, `read_status` lists the changed setting by name alone in that environment's `bound_not_applied`. The submission's `settings` rows omit plain settings because no stored value is read for them.

`turnzero provision` writes no line for a plain setting. For a local run, copy the value from the manifest into `.env` ([Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/)).

### Declare an upstream in the manifest

An upstream is an outside API your backend calls through the platform's gateway, which adds the stored key on the way. The optional `upstreams` member declares each one in the manifest. Each key is the upstream's name, and each entry takes the members `declare_outbound_api` takes except `application`. [Call an external API with an API key](/cloud/guides/call-an-external-api-with-an-api-key/#declare-in-the-manifest) gives the task, the entry's rules, and the call through the gateway.

```json
{
  "manifest_version": 1,
  "services": [],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": [],
  "upstreams": {
    "openai": {
      "base_url": "https://api.openai.com",
      "credential_name": "openai-key",
      "auth_header": "Authorization",
      "auth_format": "Bearer {value}",
      "sdk_settings": { "base_url": "OPENAI_BASE_URL", "key": "OPENAI_API_KEY", "base_path": "/v1" }
    }
  }
}
```

An upstream's `sdk_settings` is not the manifest's top-level [`settings`](#bind-a-stored-value-to-a-setting): `settings` gives your code its own values, and `sdk_settings` gives an unchanged SDK the gateway's address and, with a `key`, an [egress key](/cloud/concepts/glossary/#egress-key).

Each submission declares every entry, as `declare_outbound_api` would. Each deploy and promote sets the entry's `sdk_settings` in the new copy. Keep `sdk_settings.key` where running copies have that setting. Omitting it, or `sdk_settings` entirely, revokes those copies' egress keys in both environments; the submission reports this.

The stored upstream credential can be missing at submission. The deploy still succeeds, but its `outcome.credentials_missing` lists the upstream. The gateway refuses calls to that upstream until `store_secret` stores the credential.

While `upstreams` names an upstream, `declare_outbound_api` refuses to change it, `manifest_owned_field`; change the entry and submit again instead.

A submission never removes an upstream's declaration, so a running version can keep calling it. To remove the declaration, first remove its entry from the manifest and submit it. Then deploy and promote the version that no longer calls the upstream. Call `declare_outbound_api` with its name and `remove: true`. This call is refused `manifest_owned_field` while the manifest still names it. 

While the platform's store answers, its calls are refused in both environments within about 30 seconds by default. During a store outage, a gateway may keep using its cached declaration for up to an hour ([End an upstream](/cloud/guides/call-an-external-api-with-an-api-key/#end-an-upstream)).

### Configure sign-in and push in the manifest

The optional `realm` member sets up sign-in for every end-user realm the application has at once. It takes the members of `configure_app_sign_in` that are the same in every environment: `sign_in_methods`, `creation`, `entra`, and `apple`. It also takes `clients`, the native apps that sign in, with one list for each environment.

While the recorded manifest lists an environment's clients, change that list in the manifest. `configure_app_sign_in` can change only each listed client's `minimum_version` and `update_url`. It refuses `manifest_owned_field` for a call that adds or removes a client, or changes any other client field. The manifest's `services` must include the `accounts` kind.

A `sign_in_methods` list with `passkey` lists `email` beside it, as in the sample below; otherwise `submit_manifest` refuses it `manifest_invalid` with `passkey_not_sole_route`. [Configure the realm](/cloud/guides/manage-end-users/#4-configure-the-realm) lists which realm fields the manifest owns and which stay with `configure_app_sign_in`. For one company's staff, [Allow only one company's staff](/cloud/guides/add-work-account-or-apple-sign-in/#3-allow-only-one-company-s-staff) declares the `workforce` audience beside the `entra` route.

A `push` entry in `services` may also name its providers, `apns` and `fcm`, with the members `configure_push` takes. Apple's `environment` is left out, because the gateway differs by environment. Development uses `sandbox` and production uses `production` until `configure_push` sets another.

```json
{
  "manifest_version": 1,
  "services": [
    { "kind": "accounts" },
    {
      "kind": "push",
      "apns": { "team_id": "ABCDE12345", "key_id": "KEYID12345", "bundle_id": "com.example.app", "key_secret_name": "apns-key" },
      "fcm": { "project_id": "example-app-12345", "service_account_secret_name": "fcm-service-account" }
    }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": [],
  "realm": {
    "sign_in_methods": ["google", "apple", "email", "passkey"],
    "creation": "open",
    "apple": { "services_id": "com.example.app.signin", "team_id": "ABCDE12345", "key_id": "SIGNKEY123", "key_secret_name": "apple-signin-key" },
    "clients": {
      "production": [
        { "client_id": "com.example.app", "redirect_uris": ["com.example.app:/callback"] }
      ]
    }
  }
}
```

Each submission applies these members to each environment the application has, from that moment, as the two actions would. On an application with one environment, that is production alone, and `create_environment` applies them to development when it adds it. So re-creating the application, or copying it into another account, takes this manifest, a `store_secret` for each credential, and a deploy. Each credential member names a stored secret, never its value.

The `clients` lists are the exception: each goes to its own environment's realm alone. A `development` list on an application with one environment is checked at each submission, and `create_environment` declares it. A re-created or copied application has new hostnames, so its `https` redirect URIs name them. Otherwise the submission is refused whole, recording nothing. Each client's `minimum_version` and `update_url` stay with `configure_app_sign_in` ([Sign in from a native app](/cloud/guides/sign-in-from-a-native-app/#1-declare-the-client-on-each-environment-s-realm)).

A credential not stored yet is accepted. The submission's `detail` names each credential not stored yet, with the environment where only one environment lacks it, and the `detail` of `create_environment` names each one development lacks. A deploy still succeeds, and its version's `outcome.provider_credentials_missing` lists each credential its environment cannot use yet. A sign-in credential stored after a submission is used once you submit the manifest again.

While the manifest names a push provider's field, `configure_push` refuses to change it, `manifest_owned_field`, and the `detail` names each field. Change the manifest and resubmit instead. Apple's gateway stays with `configure_push`, because it differs by environment.

A submission refused after recording the manifest lists in its `detail` the realms or push configurations it set up and those it did not. Make any correction `detail` asks for and submit again to finish setup.

If `create_environment` is refused while configuring development, its `detail` describes the sign-in or push member it reached. It says whether that configuration was recorded or a credential was taken back. Follow its remedy: repeat `create_environment` or correct and resubmit the manifest ([Refusals](#refusals)).

### Accept WebSocket connections

For a server, the optional `websockets` member declares that it accepts WebSocket upgrades. A serverless application's manifest refuses this member with `serverless_no_websocket`. Without it, every upgrade is refused `websockets_not_declared`. The empty object admits a page on the application's own hostname and a client outside a browser, and `origins` lists up to ten other browser origins whose pages may connect. [Use WebSockets](/cloud/guides/use-websockets/) gives the member's rules, the server and client code, and the connection limits.

### Adding a service later

The `add-service` skill adds the entry to `services` and submits the whole manifest again. The next deploy sets the settings the new service adds in the environment it reaches, such as the database connection string or the realm's public keys. On the manifest concept page, [The members](/cloud/concepts/the-manifest/#the-members) lists each kind and [What submitting does](/cloud/concepts/the-manifest/#what-submitting-does) what a submission provisions, and [The guide for each part of the manifest](#the-guide-for-each-part-of-the-manifest) links the guide for each kind.

For the prompt "Let users upload their receipts", add this entry to `services`:

```json
{ "kind": "object_storage", "areas": [{ "name": "receipts", "account_keyed": true }] }
```

A manifest can contain only one `object_storage` entry. Its optional `areas` list holds 1 to 50 areas, with each name listed once. Each area has exactly two fields: `name` and the boolean `account_keyed`.

An area's `name` starts with a letter or digit, followed by letters, digits, underscores or hyphens, up to 64 characters in total. It matches `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`. Names beginning `export-` or `deploy-` are reserved for the platform. So is `images-` followed by an application's UUID; other names beginning `images-`, such as `images-thumbs`, are not reserved.

`account_keyed` is required for each area and has no default. Use `true` for files that belong to individual end users, and prefix each file name with that user's ID. Use `false` for files the whole application shares.

The platform records this value and returns it in `list_storage_areas`. It does not separate files by end user; your backend must check which files each caller may read or change.

`account_keyed` cannot change for an existing area; use a new area for a different value. Before the manifest is recorded, a conflict is reported as `manifest_invalid`, with `differing_redeclaration` in `violations`. A conflict that appears after that check returns 409 `differing_redeclaration`, and the manifest stays recorded.

The submission declares each listed area and provisions nothing. Your AI tool writes the upload route. You can also omit `areas` and use the bare entry `{"kind":"object_storage"}`. Declare an area before using it, through the manifest, `declare_storage_area` or the application itself. Storage routes work for a declared area with or without this entry; [Store files](/cloud/guides/store-files/) shows the declaration and access checks.

The schema also accepts `email` and `custom_domain`. Declaring `email` provisions nothing, and a `custom_domain` entry declares the application's own domain for production ([Attach your own domain](/cloud/guides/attach-your-own-domain/)). A manifest declares one custom domain, so a second `custom_domain` entry is refused `manifest_invalid` at its path. Email send is available to every application.

Removing a `database` or `accounts` entry deletes neither the database nor the end-user realm ([Changing the manifest](/cloud/concepts/the-manifest/#changing-the-manifest)). Removing a schedule stops its future runs, and its run records are kept for the run-history retention period.

### Bind a space to some of its components

An `issue_tracking` entry that names a `space` your account owns binds the application to that space ([Keep your own issue list](/cloud/guides/keep-your-own-issue-list/)). If its `level` is `report`, the entry may also name `components`, one to two hundred of the space's declared component names, each once and at most 64 characters. A name the space does not declare is refused `invalid_request`; the issue binding and its token stay as they were. The manifest is recorded and the other kinds are set up. Submit the manifest with the name corrected to bind the space.

```json
{ "kind": "issue_tracking", "space": "7d3f1c2a-9b4e-4f61-8a27-5c0e2d9b1f44", "level": "report", "components": ["billing", "sign-in"] }
```

The platform then mints a `report` token for the binding, limited to that list, and the application's calls reach the space under it instead of the space's own token. Such a binding files reports in the listed components and reads the issues they hold, sees no restricted issue, and takes the `/v2` calls `submit`, `read`, `list`, and `search` alone. Every other call, and every `/v1` call, is refused `issue_tracking_call_refused`.

A submission that changes the list or the level mints a new token first, then revokes the old one. If the new token cannot be minted, the old binding and its token stay as they were. Moving the binding to another space, deleting the development environment it alone serves, deleting the application, deleting the account, or deleting the space with `tztrack_delete_space` revokes the token. A later submission naming no `space` keeps the binding and its token. After the space is deleted, remove `space` from the entry before the next deploy ([Delete a space](/cloud/guides/keep-your-own-issue-list/#delete-a-space)).

`components` requires a `space`. With a component list, `level` must be `report` or left out to use that default. Any other level is refused `level_invalid`. Only the owning account can bind the platform's own issue space, at `report` with a component list.

### Run scheduled work

To add a job to an application you already have, step by step, read [Add a scheduled job](/cloud/guides/add-a-scheduled-job/). This section describes the schedule declaration and when it starts. The [Schedule handler reference](/cloud/reference/schedule-handler/) gives the request headers, status-code rules, and private-path check together.

#### Declare the schedules

For the prompt "Run the daily report every morning at 6am UTC, and show me how to tell whether it ran", your AI tool adds a `schedule` service entry. Each schedule has:

- a unique name of at most 64 characters matching `^[a-z][a-z0-9_]*$`, so `hourly_heartbeat` passes and `hourly-heartbeat` is refused `manifest_invalid`. A schedule's name is an identifier in the manifest and its records, so it takes underscores and no hyphens. An application's name, which matches `^[a-z][a-z0-9-]{0,39}$`, takes hyphens and no underscores, since it becomes part of hostnames, which hold no underscore;
- a five-field cron expression in UTC: minute, hour, day of month, month, and day of week, so `0 6 * * *` means 06:00 UTC every day;
- an absolute handler path.

In the entry, `schedules` lists them, each with `name`, `cron`, and `path`, the handler path. The sample below declares the prompt's daily report beside the [Schedule](/cloud/backend-packages/schedule/) package's row. That row is optional. A handler written without the package, as [A handler without the package](/cloud/backend-packages/schedule/#a-handler-without-the-package) shows, needs no row, so `packages` lists only the project's other library entries, and is `[]` where it holds none.

```json
{
  "manifest_version": 1,
  "services": [
    {
      "kind": "schedule",
      "schedules": [
        { "name": "daily_report", "cron": "0 6 * * *", "path": "/jobs/daily-report" }
      ]
    }
  ],
  "health": "/health",
  "region": "usa",
  "egress": [],
  "audience": { "kind": "public" },
  "packages": [
    { "name": "schedule", "version": "0.3.3" }
  ]
}
```

#### Check cron and schedule limits

The expression accepts numbers, ranges, lists, steps, and `*`. Month names, day names, macros, and a seconds field are not accepted. When both day fields are restricted, a date matching either one is eligible. An expression with no due time in the next year is refused.

Before the first submission, read the schedule limits with `read_plan_quotas`: `schedule-minimum-interval` is one minute and `schedule-count-limit` is 25 for either size. Choose a frequency within both. The platform checks them at submission and at a size change:

- A schedule whose due times fall closer together than the minimum interval is refused `schedule_interval_below_plan`: its interval is below the one-minute floor. The interval applies in both environments.
- More schedules than the count limit are refused `schedule_count_over_plan`.
- A size change whose target limits the current schedules exceed is refused `plan_schedule_conflict`.

One schedule entry contains up to 25 schedules. Do not use the health path, or a path under `/__account/` or `/__router/`, as a handler path.

Write the handler to meet the [request and response contract](/cloud/reference/schedule-handler/). The [Schedule](/cloud/backend-packages/schedule/) package's router implements it, and [A handler without the package](/cloud/backend-packages/schedule/#a-handler-without-the-package) shows one on plain `node:http`.

#### Start schedules in each environment

Submit the manifest, then deploy: submitting starts no run. The platform keeps one row per schedule in each environment, and a new or changed schedule starts in an environment after its next deploy there. On an application with one environment, that is the deploy to production. With two environments, it is the deploy for development and the promote for production, which your AI tool makes only when you ask.

The `submit_manifest` response says when each row starts. While the row waits, its `next_due` is null and its `starts_with` names what it waits for. That is `the next deploy to production` on an application with one environment, and `the next deploy to development` or `the next promote to production` with two. Its value is `already running` once the environment has a deploy or promote made at or after the declaration, with `next_due` set. Where that environment is halted, its value is `the environment's resume` instead, with `next_due` null, since no row of a halted environment runs until the resume.

#### Read and investigate runs

Each row of the `submit_manifest` response also includes `cron_preview`, so you can check a cron before you spend a deploy. It holds up to three run times the cron yields after the submission, in UTC, and is null on an ended row. `read_schedules` shows the same member on every row, before its deploy and after it: up to three run times the cron yields after the read. An expression that yields fewer than three within a year shows fewer.

For `0 * * * *`, they are the next three hour marks. Where the row shows `deployed: true` and the response shows `halted: false`, the platform takes them in turn, a run starting or its outcome recorded at each.

When the platform starts a run late but within the allowed delay, it uses the oldest due time. It skips later due times already passed, with no run or record for them. A delay beyond that limit records one missed run with the count of due times missed. Before the deploy the row waits for, and while the environment is halted, no run starts at them.

A due run wakes a stopped environment, such as production with `production_sleep` on, or a development environment, and the time to wake counts against `window_seconds`, so leave the handler room for it. With sleep on, production stops thirty minutes after its last request. Development always sleeps when idle. Measured on the platform, a run that woke its application took 23 to 42 seconds, and 94 seconds for the first run after a resume, in its own container. [How the sizes differ technically](/cloud/concepts/how-the-plans-differ-technically/#start-after-idle-and-response-time) gives the start on shared compute.

Keep a handler's state between runs in a JSON file in a declared storage area, written with a conditional put, or in the database where one is declared. Counters are write-only tallies, never state. The [Schedule](/cloud/backend-packages/schedule/#keep-state-between-runs) page shows a handler that keeps its state in a file.

A schedule runs against a deployed environment, never against a process on your machine. In a test, the schedule double starts a run ([Test your application locally](/cloud/guides/test-your-application-locally/)).

[What an application must do](/cloud/backend-packages/schedule/#what-an-application-must-do) on the Schedule page says what `read_schedules` shows and how it waits for a run to end. [Confirm it runs](/cloud/guides/add-a-scheduled-job/#4-confirm-it-runs) in Add a scheduled job fires a run now with `run_schedule`. Use the run details and [the logs](/cloud/guides/read-logs-and-counters/) to investigate a failure.

#### Skipped, missed, and unfinished runs

The platform does not retry a failed or missed run. It skips a run in these cases:

- another run of the schedule is in progress;
- the account is suspended;
- the environment has no eligible deploy;
- the account has used its balance. The router refuses the run `account_paused` before any handler runs. The plane records it `skipped` with that name as its detail, and its due time counts nothing. The pause ends at the next UTC month's first instant.

While an environment is halted, its schedules do not run, and each next due time stays where it was. A resume restarts every schedule from the moment of the resume, and no missed run is recorded for the halt. A deploy to a halted development environment ends its halt and restarts its schedules from the deploy the same way. `run_schedule` on a halted environment is refused 409 `target_environment_halted`.

A run that is too late to start is recorded as missed and not run later. A run with no recorded end after its window is recorded `abandoned`, and its outcome is unknown.

## Expected result

`submit_manifest` returns `outcome: "recorded"` with the application identifier. `changed` says whether this manifest differs from the one recorded before it; a repeat still completes what an earlier submission left undone. `deploy_reads` says a deploy runs under this recorded manifest. `hostnames` gives each environment's hostname, where the application and its sign-in pages answer once a version serves. The kinds you declare add their own members, such as `development_database` and `connection_limit` for the database ([Add a database](/cloud/guides/add-a-database/#expected-result)). The rows below are the ones your AI tool acts on, and [submit_manifest](/cloud/reference/actions/submit-manifest/) lists every member.

When `changed` is `true`, `cost_reads` points to the `cost-estimate` skill and `read_rate_card` for your AI tool to estimate cost before deploying. Read the skill with `read_context`, id `skill:cost-estimate`.

| Member | Returned when | What it contains |
| --- | --- | --- |
| `detail` | Every submission through the MCP tool. Through the HTTP API, where the submission has something to report. | What happened, one fact per line, each line a whole sentence: a line for each service the submission set up, and one naming each credential not stored yet. The last line says that only a run on your machine needs `turnzero provision`, and that the page in `page` explains each line. |
| `settings` | The manifest binds a setting in `settings`. | One row per bound setting and environment: the `setting`, the `secret`, the `environment`, and `stored`, whether the name is stored at that environment's scope. A plain setting, given as `value`, has no row. The rows cover only the environments the application has. `detail` lists each name not stored yet, for the environments the application has. |
| `next` | A name a setting, an upstream, a sign-in method, or a push provider uses is stored at no scope its environment reads. | One `store_secret` call per name and environment the `detail`'s not-stored line counts, in that line's order, each filled in whole; make each before the deploy. A resubmission naming `local_run` is never listed. On an application with no development environment, an upstream key's development step, which only local runs read, is not listed either. |
| `schedules` | The manifest declares the schedule kind, or a resubmission without the kind ends its schedules. | One row per schedule in each environment, with `starts_with`, `next_due`, and `window_seconds`, the seconds a run has before the platform ends it. Each row also has `cron_preview`, up to three run times the cron yields after the submission, so your AI tool can check the cron before it deploys. `starts_with`, `next_due`, and `cron_preview` are null for an ended row. Every row of `read_schedules` shows up to its next three run times in `cron_preview`, before that deploy as well as after it, though a row starts no run before its deploy. |
| `storage_areas` | The manifest's `object_storage` entry carries `areas`. | One row per listed area: `area`, the area as `list_storage_areas` answers it; `outcome`, `created` or `unchanged`; and `address`, the area's whole file address with `<name>` in place of a file's name. |

After the deploy, `read_schedules` shows each row of the environment it reached with `deployed: true`, its `next_due`, and `reason: null`; on two environments, the production rows show the same after the promote. `run_schedule` with `wait_seconds` returns the run's own outcome where it ended inside the wait, with the handler's console lines in `console`. `read_schedules` then shows that run under `last_run` with its `outcome`, `status`, and `duration_ms`.

## Refusals

See the [refusals reference](/cloud/reference/refusals/) for other platform errors.

These parts cover `submit_manifest`, `read_schedules`, and `run_schedule`, with `manifest_missing` from `deploy`, the serving router's skipped run, and `set_app_size`'s schedule conflict. A refusal gives its cause in `detail`. A submission refused before the manifest is recorded changes nothing. Where a row says the manifest stays recorded, the `detail` lists what was set up and what was not: make any change it asks for, then submit again before the next deploy or promote.

### Validate the declaration and identify the application

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `manifest_invalid` | 400 | The manifest does not match the schema; `violations` lists the failing paths. An `upstreams` entry's line also names the refusal `declare_outbound_api` would give it. A `realm` member's or `push` entry's line names the refusal of `configure_app_sign_in` or `configure_push`. A listed area's line names the refusal the minting route would give it: `differing_redeclaration`, `area_name_reserved`, or `area_scope_refused`. A `settings` entry that is not exactly one of `{"secret": ...}` and `{"value": ...}`, or whose value breaks its bounds, has a line naming both forms. | Correct each path and resubmit the whole manifest. |
| `area_name_reserved` | 400 | A listed area's reserved name became free while this manifest was being recorded. The manifest stays recorded. | Choose a name that does not begin `export-` or `deploy-`, and does not match `images-` followed by an application's UUID. Then submit the whole manifest again. |
| `environment_unsupported` | 400 | The manifest has an `environments` member. | Remove it; `create_environment` and `delete_environment` set an application's environments. |
| `region_unavailable` | 400 | `region` is `europe`, `uk` or `global`, which the schema admits and the platform does not serve. | Set `region` to `usa`. |
| `invalid_request` | 400 | A member is malformed or missing, and `detail` names it. For `read_schedules`, the environment is not `development` or `production`. For the `issue_tracking` entry, a `level` or `components` with no `space`, or the platform's own space named with no `components`. Also a `space` given by an application that kept a space for each environment or has its own. Nothing is recorded. | Correct the named member. |
| `level_invalid` | 400 | The `issue_tracking` entry's `level` is not `report` or `contribute`, or is not `report` beside `components` or for the platform's own space. Nothing is recorded. | Name `report` or `contribute`, and `report` with a list. |
| `no_such_application` | 404 | `application` names no application of your account. | Use the identifier `list_applications` returns. |
| `application_other_account` | 403 | `application` names an application that another account holds, not the account the call is signed in as. The `detail` names the account the call acted as and nothing of the other one. | Compare `turnzero whoami` with `read_account` over your AI tool's connection. Make the call from the one signed in to the account that holds the application. |
| `area_scope_refused` | 403 | Another application claimed a listed area's name after the initial check, and this credential cannot reach that application. The manifest stays recorded. | Use a new area name for this application, then submit the whole manifest again. |
| `realm_not_declared` | 404 | An end-user realm was deleted while this manifest was being recorded, so it was not set up. The manifest stays recorded. | Submit the manifest again. |
| `differing_redeclaration` | 409 | A listed area was declared with different values while this manifest was being recorded. The manifest stays recorded. | Use a new area name or match the existing area's values, then submit the whole manifest again. |

### Bind settings and configure services

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `declared_tenant_contradicts_route` | 409 | The workforce audience gives a different tenant from the work-account route of one of the application's realms, and the refusal's `environment` names which. | Declare that route's tenant, or call `configure_app_sign_in` for the named environment with the audience's tenant ([Manage end users](/cloud/guides/manage-end-users/)). Where the manifest's `realm` member names `entra`, change its tenant there instead and submit again. |
| `declared_audience_contradicts_route` | 409 | The invited audience is declared while a realm's sign-in methods include `entra`, which an invitation-only realm does not allow. | Remove `entra` from the realm's `sign_in_methods` and submit again, or keep the current audience. Remove it in the manifest's `realm` member where that names `sign_in_methods`, and otherwise with `configure_app_sign_in` ([Manage end users](/cloud/guides/manage-end-users/)). |
| `setting_scope_refused` | 409 | A binding in `settings` names a secret stored at account scope or at another application's scope, which no deploy of this application reads. | Store the value under a new name at this application's scope, in each environment, and bind that name. |
| `platform_minted_name` | 409 | A binding names a credential the platform created for one of your applications. | Bind a name of your own that you stored with `store_secret`. |
| `setting_is_upstream_key` | 409 | A binding names the key an upstream of the application declares; the gateway never gives that key to the application. | Call the upstream through the gateway, or bind a value stored under another name. |
| `name_bound_to_realm` | 409 | A binding names a realm sign-in method's credential, the work-account client secret or the Apple signing key. | Bind a value stored under another name; a sign-in method's credential stays the realm's. |
| `name_bound_to_push` | 409 | A binding names a push provider's credential of the application's push configuration. | Bind a value stored under another name; a provider's credential stays the push service's. |
| `binding_refused` | 409 | Another application of your account declared an `upstreams` entry's name while this manifest was being recorded, and `application` names it. The manifest stays recorded. | Rename the entry and submit the manifest again before the next deploy or promote. |
| `upstream_key_is_bound` | 409 | A binding of an `upstreams` entry's key was recorded while this manifest was being recorded, so the platform undid this submission's change to that entry where it could. The `detail` names an entry it could not undo. The manifest stays recorded. | Store the key under another name and change the entry, or remove the binding, then submit the manifest again before the next deploy or promote. |
| `not_yet_provisioned` | 501 | The platform you reached runs no issue service, so an `issue_tracking` entry, one naming a `space` among them, sets up nothing. The manifest is recorded and every other kind is provisioned. | Submit again on a platform that lists the feedback actions. |
| `name_bound_to_setting` | 409 | A binding of a sign-in or push credential the manifest names was recorded while this manifest was being recorded, so the platform took that credential back where this submission set it. The manifest stays recorded. | Store the credential under another name and change the member, or remove the binding, then submit the manifest again. |
| `custody_entry_missing` | 409 | A credential named in the `realm` member was deleted while this manifest was being recorded, so that environment's realm was not set up. The manifest stays recorded. | Store the value again, or under a new name set in the member, and submit the manifest again. |
| `custody_entry_unmovable` | 409 | The platform's store for sign-in credentials already contains a credential named in the `realm` member, at another version, so that environment's realm was not set up. The manifest stays recorded. | Store the value under a new name, change the member to it, and submit the manifest again. |

### Deploy and run schedules

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `no_such_schedule` | 404 | The application has no schedule of that name in that environment. | Name a declared schedule, and name the environment when it is not production. |
| `manifest_missing` | 409 | `deploy` found no manifest for the application. | Submit the manifest first. |
| `setting_secret_missing` | 409 | A `deploy` or `promote` found a bound name not stored at its environment's scope; `detail` names the setting and the name, and `next` the `store_secret` call to make. | Store the value there with `store_secret` for the application and the environment, as [Store a secret](/cloud/getting-started/store-a-secret/#2-supply-the-value-without-exposing-it) describes, then deploy or promote again. |
| `schedule_interval_below_plan` | 409 | A schedule's due times fall closer together than `schedule-minimum-interval`. `path` names it, `quantity` gives the minimum in minutes, and `gap` the shortest gap found. | Run it less often. |
| `schedule_count_over_plan` | 409 | The manifest declares more schedules than `schedule-count-limit`. `path` names the first one over, and `quantity` gives the limit. | Declare fewer schedules. |
| `plan_schedule_conflict` | 409 | `set_app_size` found declared schedules that exceed the target size's limits. | Submit the manifest within those limits, then repeat the size call. |
| `plan_quantity_unset` | 409 | A required quantity for the size is unset. The manifest stays recorded for a database, and nothing is recorded for a schedule. | Read its row with `read_plan_quotas` and wait for platform staff to set it. |
| `deletion_in_progress` | 409 | The application or one of its environments is being deleted. A deletion approved while another deletion of the same application holds it ends failed with this refusal. That refusal's detail gives the instant the other deletion's hold lapses; if its process stopped, request your deletion again after that instant. | Wait for the deletion to finish; `read_approval_status` shows whether it completed. If it failed, request the same deletion again to complete it. |
| `schedule_not_deployed` | 409 | `run_schedule` named an environment with no deploy or promote since the schedule was declared. | Deploy to that environment, or promote to production on an application with two environments, then run again. |
| `environment_not_created` | 409 | `run_schedule` named `development` on an application with one environment. | Run it in production, or turn development on with `create_environment` and deploy there first. |
| `run_in_flight` | 409 | A run of the schedule is still in progress. A due time during it is skipped, not queued. | Wait until `read_schedules` shows the run ended, then run again. |
| `target_environment_halted` | 409 | `run_schedule` targeted a halted environment. | Resume it by calling `halt_environment` with `resume: true`, then run again. |
| `account_paused` | 429 | The account has used its balance. The router refuses the run before the handler runs; the plane records `skipped` with `account_paused` as its detail, and the due time counts nothing. | Wait until the next UTC month starts. |

### Provision the database and finish setup

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `database_provisioning_failed` | 502 | Creating the database role or password failed; the manifest stays recorded. | Read the response, then resubmit to finish the setup. |
| `server_unavailable` | 503 | No database server has room for the database now. Or an earlier, unfinished setup recorded a server that no longer takes databases, and the setup cannot move to another server while that record exists. The manifest stays recorded. | Where `detail` does not name a server recorded by an earlier run, resubmit later; changing the manifest does not help. Where it names one, resubmit once, since that run may still be finishing. If it repeats, `delete_environment` naming development removes the setup, with development's data and secrets, on one environment or two. A resubmission then sets it up again; on two environments, call `create_environment` before it. If that deletion fails, report the refusal with its `detail`, and resubmit once platform staff have removed the earlier setup or opened the server again. |
| `cell_not_configured` | 503 | The platform cannot place the database now; the manifest stays recorded. | Nothing on your side corrects this: report the refusal with its `detail`, and resubmit once platform staff have configured the [hosting cell](/cloud/concepts/glossary/#hosting-cell). |
| `store_unavailable` | 503 | The platform's store did not respond while the `upstreams` entries or the listed areas were being declared, or while the realms or push configurations were being set up. The manifest stays recorded, and `detail` lists what was done and what was not. | Submit the same manifest again, before the next deploy or promote. |

## Related

- [The manifest](/cloud/concepts/the-manifest/) explains each member, what submitting provisions, and what a change or removal leaves in place.
- [Deploy from your computer](/cloud/getting-started/deploy-an-application/) covers the deploy that follows a submission, and [The deploy health check](/cloud/concepts/the-deploy-health-check/) the check on the health path.
- [Add a database](/cloud/guides/add-a-database/), [Add sign-in to your app](/cloud/guides/add-sign-in-to-your-app/), [Store files](/cloud/guides/store-files/), and the other guides that [The guide for each part of the manifest](#the-guide-for-each-part-of-the-manifest) lists each show their part of the manifest in use.
- [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/) writes the environment file a local run reads.
- [Schedule handler](/cloud/reference/schedule-handler/) gives the request and response contract; [Schedule](/cloud/backend-packages/schedule/) describes the package's router and examples.
- [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/) explains the observe and enforce modes for the egress list.
- [submit_manifest](/cloud/reference/actions/submit-manifest/), [read_schedules](/cloud/reference/actions/read-schedules/), and [run_schedule](/cloud/reference/actions/run-schedule/) in the generated reference give each action's arguments and result.
- [Glossary](/cloud/concepts/glossary/) defines the terms used on this page.
