# Update an application's configuration.

This function updates an application's configuration. Only the
parameters you pass change; omitted parameters keep their current
values.

Important:

  The env parameter uses replace-all semantics — the value you
  pass becomes the application's complete set of environment
  variables. To change one variable, read the current set first and
  resubmit it with your change applied. env_text is the same
  operation with the same semantics, for a caller pasting a whole
  .env file instead of assembling an object; pass one or the other,
  never both.

Endpoint: GET /WebApp/configure
Version: 11.138.0.19
Security: BasicAuth

## Query parameters:

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

  - `appdir` (string)
    The application root, relative to the top of the source, for a
source whose application does not live at the top level (for
example, packages/web in a monorepo).

Pass an empty value to reset the root back to the source top.

Changing this value re-runs the preflight against the new root,
which re-detects the application's framework and category and
re-seeds the suggested build defaults (any value you pass explicitly
in the same call takes precedence). When it changes, the response
also carries the confidence and defaults from the re-detection.

This parameter must be a relative path inside the source.
    Example: "packages/web"

  - `auto_recovery` (string)
    Whether the scheduled health check may act on this application.

* 1 — The health check may restart or otherwise repair it.
* 0 — Leave the application alone entirely. It is not checked, so its health block stops being updated.

Pass an empty value to follow the server-wide setting, which is the
default.
    Enum: "0", "1", ""

  - `build_command` (string)
    The command that builds the application.

Pass an empty value to clear it, so the deploy falls back to the
detected default.
    Example: "npm run build"

  - `db` (string)
    The application's database action.

* create — Provisions a new MySQL database and user, named from
  the application's slug.
* link — Attaches an existing, account-owned database (see
  db_name) by creating a new, dedicated MySQL user for it,
  granted ALL PRIVILEGES on the database — never by reusing an
  existing user, since MySQL keeps no retrievable password for one.
* remove — Clears the application's db record, and deletes the
  database and its user if it was created, or only the
  dbuser if it was linked — the linked database itself is
  never touched.

An application may have at most one linked database, so create
or link on an application that already has one fails: use
remove first. There is no replace action that does both in one
call.

Warning: for a created database, remove destroys it and
everything in it, and this cannot be undone. A linked database
is never at risk from remove — only its dbuser is.

remove clears the db record even when the underlying drop
itself fails (for example, a created database already dropped
outside this API). The call succeeds and reports a warning, since
clearing the record is the only way to make the application's
database name usable again.

On a deployed application, the container is recreated so the new
database settings take effect immediately, without a redeploy. A
stopped application stays stopped, and picks the settings up when
it next starts. If the change cannot be applied to the container,
the call fails and the application and its database are left as
they were.

All three actions require the account's mysql feature and the
server's MySQLClient role.
    Enum: "create", "link", "remove"

  - `db_name` (string)
    The existing, account-owned database to attach. Required when db
is link; ignored (and omittable) otherwise.
    Example: "my_existing_db"

  - `deployname` (string)
    The name (slug) used to name the deployment. When omitted, the
deployment is named after the application.
    Example: "my-app"

  - `domain` (string)
    The domain to bind the application to: a new subdomain of a domain
the account owns, or the application's own already-materialized
domain. A domain already claimed by another application is always
rejected. A domain the account already uses for something else — the
main domain, an addon domain, a manually created subdomain — is
rejected unless use_existing_domain confirms it. See the
domain_in_use, domain_unavailable, and domain_temporary
error_category values.

Pass an empty value to regenerate the application's default
..
    Example: "my-app.example.com"

  - `env` (string)
    A JSON-encoded object of the application's environment variables.

Warning: This replaces all existing environment variables
with the set you provide.

The values are written to the application's own .env file, which
the container reads at startup. That file lives in the application's
source tree, so setting values is refused unless the repository
keeps it out of version control — see the env_not_editable
error_category and the env_editable field on the application. An
empty object clears the environment, which is allowed even then,
because a clear removes values rather than publishing them.

Database precedence: once a database is configured (create
or link), its connection details are injected under DB_HOST,
DB_NAME, DB_PORT, DB_USER, and DB_PASSWORD (see
db.env_keys). If this parameter sets a variable with the same
name, the database's value overrides it in the deployed
container.

Limits: at most 16384 bytes of JSON and 64 variables. A name
must match A-Za-z_* and be at most 128 characters.
A value must be a single value (not an object or a list), at most
4096 characters, and free of control characters. PORT is
reserved by the system and is rejected.
    Example: "{\"NODE_ENV\":\"production\",\"API_KEY\":\"abc123\"}"

  - `env_text` (string)
    The raw contents of a .env file, for a caller pasting a whole file
rather than assembling an object. Mutually exclusive with env;
passing both is an error.

Warning: This replaces all existing environment variables,
exactly as env does.

The text is read the way podman's --env-file reads it, so what is
accepted here is what the container would have loaded from the same
bytes: leading whitespace is trimmed, blank lines and lines
beginning with # are ignored, the first = separates the name
from the value, and the rest of the line is taken verbatim — no
quote stripping and no trimming, so A="b" has the value "b"
including the quotes. A name repeated on a later line takes that
later value. A line with no = is rejected rather than copied from
the server's own environment.

The resulting variables are held to the same limits as env, and
are refused for the same repository reasons. Text that yields no
variables clears the environment, which is allowed even then,
exactly as an empty env object is.
    Example: "# deployment\nNODE_ENV=production\nAPI_KEY=abc123"

  - `mode` (string)
    The run mode for server category applications.
    Enum: "production", "development"

  - `output_dir` (string)
    The directory, relative to the application root, that the build writes its output to.
    Example: "dist"

  - `runtime_tag` (string)
    The runtime version tag to run the application under. Use WebApp::get_available to list the valid tags.
    Example: "22"

  - `startup_command` (string)
    The command that starts the application's server process. Only
meaningful for the server category.

Pass an empty value to clear it, so the deploy falls back to the
adapter default. Clearing both this and build_command on a
non-static application leaves it undeployable: the deploy then fails
with a requires_build error_category.
    Example: "npm run start"

  - `use_existing_domain` (integer)
    Confirms that the application may be served at a domain the account
already uses. The application is proxied over that domain, so
whatever its document root serves — an existing website, and any
files added to it later — stops being reachable until the
application is deleted. Other configuration on a domain already in
use (rewrites, handlers) may also take precedence and keep the
application from being served, which is why a fresh, unused
. is the ideal target. See
https://go.cpanel.net/docroot2proxy.

Only meaningful alongside domain, and only kept while that domain
is unchanged: pointing the application at a different domain
requires confirming again. Omitting the parameter does not withdraw
a confirmation already given — it leaves the standing one in place,
so resending domain to change something else needs no
reconfirmation. There is no way to withdraw a confirmation for a
domain that still exists (sending 0 is refused with
domain_unavailable); point the application at a different domain
instead, which releases the reverse-proxy include on the domain being
left so it serves its own document root again.

It is recorded only when the domain already exists and the
application did not create it; for one the application will create,
or already created, the domain is the application's own, so there is
nothing to take over and the application object reports 0. It does
not allow a domain another application already has, nor a domain the
system cannot create.
    Enum: 0, 1

## Response 200 fields (application/json):

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

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

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

  - `result` (object)

  - `result.data` (object)
    The application with its updated configuration.

  - `result.data.auto_recovery` (integer,null)
    Whether the scheduled health check may act on this
application: 1 if it may, 0 if the application
is to be left alone entirely, and null when it
follows the server-wide setting.

An application set to 0 is not checked at all, so
its health block stops being updated.

  - `result.data.build_command` (string,null)
    The application's configured build command, or null if it has no build step. Set from the preflight-suggested default at stage, and overridable via configure.
    Example: "npm run build"

  - `result.data.category` (string)
    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.
    Enum: "static", "server", "other"

  - `result.data.confidence` (string)
    How confident the preflight detection is. Present
only when this call changed appdir and re-ran the
preflight.

* high — Strong framework markers found.
* low — Partial markers found; verify the defaults before deploying.
* none — No recognizable markers; the defaults are generic.
    Enum: "high", "low", "none"

  - `result.data.container_name` (string,null)
    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.
    Example: "my-app.bob.01"

  - `result.data.db` (object,null)
    The application's linked database, or null if none is configured.

  - `result.data.db.env_keys` (array)
    The environment variable names the database's
connection details are injected under, directly
into the deployed container's environment. These
are not part of this application's own env
field, and are never echoed back by any call.
    Example: ["DB_NAME","DB_HOST","DB_PORT","DB_USER","DB_PASSWORD"]

  - `result.data.db.host` (string)
    The database server hostname.
    Example: "localhost"

  - `result.data.db.name` (string)
    The database name.
    Example: "example_my_app"

  - `result.data.db.origin` (string)
    How the application got this database.

* create — Provisioned by this application; remove
  deletes the database itself.
* link — An existing database this account owns
  independently; remove only detaches the
  dedicated dbuser created for it.
    Enum: "create", "link"

  - `result.data.db.port` (integer)
    The database server port.
    Example: 3306

  - `result.data.defaults` (object)
    Suggested configuration values for the detected framework. Present only when this call changed appdir and re-ran the preflight.

  - `result.data.defaults.build_command` (string,null)
    The suggested build command, or null if no build step is needed.
    Example: "npm run build"

  - `result.data.defaults.output_dir` (string,null)
    The suggested build output directory, or null if not applicable.
    Example: ".next"

  - `result.data.defaults.runtime_tag` (string)
    The suggested runtime version tag.
    Example: "22"

  - `result.data.defaults.startup_command` (string,null)
    The suggested startup command, or null for static applications.
    Example: "npm run start"

  - `result.data.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.

  - `result.data.deployname` (string,null)
    The name used to name the deployment, or null when it defaults to the application name.
    Example: "my-site"

  - `result.data.domain` (string)
    The domain the application is bound to. This is an existing domain on the account or an automatically generated temporary domain.
    Example: "my-app.example.com"

  - `result.data.env` (object)
    The application's environment variables.
    Example: {"API_KEY":"abc123","NODE_ENV":"production"}

  - `result.data.env_editable` (boolean)
    Whether the environment may be set for this
application. The values are written to the
application's own .env, which lives in its
source tree, so a repository that would publish
that file withholds the feature: a configure
that sets env or env_text fails with an
error_category of env_not_editable. Derived from the source
tree on every call, so it changes as soon as the
repository does.
    Example: true

  - `result.data.env_status` (string)
    Why the environment is not editable, or ok when
it is. tracked means the repository tracks
.env; not_ignored means no committed
.gitignore rule covers it. Both are fixed by the
user in the repository, not through this API.
    Enum: "ok", "tracked", "not_ignored"

  - `result.data.framework` (string,null)
    The application's detected or user-selected framework, or null if unknown.
    Example: "nextjs"

  - `result.data.health` (object,null)
    What the most recent health check found, or null
if the application has not been checked yet. This
is read from the last check rather than measured
when you call this function, so it is at most one
check interval old.

  - `result.data.health.action` (string)
    What would repair the cause, which is not
always a restart.

* none — Nothing should be done to the application.
* restart — Restarting it is a reasonable repair.
* rewire_proxy — Its reverse-proxy configuration needs rewriting.
* notify — Only a person can resolve this.
    Enum: "none", "restart", "rewire_proxy", "notify"

  - `result.data.health.cause` (string)
    What is wrong with the application.

* healthy — Nothing.
* stopped_by_user — You stopped it.
* deploying — A deploy is in progress.
* never_deployed — No deploy has ever succeeded.
* out_of_memory — It exceeded its memory limit and was killed.
* crash_on_boot — It has never started successfully since its last deploy.
* dead — It ran and then stopped.
* unit_missing — Its service definition is gone.
* wedged — It is running but not answering on its port.
* stale_proxy_port — Its reverse proxy points at a port it no longer uses.
* missing_include — It has no reverse-proxy configuration.
* port_unreachable — It is running but publishes no port.
* public_unreachable — It answers locally, and its domain does not.
* app_error — It answers requests with an error of its own.
* unknown — Nothing could be read about it.
    Enum: "healthy", "stopped_by_user", "deploying", "never_deployed", "out_of_memory", "crash_on_boot", "dead", "unit_missing", "wedged", "stale_proxy_port", "missing_include", "port_unreachable", "public_unreachable", "app_error", "unknown"

  - `result.data.health.checked_at` (string)
    When the check ran, in ISO 8601 format.
    Example: "2026-06-12T14:03:22.000Z"

  - `result.data.health.healthy_at` (string,null)
    When the application was last seen healthy, in ISO 8601 format, or null if it never has been. An application that has not been healthy since its last deploy has never started successfully, which a restart cannot fix.
    Example: "2026-06-12T13:58:04.000Z"

  - `result.data.health.incidents` (integer)
    How many incidents were recorded for this application in the last 24 hours. Only the most recent incidents are kept, so this figure stops climbing once enough of them have been recorded to show the pattern.
    Example: 3

  - `result.data.health.memory` (object,null)
    The application's own memory accounting at the time of the check, or null when neither a live figure nor a configured limit could be read.

  - `result.data.health.memory.limit_bytes` (integer,null)
    The memory limit, or null if it is not capped.
    Example: 536870912

  - `result.data.health.memory.oom_kills` (integer)
    How many times a process was killed for exceeding the limit during this run.
    Example: 1

  - `result.data.health.memory.peak_bytes` (integer,null)
    The highest memory use recorded during this run, or null once the run is over or if this server does not keep that figure.
    Example: 186912768

  - `result.data.health.oom_incidents` (integer)
    How many of the last 24 hours' incidents were the application exceeding its memory limit, counted over the same kept incidents as incidents. Past a few of these, raising the limit is the only thing that will help, and that is your decision.
    Example: 3

  - `result.data.health.restarts` (integer)
    How many times the service has been restarted, as the system's own retry counter reports it. Omitted when that counter could not be read.
    Example: 3

  - `result.data.health.state` (string)
    A summary of cause suitable for a status badge.

* healthy — Nothing is wrong.
* stopped — You stopped it.
* pending — It is deploying, or has never deployed.
* recovering — Something is wrong and a repair is available.
* needs_attention — Something is wrong that only you can resolve.
* unreachable — The application is fine and its domain is not.
* unknown — Nothing could be read about it.
    Enum: "healthy", "stopped", "pending", "recovering", "needs_attention", "unreachable", "unknown"

  - `result.data.last_deploy` (object,null)
    Information about the most recent deploy, or null if the application has never deployed.

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

  - `result.data.last_deploy.result` (string)
    The result of the deploy.
    Enum: "success", "failed"

  - `result.data.last_deploy.timestamp` (string)
    When the deploy finished, in ISO 8601 format.
    Example: "2026-06-12T14:03:22.000Z"

  - `result.data.mode` (string,null)
    The application's run mode. Only meaningful for the server category; null otherwise.
    Enum: "production", "development"

  - `result.data.name` (string)
    The application's name (slug), unique across the
account. Use this value to address the application
in the per-app operations (configure, deploy,
and the lifecycle verbs). A name is assigned at
stage; staging a name a deployed application already
uses registers the new one under the next free
-N, so each application keeps a distinct
name.
    Example: "my-app"

  - `result.data.package_manager` (string)
    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).
    Enum: "npm", "yarn", "pnpm", "bun"

  - `result.data.runtime` (string)
    The application's runtime identifier.
    Example: "nodejs"

  - `result.data.runtime_tag` (string)
    The runtime version tag.
    Example: "22"

  - `result.data.source` (object)
    The application's source information.

  - `result.data.source.branch` (string,null)
    The Git branch, or null for ZIP sources.
    Example: "main"

  - `result.data.source.type` (string)
    The source type.

* zip — An uploaded archive.
* git — A Git repository.
    Enum: "zip", "git"

  - `result.data.source.url` (string,null)
    The Git repository URL, or null for ZIP sources.
    Example: "https://github.com/example/my-app.git"

  - `result.data.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.
    Example: true

  - `result.data.startup_command` (string,null)
    The application's configured startup command, or null for a static application (which has no running process to start). Set from the preflight-suggested default at stage, and overridable via configure.
    Example: "npm run start"

  - `result.data.status` (string)
    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.
    Enum: "created", "deploying", "running", "stopped", "errored"

  - `result.data.url` (string)
    The application's live HTTPS URL.
    Example: "https://my-app.example.com"

  - `result.data.use_existing_domain` (integer)
    Whether the application was confirmed onto a domain the account already used, replacing what that domain served. 0 for an application serving a domain it created itself. See https://go.cpanel.net/docroot2proxy.

  - `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 domain, env, or
env_text parameter was rejected.

* domain_in_use — Another of this account's applications already has this domain. No confirmation overrides this.
* domain_unavailable — The domain exists on the account as a non-webapp domain (the main domain, an addon domain, or a manually created subdomain), and use_existing_domain was not set.
* domain_temporary — The domain does not exist and sits under one of the server's temporary domains, which the system cannot create a domain beneath. Use the temporary domain itself, with use_existing_domain.
* env_not_editable — Values cannot be set because the application's repository would publish its .env file. See the env_status field on the application for which of the two mistakes it made. Clearing the environment is still allowed, since it publishes nothing.
    Enum: "domain_in_use", "domain_unavailable", "domain_temporary", "env_not_editable"

  - `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.