# WPX

The WPX module for UAPI.

## Update WordPress administrator password

 - [POST /WPX/change_admin_password](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-change_admin_password.md): This function sets a new password for a WordPress administrator of an
installation that the caller owns.

  Note:

  - Over HTTP this function accepts only the POST method, and it rejects
    any request that carries a password key in the URL query string. It
    checks both before it reads the password, so the password cannot reach
    an access log, a proxy log, or the browser history. The Perl bindings
    and the uapi command-line tool set no request method and no query
    string, so they are unaffected.
  - The system passes the password to WordPress through a file that only the
    caller can read, so it never appears in a process list, in the process
    environment, or in the WordPress Toolkit logs.
  - The system applies no password-strength rule of its own. Any non-empty
    value is accepted.
  - The system verifies that the caller owns the installation before it
    changes anything.

## Start a Nova for WordPress walkthrough

 - [POST /WPX/create_nova_for_wordpress_website](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-create_nova_for_wordpress_website.md): This function starts a Nova for WordPress walkthrough for the
specified domain. It creates a cPanel API token and creates a
Nova magic link whose callback points directly at UAPI's import_website
function, then returns the magic link. It does not install WordPress.
The user is sent straight to Nova for WordPress, which builds the site
and publishes it back into the account via UAPI's import_website function.

  Note:

  - This function requires the nova-wordpress entitlement.
  - This function requires the mysql feature, because the WordPress
    install provisions a MySQL database.
  - This function also requires the redirects feature. An account
    without it receives a synchronous error before any token is created
    or any install task is queued.
  - This function requires the apitokens feature, because the
    walkthrough creates a cPanel API token.
  - Your account is handed off to Nova for WordPress. Nova's callback
    into UAPI's WPX::import_website function queues a WP Toolkit
    Site Import. So this function requires the
    wp-toolkit-site-import feature.
    An account without it receives a synchronous error before any
    token is created or any install task is queued. If an
    administrator has disabled wp-toolkit-site-import server-wide
    (the disabled feature list), the nova-wordpress feature itself
    becomes unavailable, and this function instead fails with the
    not-entitled error from the Nova for WordPress entitlement check.
  - If the domain already has one or more WordPress installations, the
    function returns a collision response listing the existing
    installations so the caller can prompt the user to remove them and
    retry.
  - The function refuses the call when the account has too little free
    disk space for a WordPress installation. That check runs before the
    token creation, so a refusal never leaves a live token behind.
  - Unlike create_website, this function does not enforce the
    account's maximum WordPress website count. That limit is a WordPress
    Toolkit plan constraint, and the Nova walkthrough deliberately does
    not gate on it.
  - If the Nova call fails after the token is created, the system revokes
    the token and returns an error, so a failed walkthrough leaves no
    live token.

## Start a new WordPress installation on a domain

 - [POST /WPX/create_website](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-create_website.md): This function starts a new WordPress installation on a domain that the
caller owns. The installation runs in the background, so the function
returns as soon as it queues the task.

  Note:

  - Poll progress with get_task_progress and the returned install_id
    value. That works with a cPanel API token, unlike the sse_url
    stream, which needs an interactive cPanel session.
  - A domain that already has a WordPress installation is not an error.
    The call succeeds with the status field set to collision and
    lists the existing installations, and it queues nothing. To replace
    the existing site, call remove_installation for each entry in
    the existing_installations field, then call this function again.
  - The data.status field reports the outcome of this call. Do not confuse
    it with the result.status field, which reports whether the call itself
    succeeded.
  - This function needs the redirects and mysql features in addition to
    the wp-toolkit feature that the whole module needs. It also refuses
    the call when the account has too little free disk space, or when the
    account already holds as many WordPress websites as its plan allows.
  - The background task can still fail after this function returns, for
    example when a feature is revoked in the meantime. Read the outcome from
    get_task_progress.

## Return WordPress administrator account

 - [GET /WPX/get_admin_account](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_admin_account.md): This function returns the WordPress administrator account details for an
installation that the caller owns: the administrator logins, the first
administrator's display name and email address, and the login URL. The
WordPress administration settings form uses it to fill in current values.

  Note:

  - The stored WordPress password is never returned. Use
    change_admin_password to set a new one, and get_credentials to sign
    in without a password.
  - The system verifies that the caller owns the installation before it
    reads anything.
  - When the installation has no WordPress administrator, the
    current_user_id field is null, the other text fields are empty
    strings, and the available_logins field is an empty array. A failure
    to read the administrator list is different: it returns a failure
    status with a message in the errors field.
  - The active WordPress language is not part of this response. Use
    set_language to change it.

## Return single-use WordPress login URL

 - [GET /WPX/get_credentials](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_credentials.md): This function returns a single-use login URL for a WordPress installation
that the caller owns. The URL carries a one-time token, so the caller does
not need the WordPress administrator password.

  Note:

  - Each call mints a new token, so the function is not idempotent and two
    calls return two different URLs. A token is consumed the first time it
    is used.
  - The login and password fields are always empty. They exist so the
    response shape stays stable for callers that expect a credential pair.
    This function never returns a WordPress password.
  - The system verifies that the caller owns the installation before it
    mints a token.

## Return PHP compatibility

 - [GET /WPX/get_php_compatibility](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_php_compatibility.md): This function reports whether the PHP version a WordPress installation
would run under meets the minimum that WordPress requires.

  Note:

  * Two PHP versions must pass: the server's system default PHP, which
    WordPress Toolkit uses while it stages the installation outside the
    document root, and the domain's own PHP, which serves the site
    afterwards.
  * A cPanel user can change a domain's PHP version in MultiPHP Manager,
    but only the hosting provider can change the system default.
  * The create_website, create_nova_for_wordpress_website, and
    import_website functions run the same check. When it fails, they
    return the status field set to unsupported_php with this
    function's data.

## Return WordPress installation activity

 - [GET /WPX/get_site_activity](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_site_activity.md): This function reports whether the account has done meaningful work on a
WordPress installation it owns. A WordPress site goes live the moment it
installs, and WordPress sends no event when real setup work finishes. So
the system compares the live site to a fresh installation and reports the
differences as flags.

  Note:

  - The has_user_activity field is the summary flag. It is 1 when the
    authored_content or uploaded_media field is 1. The remaining
    three flags are informational and do not affect it.
  - This function is expensive. It starts WordPress once to collect every
    signal, and the system stops the attempt after 30 seconds.
  - A site whose WordPress cannot start, or that does not answer within
    the 30-second limit, reports every flag as 0. This is not an error.
  - An id parameter that does not exist, or that belongs to another
    account, returns a failure status with a message in the errors
    field. The two cases are indistinguishable.
  - The system verifies that the caller owns the installation before it
    reads anything.

## Return WordPress task progress

 - [GET /WPX/get_task_progress](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_task_progress.md): This function returns the progress of a WordPress installation or import
for the supplied install_id parameter.

  Note:

  - Use this function to read progress with a cPanel API token. The
    equivalent Server-Sent Events stream (the sse_url field) is only
    available to an interactive cPanel session, not to an API token.
  - create_website and import_website return the install_id in
    their normal-start responses. Those are the only two functions that
    return one. create_nova_for_wordpress_website queues no
    installation task and returns no install_id value; a Nova walkthrough
    gets one when its later import_website callback starts the import.
  - This function is the authoritative source for progress and for
    success or failure, and it still works after the task finishes,
    because it reads the run's progress log. get_task_status reads the
    task queue instead, so it can only report whether the task is still
    queued, and it cannot tell success from failure.

## Return background task status

 - [GET /WPX/get_task_status](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_task_status.md): This function reports whether a queued background task is still in the
caller's task queue. It answers only that one question.

  Note:

  - This function and get_task_progress are a pair, and they are not
    interchangeable. get_task_status takes a task_id, reads the task
    queue, and reports only whether the task is still queued. It cannot
    tell you whether the work succeeded. get_task_progress takes an
    install_id parameter, reads the run's progress log, and is the authoritative
    source for progress and for success or failure. Prefer
    get_task_progress unless you specifically need to know whether the
    task is still queued.
  - A task_id parameter that is absent from the queue returns done. A finished
    task, a removed task, a task that never existed, and a task that
    belongs to another account are indistinguishable, and all four return
    done. There is no not-found failure.
  - Ownership needs no check: the queue lives in the caller's own home
    directory, so the caller can only ever see its own tasks.

## Return WordPress installation

 - [GET /WPX/get_website](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-get_website.md): This function returns a single WordPress installation, addressed by its
numeric WordPress Toolkit instance id parameter. The returned row is
identical to one element of the list_websites response, so the same
consumer mapping works for both.

  Note:

  - This is a lightweight by-id read intended for resolving one
    installation directly, without listing every installation. A direct
    lookup is not subject to the brief eventual-consistency lag that can
    keep a freshly created installation out of list_websites.
  - A valid id parameter that does not exist, or that belongs to another
    account, is not an error: the call succeeds with an empty (null)
    data field. An installation owned by another account is
    indistinguishable from one that does not exist.
  - A missing or non-integer id parameter, or a backend failure, returns
    a failure status with a message in the errors field.

## Return WordPress disk quota status

 - [GET /WPX/has_reached_quota](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-has_reached_quota.md): This function reports whether the caller's disk usage is already at or
near the limit that would block a new WordPress installation. The check
reserves headroom for the install itself, so it can report 1 before the
account has actually exceeded its quota.

  Note:

  - The onboarding flow calls this up front, before it offers to install
    WordPress, so it can explain the refusal instead of failing partway
    through create_website.
  - This function takes no parameters and has no failure path of its own,
    beyond the wp-toolkit feature that every function in this module
    needs. A caller that holds the feature always gets a successful status.
  - create_website repeats the same check and refuses with an error when
    the quota blocks the install.

## Import an existing WordPress site

 - [POST /WPX/import_website](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-import_website.md): This function imports an existing WordPress site to your cPanel account.
The import runs in the background, so the function returns as soon as it
queues the task.

  Note:

  - This function has the following prerequisites:
      - The nova-wordpress entitlement.
      - The redirects, wp-toolkit, wp-toolkit-site-import, and
        mysql features.
  - Because the request carries the source WordPress credentials, use the
    POST method and do not place the source_password or source_user
    keys in the URL query string. The system rejects a request that uses
    another method, or that puts either key in the query string, before it
    reads the credentials, so they cannot leak into access logs, proxy
    logs, or browser history.
  - The background task can still fail after this function returns, for
    example when a feature is revoked in the meantime. Read the outcome
    from the WPX::get_task_progress function.

## Return active WordPress installs

 - [GET /WPX/list_active_installs](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-list_active_installs.md): This function lists the WordPress installs that are still queued or
running for the account. It joins each queued install task to the run's
progress log, so status is the value get_task_progress reports.

  Note:

  * This function reads the task queue without taking element locks, so
    it never fails or blocks when another reader or the task runner
    briefly holds an element.
  * A task that is queued but has not written a log line yet reports
    unknown with a percentage of 0.
  * An element in the queue is not proof that an install is in flight. If
    the task runner dies mid-install (reboot, OOM kill) the element stays
    in the queue until the account queues another task. The function
    reports such a row as stale when its log says running but the
    runner's pid file names a process that is gone or is not a task
    runner.
  * A finished install leaves the queue when the runner completes it. It
    can appear once with complete or failed in the short window
    before that removal.
  * The rows need no ownership check: the queue and the logs live in
    the caller's own home directory, so the caller can only ever see
    its own installs.

## Return WordPress installations

 - [GET /WPX/list_websites](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-list_websites.md): This function returns the caller's WordPress installations. Each row is
identical in shape to the get_website response data, so the same
consumer mapping works for both.

  Note:

  - Ownership is enforced by filesystem path: only installations under the
    caller's home directory are returned.
  - Each row carries the installation's health as flat flags
    (alive, broken, infected, outdated_php, outdated_wp,
    unsupported_php, unsupported_wp), taken directly from WordPress
    Toolkit.

## Delete a WordPress installation permanently

 - [POST /WPX/remove_installation](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-remove_installation.md): This function permanently deletes a WordPress installation that the caller
owns. It removes the site's files and its database.

  Note:

  - This action cannot be undone. There is no recycle bin, and the system
    keeps no copy of the files or the database.
  - The onboarding flow calls this to clear an existing installation before
    it retries create_website. When create_website reports a
    collision, call this function once for each entry in the
    existing_installations field, then call create_website again.
  - This function is not idempotent. A second call for the same id
    parameter fails, because the installation no longer exists.
  - The system verifies that the caller owns the installation before it
    deletes anything. An installation that belongs to another account is
    indistinguishable from one that does not exist.

## Update WordPress installation language

 - [POST /WPX/set_language](https://api.docs.cpanel.net/specifications/cpanel.openapi/wpx/wpx-set_language.md): This function sets the active WordPress language for an installation that
the caller owns. The system installs the translation files if the site does
not already have them, then activates the locale.

  Note:

  - The system verifies that the caller owns the installation before it
    changes anything.
  - get_admin_account does not report the active language. There is no
    function that reads it back.