API Reference

Authentication

All API requests require authentication via a Bearer token in the header:

Authorization: Bearer YOUR_API_KEY

Generating API Keys

1. Go to Dashboard → Settings → API Keys
2. Click Create New Key
3. Give it a descriptive name
4. Copy the key immediately (it won't be shown again)

Important: API keys have the same permissions as your account. Keep them secret and rotate regularly.

Base URL

https://hostwares.com/api

All endpoints are relative to this base URL. Responses are JSON.

Sites API

Create a site

POST /api/sites
{
  "name": "my-nextjs-app",
  "type": "github",
  "repository": "github.com/user/my-app",
  "branch": "main",
  "port": 3000,
  "buildCommand": "npm run build",
  "startCommand": "npm start"
}

Response

{
  "id": "cm1234abcd",
  "name": "my-nextjs-app",
  "status": "DEPLOYING",
  "domain": null,
  "createdAt": "2026-05-20T10:30:00Z",
  "url": "https://hostwares.com/api/sites/cm1234abcd"
}

Databases API

Create a database

POST /api/databases
{
  "name": "production-db",
  "type": "postgresql"
}

Credits API

Check balance

GET /api/credits

Response:
{
  "balance": 450,
  "lastPurchase": "2026-05-15T08:00:00Z"
}

Site Actions

Use PATCH with an action field to control site state:

PATCH /api/sites/:id
{ "action": "restart" }

Available actions

Error Handling

All errors return consistent JSON with an error code and message:

{
  "error": "NOT_FOUND",
  "message": "Site not found or you don't have access",
  "statusCode": 404
}

Common error codes

Rate Limits

• 60 requests per minute per API key
• Rate limit headers included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1716210000

When rate limited, wait until the reset timestamp before retrying.

Code Examples

Node.js (fetch)

const response = await fetch('https://hostwares.com/api/sites', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const sites = await response.json();

Python (requests)

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get("https://hostwares.com/api/sites", headers=headers)
sites = response.json()

cURL

curl -X GET https://hostwares.com/api/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Deploy a site via API

curl -X POST https://hostwares.com/api/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "type": "github",
    "repository": "github.com/user/my-app",
    "branch": "main"
  }'