# Start a new WordPress installation on a domain

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.

Endpoint: POST /WPX/create_website
Version: 11.138.0.10
Security: BasicAuth

## Request fields (application/x-www-form-urlencoded):

  - `domain` (string, required)
    The domain to install WordPress on. The cPanel account must own the domain, and the domain must have its own document root. The system normalizes the value to lowercase.
    Example: "example.com"

  - `title` (string)
    The WordPress site title. When you omit this parameter, the system
uses the domain name as the title. The system rejects a title longer
than 253 characters or one that holds control characters, but it
does that in the background task, not in this call: an invalid title
still returns a successful status, then fails the installation. Read
the failure from get_task_progress.
    Example: "My Blog"

## Response 200 fields (application/json):

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

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

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

  - `result` (object)

  - `result.data` (object)
    On the normal start path the object contains the status,
domain, task_id, sse_url, and install_id return
values. When the domain already has a WordPress
installation, the object instead contains the status
field set to collision, plus the domain and
existing_installations fields.

  - `result.data.domain` (string)
    The domain, normalized to lowercase.
    Example: "example.com"

  - `result.data.existing_installations` (array)
    The WordPress installations that already exist on the domain. Present only when the status field is collision, and never empty in that case.

  - `result.data.existing_installations.id` (integer)
    The WordPress Toolkit installation id. Pass it to remove_installation.
    Example: 17

  - `result.data.existing_installations.url` (string)
    The site URL of the existing installation. This is an empty string when the system could not determine it.
    Example: "https://example.com"

  - `result.data.install_id` (string)
    The unique correlator for the installation run. Pass it to get_task_progress to poll progress with a cPanel API token. Present only when the status field is running.
    Example: "1784237244-988110-12345"

  - `result.data.sse_url` (string)
    The path to the Server-Sent Events stream that reports installation progress. This is a path, not a full URL. Resolve it against the cPanel host that served the request. An interactive cPanel session can read this stream, but a cPanel API token cannot. Present only when the status field is running.
    Example: "/sse/UserTasks/00000000_63d7f020927f8f/wpx_install_1784237244-988110-12345.log"

  - `result.data.status` (string)
    The outcome of this call.
- running - The system queued the installation task.
  The task_id, sse_url, and install_id fields are
  present.
- collision - The domain already has a WordPress
  installation. The existing_installations field is
  present, and the system queued nothing.
    Enum: "running", "collision"

  - `result.data.task_id` (string)
    The queued installation task id. Pass it to get_task_status to check whether the task is still queued. Present only when the status field is running.
    Example: "00000000/63d7f020927f8f"

  - `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.transformed` (integer)
    Post-processing may have transformed the data.
    Enum: 1

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

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