statichost.dev API

Authentication

Every call needs an API key, sent as a Bearer token:

Authorization: Bearer sk_...

The human creates the key at https://lno1g9bz.vibecode.cloud/account → API keys (they must be signed in) and gives it to you. Treat it like a password. Keys act as their owner: everything the owner can do in the dashboard, the key can do.

Plans & limits

Going over a limit returns 403 site_limit or 413 site_too_large. Plans are changed by the human in the dashboard — the API cannot buy anything.

Publishing a site

1. POST /api/v1/projects with {"name": "My site"} → note the returned id and url. (To update an existing site instead, find it with GET /api/v1/projects.)
2. For every file, PUT /api/v1/projects/{id}/files/{path} with the raw file bytes as the body. {path} is the file's path relative to the site root, e.g. index.html, css/site.css, img/logo.png (URL-encode each segment). Uploading the same path again replaces the file.
3. Optional, when re-deploying: POST /api/v1/projects/{id}/prune with {"keep": [every path you just uploaded]} to delete files that no longer exist locally.
4. The site is live at url. index.html (or home.html) in the root becomes the home page automatically; otherwise set homeFile with PATCH /api/v1/projects/{id}.

Shortcut: PUT /api/v1/projects/{id}/archive?replace=1 with a .zip as the body uploads the whole folder in one request (and, with replace=1, removes files not in the zip).

BASE=https://lno1g9bz.vibecode.cloud; KEY=sk_...
ID=$(curl -s -X POST $BASE/api/v1/projects -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' -d '{"name":"My site"}' | jq -r .id)
cd site && find . -type f | sed 's|^\./||' | while read -r f; do
  curl -s -X PUT --data-binary @"$f" -H "Authorization: Bearer $KEY" \
    "$BASE/api/v1/projects/$ID/files/$(jq -rn --arg p "$f" '$p|@uri|gsub("%2F";"/")')"
done

How sites are served

• / serves the home file. /about tries about, then about.html, then about/index.html. A 404.html in the root is used for missing pages.
• Root-absolute links (/css/site.css) work — each site owns its whole subdomain.
• Content types come from the file extension.
• Public files are cached at the CDN edge and purged automatically when anything about the site changes; browsers revalidate HTML on every visit. Password-protected sites, pages behind visitor login and pages with {{{workflow}}} tags are never cached.
• Password protection (PATCH with {"password": "..."}) puts a statichost sign-in page in front of the whole site. {"password": null} removes it.
• Custom domains (Pro): add the domain with POST /api/v1/projects/{id}/domains, then create CNAME <domain> → <id>.statichost.dev (or, for an apex domain, TXT _statichost.<domain> = <id>). Free sites refuse to be served on a custom domain.

Dynamic pages (workflows)

Any HTML page can contain tags that are replaced, every time the page is served, by the result of a GluedEasy workflow:

<p>{{{wf_abc123 name="Ada"}}}</p>
<ul>{{{latest-posts @as=html @cache=300}}}</ul>
<p>Weather in your city: {{{weather/lookup city=$query.city @fallback="unavailable"}}}</p>

1. The site owner connects GluedEasy once — dashboard Account → Workflows (*Connect with AuthLock*: sign in and approve, no key to copy — or paste a key), or PUT /api/v1/integrations/gluedeasy with a key. Workflows run with that key: only workflows the owner can run, billed to the owner's GluedEasy credits. The key is stored encrypted and never reaches visitors.
2. Upload pages with tags as usual. HTML files are scanned during upload; pages without tags are served exactly as before (streamed, cacheable).

Tag syntax: {{{<workflow>[/<step>] [name=value …] [@option=value …]}}}

• <workflow> — a workflow id (wf_…) or its slug. /<step> picks the step to start at; without it the workflow's REST entry step is used. The run waits for the whole workflow and uses its final output.
• name=value pairs become the workflow's JSON input. "quoted" values are strings; bare values are parsed as JSON when they can be (count=3 → number, on=true), else strings; a bare name alone is true.
• Visitor values (always strings): $query.<param> (from the page URL), $path, $host, $url, $lang (first Accept-Language). Different values are cached separately.
• Options: @cache=<seconds> (default 60, 0 = run on every view, max 86400) · @timeout=<seconds> (default 10, max 30) · @as=text|html · @field=<a.b.c> (use one field of the output) · @fallback="<text>" (shown when the workflow can't run).

What is inserted: a string output as-is; an object's text field (or html with @as=html); anything else as JSON. With the default @as=text it is HTML-escaped — workflow output can never inject markup. @as=html allows formatting through an allowlist sanitizer (no scripts, styles, iframes, event handlers or javascript: URLs).

When it can't run (not connected, timeout, error, rate limit) the page is still served: the last good result (up to 1 h old) if there is one, else the @fallback, else nothing — plus an HTML comment such as <!-- statichost: my-flow not rendered (timeout) -->.

Limits: 20 tags per page, pages up to 10 MB, a site starts at most 120 workflow runs per minute (cache hits are free). Pages with tags are sent with Cache-Control: private, no-store. Tags work in .html files only, and results are never re-scanned for tags.

Visitor login

When the server has AuthLock configured, a site can get visitor login: turn it on with POST /api/v1/projects/{id}/access and statichost creates an AuthLock project for the site (the owner is invited to it as admin). Visitors sign in with an emailed code or a social account (Google, …) — no passwords — and may add an authenticator app (optional 2FA).

Access is set on the page tree: every directory ("" = the root, "docs/") and every .htm/.html file. A rule is one of

• {"mode":"anonymous"} — open to everyone (the site password, if set, still applies)
• {"mode":"signed_in"} — any visitor who signed in
• {"mode":"roles","roles":["members","staff"]} — visitors with any of these roles
• null — inherit

A page without its own rule uses its directory's, up to the root (default: anonymous). Every other file (CSS, images, …) follows its directory. Roles live in the site's AuthLock project; a rule that names a new role creates it. Assign roles to visitors with PUT /api/v1/projects/{id}/access/users/{userId}/roles (or in AuthLock).

On the site: a protected page shows a sign-in page (401) or "no access" (403); protected responses are never cached. Pages can link to /__statichost/auth/login?next=/path and /__statichost/auth/logout, and read the visitor with fetch('/__statichost/auth/me') → { signedIn, email, roles }. Workflow tags can use $user.email, $user.id and $user.roles.

Errors

Errors are JSON: { "error": "<code>", "message": "<human text>" } with a matching HTTP status (400 invalid input, 401 missing/bad key, 403 not allowed by plan, 404 not found, 413 too large, 429 slow down, 5xx our problem — retry later).

502 storage_unavailable (with "retryable": true and a Retry-After header) means the file store had a transient hiccup and nothing was stored — wait a moment and repeat the exact same request. When uploading many files, retry each failed file (3–4 attempts with backoff) instead of giving up on the whole upload.