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.

Next steps