---
title: "Generate a beautified rebuild of a single-file HTML page (preview only — nothing is written)."
method: POST
path: "/sites/{idOrSlug}/beautify"
tags: ["Sites"]
---

# Generate a beautified rebuild of a single-file HTML page (preview only — nothing is written).

`POST /sites/{idOrSlug}/beautify`

## Request

- Base URL: `https://api.stacktr.ee`
- URL: `https://api.stacktr.ee/sites/{idOrSlug}/beautify`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.stacktr.ee/oauth/authorize`, token URL `https://api.stacktr.ee/oauth/token`, scopes: `sites:write`)

Runs the design guide (GET /design-guide) server-side and returns either an honest abstention (the page already carries design judgement) or {direction, html} to review. Applying is a separate, explicit `PUT /sites/{idOrSlug}` with the returned HTML. Owner-authed; single-file, non-E2E HTML pages up to 100 KB; rate-limited per user per day. Generation can take minutes, so the 200 response streams NDJSON: `{"ping":true}` keepalive lines, then one terminal line — the result object, or `{error, message, status}` on failure. Guard errors (the non-200 codes below) are plain JSON. Agents with their own inference should prefer running the design guide themselves — same pipeline, no cap.

## Response `200`

A verdict: abstained with a reason, or a rebuilt document to review.

- object
  - `abstained` boolean, required
  - `reason` string: Present when abstained: why a rebuild would not improve the page.
  - `direction` string, nullable: One-sentence design direction, written for the page owner.
  - `html` string: The complete rebuilt document. Not yet applied.
  - `model` string
  - `version` string: Design-guide version used.

## Other responses

- `400`: Not eligible: multi-file site (a rebuild would lose the other files) or E2E-encrypted page.
- `401`: Missing or invalid credentials.
- `404`: Resource not found.
- `413`: Page over the 100 KB one-click ceiling.
- `429`: Daily beautify limit reached (rolling 24h).
- `502`: Generation failed; nothing was changed.
- `503`: Beautify not enabled on this deployment, or temporarily busy.

---

[API](https://skmtc.dev/stacktr/apis/stacktree-api.md) · [All operations](https://skmtc.dev/stacktr/apis/stacktree-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stacktr/apis/stacktree-api/revisions/5878cce46977?raw)