NewHost Docs

API reference

Applications

Node.js / Next.js applications, their deployments and environment variables.

Try these requests in Postman: Download Postman collection (how to use it).

List applications

GET/v1/apps

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
limitqueryintegerItems per page, 1-100 (default 50).
offsetqueryintegerItems to skip (default 0).

Request

curl "https://api.newhost.co.za/v1/apps" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8app0001",
      "name": "Shop front",
      "slug": "shop-front",
      "framework": "NEXTJS",
      "nodeVersion": "22",
      "repoUrl": "https://github.com/acme/shop.git",
      "branch": "main",
      "installCommand": "npm ci",
      "buildCommand": "npm run build",
      "startFile": "server.js",
      "primaryDomain": "shop-front.apps.newhost.co.za",
      "status": "RUNNING",
      "autoDeploy": true,
      "previewDeploys": false,
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-20T10:15:00.000Z"
    }
  ],
  "has_more": false
}

Create an application

POST/v1/apps

Creates the site on a NewHost server and starts the first deployment. Counts towards your plan's app limit.

Requires a secret key with the write scope. Returns 201 on success.

Body

FieldTypeDescription
namerequiredstringDisplay name (2-60 characters).
frameworkrequiredstringNEXTJS, NODE, EXPRESS or NUXT (default NEXTJS).
repoUrlstringGit repository (https:// or git@).
branchstringBranch to deploy (default main).
nodeVersionstringNode.js major version: 24, 22 (default) or 20.
customDomainstringYour own domain. Left out: the domain chosen when your app plan was ordered, while no app uses it, else <slug>.apps.newhost.co.za; send an empty string for the free address. Changed October 2026: left out, it can be your plan's domain.
deployNowbooleanStart the first deployment immediately (default true).
installCommandstringDefault npm ci.
buildCommandstringe.g. npm run build.
startFilestringEntry file, e.g. server.js.

Request

curl -X POST "https://api.newhost.co.za/v1/apps" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Shop front","framework":"NEXTJS","repoUrl":"https://github.com/acme/shop.git","branch":"main"}'

Response

{
  "data": {
    "id": "clx8app0001",
    "name": "Shop front",
    "slug": "shop-front",
    "framework": "NEXTJS",
    "nodeVersion": "22",
    "repoUrl": "https://github.com/acme/shop.git",
    "branch": "main",
    "installCommand": "npm ci",
    "buildCommand": "npm run build",
    "startFile": "server.js",
    "primaryDomain": "shop-front.apps.newhost.co.za",
    "status": "RUNNING",
    "autoDeploy": true,
    "previewDeploys": false,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-20T10:15:00.000Z"
  }
}

Retrieve an application

GET/v1/apps/{id}

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.

Request

curl "https://api.newhost.co.za/v1/apps/ID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8app0001",
    "name": "Shop front",
    "slug": "shop-front",
    "framework": "NEXTJS",
    "nodeVersion": "22",
    "repoUrl": "https://github.com/acme/shop.git",
    "branch": "main",
    "installCommand": "npm ci",
    "buildCommand": "npm run build",
    "startFile": "server.js",
    "primaryDomain": "shop-front.apps.newhost.co.za",
    "status": "RUNNING",
    "autoDeploy": true,
    "previewDeploys": false,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-20T10:15:00.000Z"
  }
}

Update an application

PATCH/v1/apps/{id}

Requires a secret key with the write scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.

Body

FieldTypeDescription
branchstringBranch to deploy.
nodeVersionstringNode.js major version.
installCommandstringInstall command.
buildCommandstring | nullBuild command.
startFilestringEntry file.
autoDeploybooleanDeploy on every push to the branch.
previewDeploysbooleanDeploy pushes to other branches as previews (Developer plan and up; needs a linked repository).

Request

curl -X PATCH "https://api.newhost.co.za/v1/apps/ID" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"branch":"release","autoDeploy":false}'

Response

{
  "data": {
    "id": "clx8app0001",
    "name": "Shop front",
    "slug": "shop-front",
    "framework": "NEXTJS",
    "nodeVersion": "22",
    "repoUrl": "https://github.com/acme/shop.git",
    "branch": "release",
    "installCommand": "npm ci",
    "buildCommand": "npm run build",
    "startFile": "server.js",
    "primaryDomain": "shop-front.apps.newhost.co.za",
    "status": "RUNNING",
    "autoDeploy": false,
    "previewDeploys": false,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-20T10:15:00.000Z"
  }
}

Delete an application

DELETE/v1/apps/{id}

Removes the site and its files from the server. This cannot be undone.

Requires a secret key with the write scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.

Request

curl -X DELETE "https://api.newhost.co.za/v1/apps/ID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8app0001",
    "deleted": true
  }
}

Trigger a deployment

POST/v1/apps/{id}/deployments

Pulls the configured branch, installs, builds and restarts the app. Deployments run one at a time per app: this one is queued, and a request while another is still queued replaces it. Poll the deployment or subscribe to deployment.* webhooks.

Requires a secret key with the deploy scope. Returns 202 on success.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.

Request

curl -X POST "https://api.newhost.co.za/v1/apps/ID/deployments" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8dep0001",
    "applicationId": "clx8app0001",
    "status": "QUEUED",
    "trigger": "API",
    "commitSha": "9f2c1ab",
    "startedAt": "2026-09-20T10:15:00.000Z",
    "finishedAt": null
  }
}

List branch previews

GET/v1/apps/{id}/previews

With previewDeploys on, every push to a branch other than the app's branch deploys to <branch>--<app>.apps.newhost.co.za. Deleting the branch removes its preview; previews idle for 14 days are removed automatically. Up to 5 per app.

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.
limitqueryintegerItems per page, 1-100 (default 50).
offsetqueryintegerItems to skip (default 0).

Request

curl "https://api.newhost.co.za/v1/apps/ID/previews" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8pre0001",
      "applicationId": "clx8app0001",
      "branch": "feature/checkout",
      "hostname": "feature-checkout--shop-front.apps.newhost.co.za",
      "url": "https://feature-checkout--shop-front.apps.newhost.co.za",
      "status": "RUNNING",
      "commitSha": "4be1d0c",
      "lastDeployedAt": "2026-09-21T09:02:11.000Z",
      "createdAt": "2026-09-21T08:58:40.000Z"
    }
  ],
  "has_more": false
}

Redeploy a preview

POST/v1/apps/{id}/previews/{previewId}

Fetches the preview's branch again and redeploys it.

Requires a secret key with the deploy scope. Returns 202 on success.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.
previewIdrequiredpathstringThe preview ID.

Request

curl -X POST "https://api.newhost.co.za/v1/apps/ID/previews/PREVIEWID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8dep0002",
    "applicationId": "clx8app0001",
    "previewId": "clx8pre0001",
    "status": "QUEUED",
    "trigger": "API",
    "startedAt": "2026-09-21T09:10:00.000Z"
  }
}

Delete a preview

DELETE/v1/apps/{id}/previews/{previewId}

Removes the preview site from the server.

Requires a secret key with the deploy scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.
previewIdrequiredpathstringThe preview ID.

Request

curl -X DELETE "https://api.newhost.co.za/v1/apps/ID/previews/PREVIEWID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8pre0001",
    "deleted": true
  }
}

List backups

GET/v1/apps/{id}/backups

Automatic backups run off peak: weekly on Starter (kept 4 weeks), daily on Developer (7 days), Business and Agency (30 days). Files, databases and mail of the app's site are included.

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.
limitqueryintegerItems per page, 1-100 (default 50).
offsetqueryintegerItems to skip (default 0).

Request

curl "https://api.newhost.co.za/v1/apps/ID/backups" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8bak0001",
      "applicationId": "clx8app0001",
      "status": "SUCCESS",
      "trigger": "SCHEDULE",
      "fileName": "nhk2x9backup_2609250114.tar",
      "sizeBytes": 48213377,
      "error": null,
      "startedAt": "2026-09-25T01:14:00.000Z",
      "finishedAt": "2026-09-25T01:16:31.000Z"
    }
  ],
  "has_more": false
}

Start a backup

POST/v1/apps/{id}/backups

One on-demand backup every 10 minutes. Status starts as RUNNING; poll the list or subscribe to backup.succeeded / backup.failed.

Requires a secret key with the deploy scope. Returns 202 on success.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.

Request

curl -X POST "https://api.newhost.co.za/v1/apps/ID/backups" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8bak0001",
    "applicationId": "clx8app0001",
    "status": "RUNNING",
    "trigger": "MANUAL",
    "fileName": null,
    "sizeBytes": null,
    "error": null,
    "startedAt": "2026-09-25T01:14:00.000Z",
    "finishedAt": null
  }
}

List deployments

GET/v1/apps/{id}/deployments

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.
limitqueryintegerItems per page, 1-100 (default 50).
offsetqueryintegerItems to skip (default 0).

Request

curl "https://api.newhost.co.za/v1/apps/ID/deployments" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8dep0001",
      "applicationId": "clx8app0001",
      "status": "SUCCEEDED",
      "trigger": "API",
      "commitSha": "9f2c1ab",
      "startedAt": "2026-09-20T10:15:00.000Z",
      "finishedAt": "2026-09-20T10:17:42.000Z"
    }
  ],
  "has_more": false
}

Retrieve a deployment

GET/v1/deployments/{id}

Includes the build log, and skippedSteps: the steps the deployment went on without (each { step, detail }; empty when every step ran), as the deployment.succeeded webhook sends them.

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe deployment ID.

Request

curl "https://api.newhost.co.za/v1/deployments/ID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8dep0001",
    "applicationId": "clx8app0001",
    "status": "SUCCEEDED",
    "trigger": "API",
    "commitSha": "9f2c1ab",
    "startedAt": "2026-09-20T10:15:00.000Z",
    "finishedAt": "2026-09-20T10:17:42.000Z",
    "log": "[10:15:02] git fetch origin main\n[10:17:40] started",
    "skippedSteps": []
  }
}

Replace environment variables

PUT/v1/apps/{id}/env

Replaces the full set. Values are encrypted and never returned; send an empty value to keep a stored secret. Redeploy to apply.

Requires a secret key with the write scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe app ID.

Body

FieldTypeDescription
varsrequiredarrayList of { key, value } pairs.

Request

curl -X PUT "https://api.newhost.co.za/v1/apps/ID/env" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"vars":[{"key":"DATABASE_URL","value":"postgres://..."},{"key":"NEXT_PUBLIC_SITE","value":"https://shop.example.com"}]}'

Response

{
  "data": {
    "keys": [
      "DATABASE_URL",
      "NEXT_PUBLIC_SITE"
    ]
  }
}

Next: Databases →