NewHost Docs

Getting started

This guide takes you from no key to a deployment triggered by your own code.

1. Create an API key

  1. Sign in at app.newhost.co.za → Developers.
  2. Click Create API key, give it a name (e.g. "CI deploys") and tick only the scopes it needs: read, write, deploy or domains.
  3. Copy the secret key (sk_live_…). It is shown once. Store it in your secret manager or CI variables, never in source control.
Each key also has a public key (pk_live_…) that is safe in browsers, but it only works on the catalogue endpoints (plans, domain search and prices). See Authentication.

2. Make your first request

curl

curl https://api.newhost.co.za/v1/account \
  -H "Authorization: Bearer $NEWHOST_SECRET_KEY"

Node.js (18+)

const res = await fetch("https://api.newhost.co.za/v1/account", {
  headers: { Authorization: `Bearer ${process.env.NEWHOST_SECRET_KEY}` },
});
const { data } = await res.json();
console.log(data.email, data.walletBalance);

Every response is JSON with a data field. Lists also include has_more; see paging.

3. Deploy an application

List your apps to find the ID, then start a deployment. The key needs the deploy scope.

curl

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

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

The call returns 202 with a deployment in QUEUED status. Poll GET /v1/deployments/{id} for the status and build log, or subscribe to the deployment.succeeded and deployment.failed webhooks.

GitHub Actions: deploy after tests pass

- name: Deploy to NewHost
  run: |
    curl -fsS -X POST https://api.newhost.co.za/v1/apps/${{ vars.NEWHOST_APP_ID }}/deployments \
      -H "Authorization: Bearer ${{ secrets.NEWHOST_SECRET_KEY }}"

4. Get notified

Add an endpoint under Developers → Webhooks (or with POST /v1/webhooks) and NewHost will POST signed events to it. Verify the signature before trusting a payload.

Use the Postman collection

Prefer to try the API before writing code? Every endpoint is in a ready-made Postman collection.

Download Postman collection

  1. Download the collection with the button above. It has every endpoint in this reference, in one folder per section.
  2. In Postman, click Import and choose the downloaded file.
  3. Open the collection, go to its Variables tab and paste your secret key (sk_live_…) into the Current value of apiKey. Every request sends it as Authorization: Bearer, so you set it once.
  4. Open Account → Retrieve the account and click Send. A 200 response with your account details means you're ready to try the rest.

The Postman collection page lists the other variables, such as appId for the requests about one application.

Next steps