# Start a Nova for WordPress walkthrough

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

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

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

  - `colorScheme` (string)
    The color scheme the caller's interface is using, so Nova for
WordPress opens in the same theme.

Note:

If you do not use this parameter, Nova will select the color
scheme.
    Enum: "light", "dark", "auto", ""

  - `domain` (string, required)
    The domain on which to start the WordPress walkthrough. 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"

  - `promptToken` (string)
    A base64-encoded website-building prompt that Nova for WordPress opens with,
pre-filled. This allows hosting companies to collect user intent before the
walkthrough and pass it through, which is the only route available to an
integration that drives cPanel entirely through the API.

Requirements:

  * Valid base64 encoding. You can use standard or URL-safe
    variants, with or without padding.
  * Maximum 5000 bytes after the system decodes it. This limit is
    separate from the maxLength cap on the value you send, and each
    one reports its own error. The system measures the decoded prompt
    in bytes, not characters, so non-ASCII text reaches that limit
    sooner. UTF-8 encodes an accented letter as two bytes and an
    emoji as four.
  * The system fails the call for a malformed or over-long value, before
    it creates an API token.
  * The system treats an empty or whitespace-only prompt as though you
    had omitted the parameter, which means it falls back to the prompt
    from session creation and uses that one up.


Note:

  Omitting this parameter does not necessarily mean that Nova opens with an
  empty prompt. When a hosting provider states a prompt for the account at
  session creation, the system uses that one instead. When you pass a value
  here, the system sends it and leaves any prompt from session creation in
  place, because that prompt may belong to a different walkthrough.
    Example: "QnVpbGQgbWUgYSBjb2ZmZWUgc2hvcCBzaXRl"

  - `return_url` (string)
    The URL to which Nova returns the user after the walkthrough. This
must be an https URL on the same cPanel host that serves the
request, it must be 2048 characters or fewer, and it must not
contain a userinfo (@) component. A value that fails any of these
checks is ignored rather than rejected, and the system substitutes
a default derived from the Nova partner URL.
    Example: "https://cpanel-server.tld:2083/frontend/jupiter/index.html"

## Response 200 fields (application/json):

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

  - `func` (string)
    The name of the method called.
    Example: "create_nova_for_wordpress_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
magic_link return value. When the domain already has
a WordPress installation, the object instead contains
the status value set to collision and the
existing_installations value. The domain value is
always present.

  - `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 WordPress installation.
    Example: "https://example.com"

  - `result.data.magic_link` (string)
    The Nova magic link the user follows to continue the walkthrough. Present on the normal start path.
    Example: "https://nova.example.com/magic/abc123"

  - `result.data.status` (string)
    This value only returns when the function detects an existing installation on the domain.
    Enum: "collision"

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