---
title: "See a description as it would be stored"
method: POST
path: "/api/entity/description-preview"
tags: ["Proposing changes"]
---

# See a description as it would be stored

`POST /api/entity/description-preview`

## Request

- Base URL: `https://verifiedhandles.org`
- URL: `https://verifiedhandles.org/api/entity/description-preview`
- Auth: HTTP bearer

The HTML a save would store for this description, and nothing written: the same steps a live edit or an approved proposal runs (`[[VHID]]` and `[[short]]` links made into links to the entry, `[url label]` into a link, then the site’s HTML allowlist, which drops a script, an event handler and any tag or attribute it does not keep). Console → Batch edit shows a new description with it before anything is sent. `html` is null when nothing would be left, which a save stores as no description. Counts as one change against the rate limit, as the writes it previews.

## Request body

- object
  - `description` string, required: Up to 64 KiB in UTF-8, as a saved description.

## Response `200`

The description as it would be stored.

- object
  - `html` string, nullable, required: The stored HTML; null when nothing would be left.

## Other responses

- `400`: The body is not JSON (`bad_json`), `description` is not a string (`bad_payload`), or it is over 64 KiB (`description_too_long`). Or the request sent a key and a session cookie together (`bearer_with_cookie`): send one.
- `401`: No key was sent (`auth_required`), or the key was refused: unknown, revoked or expired, its holder may no longer use keys, or this instance takes none. Carries `WWW-Authenticate: Bearer`. After 60 refused keys from one IP address in a minute, every key from there is answered `429` (text, with `Retry-After`) until the minute is up.
- `403`: A read-only key tried to change something (`read_only_key`), or the account is blocked (`forbidden`).
- `413`: The body is over 512 KiB.
- `429`: Too many changes in the last minute: counted per IP address, per account and per key (an admin key’s per key alone, at the limit set on Console → Rate limits). Wait the number of seconds `Retry-After` gives.
- `503`: The site is down for maintenance. The body is the maintenance page, as HTML. Try again later: `Retry-After` gives the seconds.

---

[API](https://skmtc.dev/verifiedhandles/apis/verified-handles-api.md) · [All operations](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/llms.txt) · [OpenAPI document](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/revisions/40720de2e0ec?raw)