# Deploy an application.

Web Apps is the recommended feature for deploying new web applications; prefer it over the older Application Manager (PassengerApps) feature for new deployments.

This function deploys an application: it installs dependencies, runs
the build, and promotes the result to the live environment.

Note:

  This function starts an asynchronous task and returns immediately.
  Stream the returned sse_url for live progress, or poll the task.
  While the task runs, the application's status is deploying. When
  the task finishes the status transitions to running on success or
  errored on failure. Use WebApp::list to read the current status
  and inspect last_deploy for the outcome and any failure category.

Important:

  This function is idempotent. If you call it while a deploy for the
  same application is already running, it returns the in-flight
  task's identifiers instead of starting a new deploy.

If this call fails before the task is dispatched (for example, when
the application does not exist), metadata.error_category carries a
machine-readable failure category. Build and runtime failures occur
inside the background task and are recorded asynchronously in
last_deploy.error_category, which is accessible via WebApp::list.

Endpoint: GET /WebApp/deploy
Version: 11.138.0.10
Security: BasicAuth

## Query parameters:

  - `name` (string, required)
    The application's unique name (slug).
    Example: "my-app"

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "deploy"

  - `module` (string)
    The name of the module called.
    Example: "WebApp"

  - `result` (object)

  - `result.data` (object)

  - `result.data.deploy_id` (string)
    The unique identifier of this deploy.
    Example: "dp-20260612-0001"

  - `result.data.sse_url` (string)
    The SSE URL to stream the deploy's progress.
    Example: "/sse/UserTasks/00000000_5c6c8b18228a35/deploy.log"

  - `result.data.task_id` (string)
    The task id of the SSE process.
    Example: "00000000/5c76ec5566332c"

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.metadata.error_category` (string,null)
    The machine-readable failure category. Only present
when status is 0 and the error occurred before
the background task was dispatched.

Build and runtime pipeline failures occur asynchronously;
they are recorded in last_deploy.error_category after
the task finishes and are accessible via WebApp::list.

* build_failed — The build step failed. The error message includes the breached resource cap when one applied.
* port_conflict — The application's port is already in use.
* requires_build — The application must be built before it can deploy, and no build command is configured.
* start_failed — The container started but is not listening on a port, so the application is unreachable; it most likely exited immediately.
* missing_output — The build finished, but the directory the application is served from does not exist. The output directory does not match what the build writes.
* limit_exceeded — Deploying this application would push the account's number of running application containers to or past its maximum allowed applications.
* domain_in_use — Another of this account's applications has claimed the application's domain since it was last configured.
* domain_unavailable — The application's domain now exists on the account as a non-webapp domain since it was last configured, and use_existing_domain was not set on it.
* domain_temporary — The application's domain does not exist and sits under one of the server's temporary domains, which the system cannot create a domain beneath. Point the application at the temporary domain itself, confirmed with use_existing_domain.
    Enum: "build_failed", "port_conflict", "requires_build", "start_failed", "missing_output", "limit_exceeded", "domain_in_use", "domain_unavailable", "domain_temporary"

  - `result.status` (integer)
    - 1 - Success.
- 0 - Failed. Check the errors field for more details.
    Enum: 0, 1

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.