GameHostCloud API Overview
Updated 2026-09-09
GameHostCloud REST API
Overview
The GameHostCloud API lets you list your servers, read your account and balance, and start, stop, restart or force-stop a server from your own scripts.
Base URL
All endpoints live under a single gateway:
https://<your-project>.supabase.co/functions/v1/api-gatewayThe exact base URL for your account is shown in Dashboard → Settings → API keys → Documentation.
Authentication
Every request needs your API key in the x-api-key header:
curl -H "x-api-key: ghc_your_key_here" \
"https://<your-project>.supabase.co/functions/v1/api-gateway/servers"Creating API keys
- Dashboard → Settings → API keys
- Click Generate new key
- Choose the permissions and an optional expiry date
- Copy the key — it is shown only once
Permissions
| Permission | Description |
|---|---|
servers:read | List and view servers |
servers:control | Start, stop, restart and force-stop servers |
billing:read | View your balance |
account:read | View your account details |
Endpoints
| Method | Endpoint | Permission |
|---|---|---|
| GET | /servers?limit=50&offset=0 | servers:read |
| GET | /servers/{id} | servers:read |
| POST | /servers/{id}/start | servers:control |
| POST | /servers/{id}/stop | servers:control |
| POST | /servers/{id}/restart | servers:control |
| POST | /servers/{id}/kill | servers:control |
| GET | /account | account:read |
| GET | /balance | billing:read |
Listings return at most 100 rows per page; use limit and offset to page through them.
Rate limits and abuse protection
The API is protected in several layers so that a flood of requests cannot slow the service down for anyone else.
| Limit | Value |
|---|---|
| Requests per API key | 120 / minute, 40 / 10 seconds, 3 000 / hour |
| Control actions (start, stop, restart, kill) | 20 / minute, 5 / 10 seconds |
| Simultaneous requests per API key | 8 |
| Requests before authentication (per IP address) | 120 / minute, 30 / 10 seconds |
| Failed or missing API keys (per IP address) | 20 / 5 minutes |
| Request body size | 64 kB |
Successful responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When a limit is exceeded you get HTTP 429 with a Retry-After header — wait for that many seconds before retrying, and back off instead of retrying in a tight loop.
Only GET, POST and OPTIONS are accepted; any other method returns 405.
Error codes
| Code | Meaning |
|---|---|
| 400 | Unknown endpoint for this resource |
| 401 | Invalid or missing API key |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 405 | Method not allowed |
| 413 | Request body larger than 64 kB |
| 429 | Rate limit exceeded — see Retry-After |
| 500 | Server error |