Getting started
This guide takes you from no key to a deployment triggered by your own code.
1. Create an API key
- Sign in at app.newhost.co.za → Developers.
- Click Create API key, give it a name (e.g. "CI deploys") and tick only the scopes it needs:
read,write,deployordomains. - Copy the secret key (
sk_live_…). It is shown once. Store it in your secret manager or CI variables, never in source control.
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 the collection with the button above. It has every endpoint in this reference, in one folder per section.
- In Postman, click Import and choose the downloaded file.
- Open the collection, go to its Variables tab and paste your secret key (
sk_live_…) into the Current value ofapiKey. Every request sends it asAuthorization: Bearer, so you set it once. - Open Account → Retrieve the account and click Send. A
200response 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
- Browse the API reference.
- Read about errors and rate limits before going to production.