Getting started
Deploy your first Node.js app end to end — obtain an access token, create an app, upload code, publish, and verify.
This walkthrough deploys a Node.js app from scratch using nothing but curl. Every write operation is async. You get back a job or deployment id and poll until it is ready.
Every code block uses $BASE_URL for the API gateway host and $TOKEN for your OAuth 2.0 access token. See Authentication for how to obtain the token; the base URL is provided by the GoDaddy API gateway when you request access.
Prerequisites
- OAuth 2.0 client credentials with the following scopes:
hosting.paas.apps:create,hosting.paas.apps:read,hosting.paas.code:write,hosting.paas.deploy:execute. - A zipped Node.js application. The zip's root should contain your
package.jsonand application entry point. curlandjq(or your language's HTTP client — the flow is the same shape everywhere).
1. Get an access token
Exchange your client credentials for a bearer token. See Authentication for the full flow.
export TOKEN=$(curl -s -X POST https://oauth.api.godaddy.com/v2/oauth2/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials" \
-d "scope=hosting.paas.apps:create hosting.paas.apps:read hosting.paas.code:write hosting.paas.deploy:execute" \
| jq -r .access_token)2. Create an app
POST /apps accepts a name and returns 202 with a job id. The app isn't ready to receive code until the job reaches active.
JOB=$(curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "my-first-app" }')
JOB_ID=$(echo "$JOB" | jq -r .job.id)
echo "Job accepted: $JOB_ID"Poll GET /apps/jobs/{jobId} until job.status is active. When it flips, the response also includes the fully-formed app object.
until STATUS=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/jobs/$JOB_ID" \
-H "Authorization: Bearer $TOKEN" | jq -r .job.status) && [ "$STATUS" = "active" ]; do
echo " ...still $STATUS"
sleep 3
done
APP_ID=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/jobs/$JOB_ID" \
-H "Authorization: Bearer $TOKEN" | jq -r .app.id)
echo "App ready: $APP_ID"Terminal states are active (success) and failed (fatal — start over with a corrected request).
3. Upload your source
Package the app as a zip, then POST /apps/{appId}/source as multipart/form-data. This lands on the preview variant.
UPLOAD=$(curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/source" \
-H "Authorization: Bearer $TOKEN" \
-F "zipFile=@./my-app.zip")
UPLOAD_JOB=$(echo "$UPLOAD" | jq -r .jobId)Poll the upload job at GET /apps/{appId}/source/status?jobId=... until it terminates.
until echo "$RESP" | jq -e '.status | test("succeeded|failed")' >/dev/null 2>&1; do
RESP=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/source/status?jobId=$UPLOAD_JOB" \
-H "Authorization: Bearer $TOKEN")
echo " upload: $(echo "$RESP" | jq -r .status)"
sleep 2
done4. Publish
Publishing takes the current preview source and promotes it to the publish variant. POST /apps/{appId}/deployments returns a deployment record. Poll the deployments list and app status to observe rollout.
curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/deployments" \
-H "Authorization: Bearer $TOKEN"Watch runtime status flip to running on the publish variant:
until curl -s "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/status" \
-H "Authorization: Bearer $TOKEN" \
| jq -e '.variants[] | select(.variant == "publish") | .status == "running"' >/dev/null; do
echo " ...deploying"
sleep 5
done
echo "Live."5. Roll back (when you need it)
If a publish goes sideways, list past deployments and roll back to a known-good id:
DEPLOYMENT_ID=$(curl -s "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/deployments?limit=5" \
-H "Authorization: Bearer $TOKEN" | jq -r '.deployments[1].id')
curl -s -X POST "$BASE_URL/v1/hosting/nodejs/apps/$APP_ID/rollback" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"deploymentId\": \"$DEPLOYMENT_ID\" }"Rollback is asynchronous like publish — poll /deployments and /status the same way.
Rollback returns 403 if the feature isn't enabled for your account. If you see one, contact GoDaddy hosting support to opt in.
What's next
Concepts
Variants, deployments, async jobs, and how they all fit together.
Authentication
OAuth 2.0 client credentials, scopes, and token handling in detail.
API reference
Every endpoint, request shape, and response shape.
Agent & Automation Notes
hosting.paas.apps:create, hosting.paas.apps:read, hosting.paas.code:write, hosting.paas.deploy:executeRelated
Last updated on
How is this guide?