---
title: "Register a new web application."
method: GET
path: "/WebApp/stage"
tags: ["WebApp", "Web Apps"]
---

# Register a new web application.

`GET /WebApp/stage`

Web Apps is the recommended feature for deploying new web applications, and this function is the entry point. Prefer it over the older Application Manager (`PassengerApps`) feature for new deployments.

This function registers a new web application from an uploaded
archive or a Git repository. Once the source is placed on disk, it
runs a preflight that inspects the source and detects the
application's framework and category, records them on the
application, and derives suggested configuration defaults. The
detection `confidence` and the suggested `defaults` are returned so
you can pass them to `WebApp::configure`. The application is
registered but **not** deployed — call `WebApp::configure` (optional)
and then `WebApp::deploy` to bring it live.

The preflight never fails the stage: a source with no recognizable
markers is registered with a `none` confidence and generic defaults.

Registering a name that is still **staged** (not yet deployed)
overwrites it: the previously staged application and its source are
replaced, and the response `warnings` array reports that the old
files were overwritten.

Registering a name that is already **deployed** leaves the running
application untouched — its container and live routing are never
disturbed — but the new application cannot reuse the deployed
application's display name, or `WebApp::list` and bare-name
addressing could not tell the two apart. So it is registered under
the next free `<name>-N` (for example, `my-app-2`), and the response
`warnings` array reports the assigned name. **Read the assigned name
from the response `data.name`: you must pass that name (not the one
you requested) to `WebApp::configure` and `WebApp::deploy` to act on
this application**, which stands up as its own separate container.

On failure, the `metadata.error_category` field carries a
machine-readable failure category.

## Query parameters

- `name` string, required
- `source` string, required
- `source_type` 'zip' | 'git', required
- `appdir` string
- `branch` string
- `mode` 'production' | 'development'
- `runtime` 'nodejs'

## Response `200`

HTTP Request was successful.

- object
  - `apiversion` integer — The version of the API.
  - `func` string — The name of the method called.
  - `module` string — The name of the module called.
  - `result` object
    - `data` object — The newly registered application.
      - `category` 'static' | 'server' | 'other' — The application's category. This determines which lifecycle actions apply. * `static` — The application builds to static files that the web server serves directly. * `server` — The application runs a long-lived server process. * `other` — Any other kind of application.
      - `container_name` string, nullable — The name of the deployed container backing this application, or `null` while it is only staged. Assigned by the deploy and unique per application instance, so it identifies the exact deployed record even when several applications share a base name.
      - `confidence` 'high' | 'low' | 'none' — How confident the preflight detection is. * `high` — Strong framework markers found. * `low` — Partial markers found; verify the defaults before deploying. * `none` — No recognizable markers; the defaults are generic.
      - `defaults` object — Suggested configuration values for the detected framework. Pass them to `WebApp::configure` as-is or after user adjustment.
        - `build_command` string, nullable — The suggested build command, or `null` if no build step is needed.
        - `output_dir` string, nullable — The suggested build output directory, or `null` if not applicable.
        - `runtime_tag` string — The suggested runtime version tag.
        - `startup_command` string, nullable — The suggested startup command, or `null` for `static` applications.
      - `db` object, nullable — The application's linked database information, or `null` if no database is linked.
        - `env_keys` string[] — The environment variable names that carry the database credentials.
        - `host` string, hostname — The database server hostname.
        - `name` string — The database name.
        - `port` integer — The database server port.
      - `deployed` boolean — Whether a deploy has put the application live. This is `true` once the application holds a container or a deploy has completed successfully, and `false` for a freshly staged application or one whose only deploy failed.
      - `domain` string, domain — The domain the application is bound to. This is an existing domain on the account or an automatically generated temporary domain.
      - `env` object — The application's environment variables.
      - `framework` string, nullable — The application's detected or user-selected framework, or `null` if unknown.
      - `last_deploy` object, nullable — Information about the most recent deploy, or `null` if the application has never deployed.
        - `deploy_id` string — The unique identifier of the deploy.
        - `result` 'success' | 'failed' — The result of the deploy.
        - `timestamp` string, date-time — When the deploy finished, in ISO 8601 format.
      - `mode` 'production' | 'development', nullable — The application's run mode. Only meaningful for the `server` category; `null` otherwise.
      - `name` string — The application's assigned name (slug), unique across the account. This may differ from the name you requested: if a deployed application already used that name, the application was registered under the next free `<name>-N`. Use this value for `WebApp::configure` and `WebApp::deploy`.
      - `package_manager` 'npm' | 'yarn' | 'pnpm' | 'bun' — The package manager the deploy uses to install dependencies and run scripts. It is detected from the source's `packageManager` field, a lockfile, or the default (`npm`).
      - `runtime` string — The application's runtime identifier.
      - `runtime_tag` string — The runtime version tag.
      - `source` object — The application's source information.
        - `branch` string, nullable — The Git branch, or `null` for ZIP sources.
        - `type` 'zip' | 'git' — The source type. * `zip` — An uploaded archive. * `git` — A Git repository.
        - `url` string, nullable — The Git repository URL, or `null` for ZIP sources.
      - `staged` boolean — Whether the application's source is present in the staging area. This is `true` after the source is uploaded or cloned and until the application is deleted.
      - `status` 'created' | 'deploying' | 'running' | 'stopped' | 'errored' — The application's current status. * `created` — Registered but never deployed. * `deploying` — A deploy is in progress. * `running` — The application is live. * `stopped` — The application is stopped. * `errored` — The last action failed.
      - `url` string, url — The application's live HTTPS URL.
    - `errors` string[], nullable — List of errors if the API failed.
    - `messages` string[], nullable — List of messages generated by the API.
    - `metadata` object
      - `error_category` 'limit_exceeded' | 'source_invalid', nullable — The machine-readable failure category. Only present when `status` is `0`. * `limit_exceeded` — The account reached its application count or memory limit. * `source_invalid` — The source archive or Git repository is missing, unreadable, or invalid.
    - `status` 0 | 1 — - `1` - Success. - `0` - Failed. Check the `errors` field for more details.
    - `warnings` string[], nullable — List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.

---

[API](https://skmtc.dev/cpanel/apis/cpanel-uapi.md) · [All operations](https://skmtc.dev/cpanel/apis/cpanel-uapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cpanel/cpanel-uapi/revisions/632e2f8e6d04/schema)