--- title: "Start a Nova for WordPress walkthrough" method: POST path: "/WPX/create_nova_for_wordpress_website" tags: ["WPX"] --- # Start a Nova for WordPress walkthrough `POST /WPX/create_nova_for_wordpress_website` ## Request - Base URL: `https://cpanel-server.tld:2083/execute` - URL: `https://cpanel-server.tld:2083/execute/WPX/create_nova_for_wordpress_website` - Auth: HTTP basic 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. ## Request body `application/x-www-form-urlencoded` - object - `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. - `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. - `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. - `return_url` string, 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. ## Response `200` HTTP Request was successful. - object - `apiversion` integer: The version of the API. - `func` string: The name of the method called. - `module` string: The name of the module called. - `result` object - `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. When the PHP version is below the WordPress minimum, it contains `status` set to `unsupported_php` and the `get_php_compatibility` fields. The `domain` value is always present. - `blocked_by` string[]: Which PHP versions fall below the minimum. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `compatible` 1 | 0: Whether WordPress can install. Always `0`. Present only when the `status` field is `unsupported_php`. - `domain` string: The domain, normalized to lowercase. - `domain_package` string, nullable: The PHP package the domain runs. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `domain_version` string, nullable: The domain's PHP version as `major.minor`. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `domain_version_source` 'domain' | 'system_default', nullable: Where the domain's PHP version comes from. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `domain_version_vhost` string, nullable: The virtual host whose PHP setting to change in MultiPHP Manager. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `effective_version` string, nullable: The PHP version that decided the refusal, as `major.minor`. Present only when the `status` field is `unsupported_php`. - `existing_installations` object[]: The WordPress installations that already exist on the domain. Present only when the `status` field is `collision`, and never empty in that case. - `id` integer: The WordPress Toolkit installation id. Pass it to `remove_installation`. - `url` string: The site URL of the existing WordPress installation. - `is_fallback` 1 | 0: Whether a PHP version lookup failed. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `magic_link` string: The Nova magic link the user follows to continue the walkthrough. Present on the normal start path. - `required_version` string: The minimum PHP version WordPress requires. Present only when the `status` field is `unsupported_php`. - `status` 'collision' | 'unsupported_php': Present only when the function refuses to start. - `collision` - The domain already has a WordPress installation. `existing_installations` is present. - `unsupported_php` - The PHP version is below the WordPress minimum. The `get_php_compatibility` function's return fields are present. - `system_default_package` string, nullable: The server's default PHP package. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `system_default_version` string, nullable: The server's default PHP version as `major.minor`. Present only when the `status` field is `unsupported_php`. See the `get_php_compatibility` function. - `errors` string[], nullable: List of errors if the API failed. - `messages` string[], nullable: List of messages generated by the API. - `metadata` object - `transformed` 1: Post-processing may have transformed the data. - `status` 1 | 0: - `1` - Success. - `0` - Failed: Check the errors field for more details. - `warnings` string[], nullable: List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running an API. ## Changes - **2026-11-04** `05239220da37`: 1 warning, 11 info - added the new `unsupported_php` enum value to the `result/data/status` response property for the response status `200` - added the optional property `result/data/blocked_by` to the response with the `200` status - added the optional property `result/data/compatible` to the response with the `200` status - added the optional property `result/data/domain_package` to the response with the `200` status - …8 more - **2026-09-23** `aed66b1a51cc`: 1 info - endpoint added [Operation history](https://skmtc.dev/cpanel/apis/cpanel-uapi/changes/WPX/create_nova_for_wordpress_website/post.md) --- [API](https://skmtc.dev/cpanel/apis/cpanel-uapi.md) - [All operations](https://skmtc.dev/cpanel/apis/cpanel-uapi/llms.txt) - [OpenAPI document](https://skmtc.dev/cpanel/apis/cpanel-uapi/revisions/05239220da37?raw)