API reference

Applications

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

List applications GET /v1/apps
Create an application POST /v1/apps
Retrieve an application GET /v1/apps/{id}
Update an application PATCH /v1/apps/{id}
Delete an application DELETE /v1/apps/{id}
Trigger a deployment POST /v1/apps/{id}/deployments
List deployments GET /v1/apps/{id}/deployments
Retrieve a deployment GET /v1/deployments/{id}
Replace environment variables PUT /v1/apps/{id}/env

List applications

GET/v1/apps

Requires a secret key with the read scope.

Parameters

Name	In	Type	Description
`limit`	query	integer	Items per page, 1-100 (default 50).
`offset`	query	integer	Items 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,
      "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

Field	Type	Description
`name`required	string	Display name (2-60 characters).
`framework`required	string	NEXTJS, NODE, EXPRESS or NUXT (default NEXTJS).
`repoUrl`	string	Git repository (https:// or git@).
`branch`	string	Branch to deploy (default main).
`nodeVersion`	string	Node.js major version: 24, 22 (default) or 20.
`customDomain`	string	Your own domain; defaults to <slug>.apps.newhost.co.za.
`deployNow`	boolean	Start the first deployment immediately (default true).
`installCommand`	string	Default npm ci.
`buildCommand`	string	e.g. npm run build.
`startFile`	string	Entry 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,
    "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

Name	In	Type	Description
`id`required	path	string	The 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,
    "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

Name	In	Type	Description
`id`required	path	string	The app ID.

Body

Field	Type	Description
`branch`	string	Branch to deploy.
`nodeVersion`	string	Node.js major version.
`installCommand`	string	Install command.
`buildCommand`	string \| null	Build command.
`startFile`	string	Entry file.
`autoDeploy`	boolean	Deploy on every push to the branch.

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,
    "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

Name	In	Type	Description
`id`required	path	string	The 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. Poll the deployment or subscribe to deployment.* webhooks.

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

Parameters

Name	In	Type	Description
`id`required	path	string	The 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 deployments

GET/v1/apps/{id}/deployments

Requires a secret key with the read scope.

Parameters

Name	In	Type	Description
`id`required	path	string	The app ID.
`limit`	query	integer	Items per page, 1-100 (default 50).
`offset`	query	integer	Items 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.

Requires a secret key with the read scope.

Parameters

Name	In	Type	Description
`id`required	path	string	The 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"
  }
}

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

Name	In	Type	Description
`id`required	path	string	The app ID.

Body

Field	Type	Description
`vars`required	array	List 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.acme.co.za"}]}'

Response

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

Next: Databases →