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 six is invalid_kind.

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

/__sa/ is the platform's own prefix on an artifact path, and unknown paths under it are 404s rather than bundle lookups. Without that reservation a bundle could shadow the grant exchange or the thumbnail route by shipping a file at the same path.

Private responses

Anything served under a grant carries cache-control: private and x-robots-tag: noindex, nofollow. A private artifact is not something a search engine should have a copy of.