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.

{
  "apiversion": 3,
  "func": "deploy",
  "module": "WebApp",
  "result": {
    "data": {
      "deploy_id": "dp-20260612-0001",
      "sse_url": "/sse/UserTasks/00000000_5c6c8b18228a35/deploy.log",
      "task_id": "00000000/5c76ec5566332c"
    },
    "status": 1
  }
}