CPcpanel
WPX

Start a Nova for WordPress walkthrough

Changed on

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.
post/WPX/create_nova_for_wordpress_website

Request

  • Base URL
    https://cpanel-server.tld:2083/execute
  • Auth
    HTTP basic

Request body application/x-www-form-urlencoded

colorScheme'light' | 'dark' | 'auto' | ''

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.

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

promptTokenstring

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.

return_urlstring uri

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 request

{
  "colorScheme": "dark",
  "domain": "example.com",
  "promptToken": "QnVpbGQgbWUgYSBjb2ZmZWUgc2hvcCBzaXRl",
  "return_url": "https://cpanel-server.tld:2083/frontend/jupiter/index.html"
}

Response

HTTP Request was successful.

apiversioninteger

The version of the API.

funcstring

The name of the method called.

modulestring

The name of the module called.

Example response

{
  "apiversion": 3,
  "func": "create_nova_for_wordpress_website",
  "module": "WPX",
  "result": {
    "data": {
      "blocked_by": [
        "system_default"
      ],
      "domain": "example.com",
      "domain_package": "ea-php73",
      "domain_version": "7.3",
      "domain_version_source": "domain",
      "domain_version_vhost": "example.com",
      "effective_version": "7.3",
      "existing_installations": [
        {
          "id": 17,
          "url": "https://example.com"
        }
      ],
      "magic_link": "https://nova.example.com/magic/abc123",
      "required_version": "7.4",
      "status": "collision",
      "system_default_package": "ea-php73",
      "system_default_version": "7.3"
    },
    "metadata": {
      "transformed": 1
    },
    "status": 1
  }
}

Changes

  • 05239220da37Revision changes
    • warning

      added the new unsupported_php enum value to the // response property for the response status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • aed66b1a51ccRevision changes
    • info

      endpoint added