GoDaddy Node.js Hosting API Tutorial: Deploy with Preview

Getting a Node.js application to run on your computer is only half the job; making it available to real users requires deployment, configuration and a way to verify that the live version works. GoDaddy’s Hosting API now lets developers automate that process through code instead of completing every step in a dashboard. This GoDaddy Node.js Hosting API tutorial walks through creating an app, uploading its source, testing a preview and publishing it to production, while explaining the checks that prevent a failed deployment from becoming a live problem.

What the GoDaddy Hosting API actually automates

GoDaddy introduced its Hosting API on September 29, 2026, giving developers a programmatic way to create and manage hosted Node.js applications. The API covers application creation, source uploads, hosting-plan attachment, deployments, environment secrets, logs and custom-domain management. A developer can call these operations from a script, use GoDaddy’s command-line interface, or give a compatible AI coding agent permission to carry them out.

The important distinction is that this is not a universal hosting API for every application framework or runtime. The documented hosting workflow currently supports Node.js applications, and publishing requires a compatible Web Hosting plan attached to the app. Previewing can happen before a plan is attached, which makes it possible to test the deployment workflow before committing to a production release.

Prepare a Node.js project that the platform can build

Before making API calls, check the project structure. The ZIP archive you upload must contain package.json at its root, with non-empty name and version fields. The platform expects both build and start scripts, installs runtime packages from dependencies, and starts the app through the start script. If the archive contains an extra parent folder instead of the project files at its root, the build can fail even when the application works locally.

For a minimal application that does not need a compilation step, the package configuration can look like this:

{
 "name": "hosting-api-demo",
 "version": "1.0.0",
 "engines": {
 "node": "20.x"
 },
 "scripts": {
 "build": "echo build",
 "start": "node index.js"
 },
 "dependencies": {
 "express": "^4.18.0"
 }
}

This is a starting configuration, not a complete application. Use a real build command for frameworks such as Next.js, NestJS or TypeScript projects when compilation is required. Also ensure the server listens on the port supplied by the hosting environment rather than assuming that port 3000 will always be available.

const port = process.env.PORT || 3000;

app.listen(port, () => {
 console.log(`Server listening on port ${port}`);
});

Before packaging the project, install and test its dependencies locally. Include the package files, application source and required static assets, but exclude node_modules and files containing local secrets, such as .env. The hosting platform installs dependencies during its build process, so uploading your local dependency directory is unnecessary and can create compatibility problems.

Create a token with only the permissions you need

The Hosting API authenticates requests using a Personal Access Token (PAT), a credential issued through GoDaddy’s developer portal. Create a token with the permissions needed for the deployment workflow rather than granting every available permission. For the initial create-upload-publish process, the documented scopes include hosting.application:create, hosting.application:read, hosting.source:write, hosting.deployment:execute and hosting.subscription:write.

Set the token and the API gateway base address in your local shell as environment variables. The following commands use placeholders deliberately: supply the values for your account and environment, and do not paste a real token into source control or an article.

export GODADDY_PAT="YOUR_PERSONAL_ACCESS_TOKEN"
export BASE_URL="YOUR_API_GATEWAY_BASE_ADDRESS"

On Windows PowerShell, use environment-variable syntax appropriate to that shell instead. Keep the token outside the application ZIP and never expose it in browser-side JavaScript. A deployment script should read the credential from its environment, while access permissions should be limited to the operations that script performs.

Create the hosting app and wait for provisioning to finish

The first API request creates a Node.js hosting application. A successful request does not necessarily mean the app is ready immediately: the endpoint returns 202 Accepted with an operation record. This is an asynchronous workflow, meaning the server acknowledges the request first and completes the underlying task later.

curl -s -X POST \
 "$BASE_URL/v1/hosting/apps?appType=NODEJS" \
 -H "Authorization: Bearer $GODADDY_PAT" \
 -H "Content-Type: application/json" \
 -d '{"name":"hosting-api-demo"}'

Read the response and capture its operation identifier or self link. Use the returned operation information to query the corresponding application-operation endpoint until its status becomes COMPLETED or FAILED. On success, save the resulting application ID because the subsequent source upload, subscription attachment and deployment requests depend on it. If the operation fails, inspect the error response before trying again rather than creating duplicate apps unnecessarily.

This polling step is not busywork. A script that sends the next request immediately may attempt to upload code before the platform has provisioned the application. Production automation should implement a bounded polling interval, a timeout and explicit handling for failed or unexpected statuses.

Upload the ZIP archive and check the preview

Once the application exists, upload the project as a ZIP archive through the source-import endpoint. Replace APP_ID with the identifier returned by the successful creation operation and make sure the archive path points to the file you prepared.

curl -s -X POST \
 "$BASE_URL/v1/hosting/apps/$APP_ID/imports" \
 -H "Authorization: Bearer $GODADDY_PAT" \
 -F "file=@./hosting-api-demo.zip"

The upload also runs asynchronously. Capture the import identifier and poll the matching import-status endpoint until it reaches COMPLETED or FAILED. An accepted upload is not proof that the source is valid or that the application starts correctly. If the import fails, check the archive layout, the root-level package file and the build output before uploading again.

GoDaddy gives each app two environments, called PREVIEW and PUBLISH. New source uploads go to preview, which is intended for iteration and testing; publishing promotes the current preview version to the live environment. Use the preview URL returned in the application details to test the deployed app, including its main route, required configuration, API calls and any database connections it needs.

Attach a hosting plan before publishing

For Node.js applications, a compatible Web Hosting subscription must be attached before the production deployment can proceed. Retrieve a valid subscription ID from the account’s available hosting plans, then attach it to the application. The documented operation is synchronous, so this particular step does not use the same polling pattern as application creation or deployment.

curl -s -X PUT \
 "$BASE_URL/v1/hosting/apps/$APP_ID/subscription" \
 -H "Authorization: Bearer $GODADDY_PAT" \
 -H "Content-Type: application/json" \
 -d '{"subscriptionId":"YOUR_SUBSCRIPTION_ID"}'

Do not assume that preview access means production hosting is included without a plan. Check that the subscription belongs to the correct account and is eligible for the app. If you do not already have a suitable plan, the platform documentation describes obtaining one through GoDaddy’s Shopping API; purchasing a plan is a separate action with its own financial implications.

Publish the tested version and verify the live status

After preview testing and plan attachment, trigger a deployment. The endpoint builds the latest imported source and promotes it to the publish environment. Like creation and import, deployment returns an asynchronous operation that must be checked until it reaches a terminal state.

curl -s -X POST \
 "$BASE_URL/v1/hosting/apps/$APP_ID/deployments" \
 -H "Authorization: Bearer $GODADDY_PAT" \
 -H "Content-Type: application/json" \
 -d '{}'

Save the deployment identifier from the response and poll its deployment-status endpoint. Continue only when the deployment reports COMPLETED; if it reports FAILED, investigate the build or runtime error instead of repeatedly triggering deployments. Then retrieve the app status and inspect the PUBLISH variant to confirm that the production environment is up. The application record also contains environment URLs, allowing your script to distinguish the preview address from the live one.

A completed deployment is a useful platform-level signal, but it is not a substitute for application-level verification. Make a request to the live app, check a representative user journey and verify that essential integrations work. If the app depends on a database, payment provider or third-party API, test those connections with the production configuration rather than assuming that preview success guarantees production success.

Keep secrets separate and diagnose failures through logs

Applications commonly need database credentials, API keys or other environment variables. The Hosting API supports secrets separately for preview and publish, so the test environment can use test credentials while production uses its own values. Secret updates use JSON Patch operations, and the API deliberately does not return secret values when you read secret metadata. That behaviour helps reduce accidental exposure, but it also means you must retain secrets securely in the system that manages them.

For example, a deployment workflow might configure a test database connection for preview and a production database connection for publish. Do not copy a production payment key into preview simply to make a test pass. Give each environment only the credentials it needs, and request the hosting.secret:write scope only when the automation must modify secrets.

If the app does not start, use the logs endpoint to inspect the relevant environment. Logs can be filtered by environment, output stream, severity and time range; the documented API supports requests for up to seven days of history. Look for missing modules, failed build commands, absent environment variables and port-binding errors. A 401 response usually calls for checking token validity and scopes, while a 429 response means the rate limit has been reached and should prompt a controlled retry with backoff.

Turn the workflow into reliable deployment automation

The API makes it possible to script the full lifecycle, but reliable automation needs more than a sequence of commands. Treat each asynchronous response as a checkpoint, persist the identifiers returned by the platform, and stop the workflow when a required operation fails. Before retrying a write request, check the operation’s current state; sending the same create or publish request again without checking can create duplicate work or trigger an unnecessary deployment.

For a first implementation, keep the process deliberately small: prepare a valid ZIP, create one app, wait for provisioning, import the source, wait for import completion, test preview, attach the hosting plan, publish, and verify the production status. Add automated health checks and controlled rollback procedures only after the basic sequence behaves predictably. GoDaddy’s current Hosting API documentation is focused on Node.js, so developers using PHP or another runtime should confirm platform support rather than assume that the same endpoints can deploy their existing application unchanged.

The practical benefit is a repeatable path from a tested codebase to a live application without manually repeating every hosting step. The next improvement is to make your deployment script report the exact failed stage, preserve its operation IDs and refuse to publish unless preview checks pass. That turns an API-driven deployment from a convenient shortcut into a process your team can inspect, troubleshoot and trust.