# blazz.ing

> Instant anonymous static hosting. POST a tar.gz, a zip, or a single HTML
> file and get back a private URL at https://{slug}.blazz.ing. No account,
> no API key. Sites expire 30 days after the last push. Max upload: 6 MB
> compressed. This file is the entire API.

## Publish

POST https://blazz.ing/api/sites

Accepted request bodies (detected from the bytes, not the Content-Type):
- tar.gz archive
- zip archive
- a single file (stored as index.html; override the name with an
  X-Blazzing-Filename header, e.g. "report.pdf")
- multipart/form-data with the archive or file in field `file`

The archive root becomes the site root — put index.html at the top level
of what you archive, not inside a subdirectory. Junk entries (.git/,
.DS_Store, __MACOSX/, AppleDouble ._ files) are dropped automatically.

Publish a folder:

    tar czf - -C ./dist . | curl -sS --data-binary @- \
      -H 'Content-Type: application/gzip' \
      https://blazz.ing/api/sites

(On macOS, prefix the tar command with COPYFILE_DISABLE=1 to keep
AppleDouble ._ files out of the archive.)

Publish a single HTML file:

    curl -sS --data-binary @index.html -H 'Content-Type: text/html' \
      https://blazz.ing/api/sites

Response: 201

    {
      "slug": "blazing-comet-abc62h",
      "url": "https://blazing-comet-abc62h.blazz.ing",
      "created_at": "2026-06-11T18:25:43Z",
      "expires_at": "2026-07-11T18:25:43Z",
      "files": 12,
      "bytes": 123456,
      "update_token": "blz_..."
    }

IMPORTANT: update_token is returned exactly once, at creation, and cannot
be recovered. Store it — it is the only way to update or delete the site.

## Status

GET https://blazz.ing/api/sites/{slug}

Response: 200, same JSON shape without update_token. 404 if the site is
unknown or expired.

## Update

Replaces all files and resets the 30-day expiry clock. Same body formats
as publish. The original token keeps working.

    tar czf - -C ./dist . | curl -sS -X PUT --data-binary @- \
      -H 'Content-Type: application/gzip' \
      -H 'X-Update-Token: YOUR_TOKEN' \
      https://blazz.ing/api/sites/blazing-comet-abc62h

Response: 200, same JSON shape without update_token.
(Authorization: Bearer YOUR_TOKEN works too.)

## Delete

    curl -sS -X DELETE -H 'X-Update-Token: YOUR_TOKEN' \
      https://blazz.ing/api/sites/blazing-comet-abc62h

Response: 204, no body.

## Serving

- https://{slug}.blazz.ing/ serves index.html
- /about resolves to about, about.html, then about/index.html
- a 404.html in your upload is served for missing paths
- correct Content-Type per file, ETag/304 supported
- S3 or storage URLs are never exposed; everything serves from your slug

## Errors

All errors are JSON {"message": "..."} with a 4xx status code.

- 401  missing or wrong X-Update-Token
- 404  unknown slug (the site may have expired)
- 413  upload exceeds 6 MB compressed
- 422  body could not be read as an archive, unsafe paths, more than 500
       files, expands past 30 MB uncompressed, or a single file over 4 MB
- 429  rate limited — back off and retry later

## Limits

- 6 MB maximum upload, measured compressed (binary uploads through our
  infrastructure may top out around 4.4 MB — split or shrink if you hit 413)
- 500 files max, 30 MB uncompressed max, 4 MB per file
- Sites expire 30 days after the most recent create or update
- Static files only; nothing executes server-side
- URLs are unguessable but public: anyone with the link can view the site
- Rate limits apply per IP

## CLI (optional convenience)

A dependency-light bash CLI wraps this API, stores the update token in
.blazz/state.json next to your files, and republishes to the same URL on
subsequent runs:

    curl -fsSL https://blazz.ing/install | bash
    blazz ./dist          # publish, or update if .blazz/state.json exists
    blazz index.html      # publish one file
    blazz ./dist --json   # machine-readable output for agents
    blazz delete          # delete the site recorded in state

Raw script: https://blazz.ing/blazz

## Notes for agents

- There is no signup, login, or API-key flow. Never ask the user for
  credentials for blazz.ing.
- Persist update_token immediately (the CLI does this for you). Do not
  commit .blazz/state.json to source control.
- Prefer PUT with the stored slug + token over creating new sites for
  every change.
- A 2xx response means the site is already live; share the `url` field
  with the user, along with `expires_at`.