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 the mesh.

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, mint a short-lived (8 hour) JWT with POST /v1/token and present it in the same header. Minting requires HIVE_JWT_SECRET to be configured on the node; when JWT auth is enforced, mutating requests (POST/PUT/DELETE) must present a JWT.

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 rate-limited per team. When you exceed the limit the API responds with 429 Too Many Requests; back off and retry after the window resets. Burst limits are higher on Pro and Enterprise plans.

Errors

Standard HTTP status codes are used throughout.

Endpoints

Browse all 34 available REST API endpoints grouped by category.