Using the REST API
Interact programmatically with your shadw cloud using direct HTTP requests. You can create deployments, manage custom domains and DNS, configure projects, and wire up webhooks, all over HTTPS.
The API supports any programming language or framework that can send HTTP requests.
API basics
The API is exposed as an HTTP/1 and HTTP/2 service over SSL. All endpoints live under the URL https://api.shadw.cloud and follow the REST architecture.
Authentication
Authenticate with a platform API key — a long-lived, team-bound token prefixed hive_. Create one under Settings → API Keys (or with POST /v1/apikeys). The full token is shown exactly once at creation; only its SHA-256 hash is stored. Include it in the Authorization header:
Authorization: Bearer hive_…Alternatively, present a short-lived JWT (1 hour at most) in the same header. POST /v1/token mints one; it requires HIVE_JWT_SECRET to be configured on the node, and once that is set it is server-only (the request must carry the x-hive-internal header). When HIVE_JWT_SECRET is set, mutating requests (POST/PUT/PATCH/DELETE) must present a JWT or an API key.
Accessing team resources
Every request resolves to a team (tenant), in this priority order: a JWT's tenant claim wins; otherwise an API key scopes the request to the team it was created under — no extra header needed; otherwise, on nodes without JWT enforcement (no HIVE_JWT_SECRET, e.g. local dev), the x-hive-team header is honored. With none of these, requests fall back to the personal team.
# An API key is already bound to its team — no team header needed.
curl https://api.shadw.cloud/v1/overview \
-H 'Authorization: Bearer hive_…'Rate limits
API requests are limited per client IP address to 600 requests per minute (a sliding window). When you exceed the limit the API responds with 429 Too Many Requests; back off and retry, since each request stops counting after one minute.
Errors
Standard HTTP status codes are used throughout.
| 200 | Success. |
| 400 | Bad request — malformed JSON or missing required fields. |
| 401 | Unauthorized — missing/invalid token, or a protected preview. |
| 404 | Not found — unknown project, deployment or domain. |
| 409 | Conflict — e.g. a name already in use. |
| 429 | Too many requests — rate limited. |
| 500 | Internal error — check the node logs. |
Endpoints
Browse the 34 documented REST API endpoints grouped by category.