API Overview

Everything the dashboard does, you can do over HTTP. The Cloady REST API is the same surface the web UI talks to — workspaces, instances, deploys, domains, vars, members.

Base URL

https://cloady.com/api

All requests and responses are application/json. Send Content-Type: application/json on any request with a body.

Authentication

Authenticate with a personal API token. Pass it as a bearer token:

Authorization: Bearer cldy_...

Tokens are user-scoped: a request runs as you, with your workspace memberships. Every token starts with the cldy_ prefix; the rest is random and shown once at creation — Cloady stores only a sha-256 hash, so a lost token can’t be recovered, only revoked and replaced.

A token can carry an expiry (30d / 90d / 1y / never) and can be revoked at any time. Requests with a missing, malformed, expired, or revoked token get 401 unauthorized.

Create a token

From the dashboard: Account → API tokens (see the Dashboard Guide). Pick a name, a scope, and an expiry — the secret is displayed once, so copy it immediately.

Token scopes

Every token is minted with one scope that bounds what it can do:

• read — read-only. List and inspect workspaces, instances, deploys, logs. No mutations.
• deploy — everything read can do, plus deploy operations: install, redeploy, start, stop, restart.
• full — unrestricted. All deploy actions plus destructive and administrative ones: delete instances, manage domains and vars, manage members and billing.

Pick the narrowest scope that covers your use case — a CI deploy key wants deploy, not full.

Workspace roles

Scope bounds the token; your role in the workspace bounds the request. Workspace-scoped endpoints require a minimum role, ranked lowest to highest:

• viewer — read access to the workspace and its instances.
• developer — deploy and operate instances.
• admin — manage domains, vars, members, region activation.
• owner — full control, including billing and workspace deletion.

A request below the endpoint’s minimum role returns 403 forbidden. A workspace you aren’t a member of returns 404 not_found (membership is never disclosed).

Env + region query convention

Instances live at (workspace, region, env, svcId). Page routes carry region and env as path segments, but API requests carry them as query params:

?env=<prod|staging|dev>&region=<regionId>

• env defaults to prod when omitted.
• region is optional. When omitted and the svcId resolves to exactly one instance, that instance is used (back-compat). When the same svcId exists in multiple regions, the request is ambiguous and returns 400 with code region_required — retry with ?region=.

GET /api/workspaces/neptolab/apps/dailyfrog?env=prod&region=hil1

Error shape

Errors use a single canonical envelope:

{ "error": { "code": "not_found", "message": "App dailyfrog not found" } }

code is a stable machine-readable string; message is human-readable; an optional details field carries structured context. Branch on code, not on message or status alone.

Example

List your workspaces:

curl https://cloady.com/api/workspaces \
  -H "Authorization: Bearer cldy_..."

{
  "workspaces": [ /* ... */ ],
  "regions":    [ /* ... */ ],
  "tiers":      [ /* ... */ ]
}

For the full endpoint catalog — paths, methods, params, and bodies — see the Endpoint Reference.