Deploy contract

This is the interface between an agent and the serving plane. It is a contract rather than a description: changing it means changing both sides.

Hosts

| Host | Serves | | --- | --- | | superart.page/{id}/… | The artifact, from storage behind the edge worker. | | api.superart.page | The deploy and management API. | | superartifacts.app | The dashboard. It holds none of the artifact bytes. |

Staging is the same set with stg. and api-stg. prefixes. Which plane a document came from is stated in the document, because the failure it guards against is an agent operating on the wrong plane while every URL in front of it looks plausible.

POST /deploy

Content-Type: application/json, Authorization: Bearer a creator key. The body is described in full on the deploy page. The server assigns the id on first deploy, assigns the version number always, and publishes what it just wrote.

Failures answer with { "error": { "code", "message" } } and an accurate status. code is a stable machine-readable string; message is for a human. A hash that does not match the bytes is hash_mismatch; a kind outside the closed seven is invalid_kind.

A bundle must contain index.html at its root. It is capped at 10 MiB in total, 5 MiB per file, 200 files and 255 characters per path.

Reading and publishing

curl -sS https://api.superart.page/artifacts \
  -H "Authorization: Bearer $SUPER_ARTIFACTS_KEY"

curl -sS -X POST https://api.superart.page/artifacts/{id}/publish \
  -H "Authorization: Bearer $SUPER_ARTIFACTS_KEY" \
  -d '{"version": 3}'

Reserved paths

A bundle path whose first segment starts with _ is refused at deploy (invalid_path): that prefix is the platform's. /__sa/ is its own prefix on a served path, and unknown paths under it are 404s rather than bundle lookups.

Response headers

Every artifact response carries x-robots-tag: noindex, nofollow, noarchive, nosnippet, noimageindex. Anything but a public artifact's published version carries cache-control: private, no-store.