API Reference

Publish from the command line.

A small REST API over the same engine. Creating and reading sites needs no auth; deletion requires the per-site manage token. All responses are JSON.

Base URL https://nebula.host

Conventions

A few rules that hold across every endpoint.

Rules

Errors	Shape `{ "error": "<message>" }` with an appropriate HTTP status.
Timestamps	ISO 8601 strings (UTC).
Slug	Matches `^[a-z0-9]{6,32}$`.

POST

/api/sites

Create (publish) a new site. multipart/form-data with one content source plus optional fields.

Form fields

Field	Type	Notes
file	file	A single `.html`/`.htm`, or a `.zip` of a static site.
html	string	Raw markup, used when no `file` is given.
filename	string	Optional name for pasted `html` (default `index.html`).
title	string	Optional, ≤120 chars. Falls back to `<title>` or filename.
listed	string	`"false"` hides it from the gallery; listed by default.
visibility	string	`public` · `unlisted` · `private`. Overrides `listed` when present. `private` requires a signed-in account.

Examplecurl

bash · paste HTML

curl -X POST https://nebula.host/api/sites \
  --form-string 'html=<!doctype html><h1>Hello</h1>'

Response201

application/json

{
  "site": {
    "slug": "wiyn4k6bkn",
    "title": "My Zip Site",
    "entry": "index.html",
    "totalBytes": 104,
    "listed": true
  },
  "url": "https://nebula.host/s/wiyn4k6bkn/",
  "manageToken": "nbla_uiNCuO0bpS9WFYjDkq1ZU…"
}

Errors

400	No content / unreadable ZIP / no HTML file present.
413	Upload too large or too many files.
415	Request was not `multipart/form-data`.

GET

/api/sites

List recently published, publicly-listed sites (newest first).

Query parameters

Param	Default	Notes
limit	30	Clamped to `1..100`.

GET

/api/sites/:slug

Fetch public metadata for a single site.

Response

Returns the public site projection (slug, title, entry, files, sizes, timestamps). Responds 404 if the slug is unknown or invalid.

PATCH

/api/sites/:slug

Change a site's visibility, or claim it to your account. Authorized by the manage token (Authorization: Bearer) and/or the signed-in owner.

Body

Field	Type	Notes
visibility	string	`public` · `unlisted` · `private`. `private` requires the site to have an owner.
claim	boolean	When `true` (signed in, with the manage token), links the site to your account.

Errors

401	No manage token and not signed in.
403	Token/owner does not match the site.
404	Site not found.

DELETE

/api/sites/:slug

Permanently delete a site and all of its files. Requires the manage token or ownership.

Authenticationheader or query

bash · curl

curl -X DELETE https://nebula.host/api/sites/wiyn4k6bkn \
  -H "Authorization: Bearer nbla_uiNCuO0bpS9WF…"

Errors

401	No token provided.
403	Token does not match the site.
404	Site not found.

GET

/s/:slug/*

Not JSON — this serves the hosted site itself, with static-host resolution rules.

Resolution rules

Request	Result
/s/<slug>	308 → `/s/<slug>/`
/s/<slug>/	entry document 200
/s/<slug>/dir/	`dir/index.html`
/s/<slug>/a/b.css	that file with its content-type
miss	404 (HTML)