---
title: "Keep a draft of an entry"
method: PUT
path: "/api/entity/{vhid}/draft"
tags: ["Drafts"]
---

# Keep a draft of an entry

`PUT /api/entity/{vhid}/draft`

## Request

- Base URL: `https://verifiedhandles.org`
- URL: `https://verifiedhandles.org/api/entity/{vhid}/draft`
- Auth: HTTP bearer

Keeps your unsaved edit to the entry, replacing any draft of it you had, and moves its expiry to 30 days from now. The description is cleaned with the same allowlist as a saved one. The body may be at most 256 KiB, and you may keep up to 100 drafts at once. A deleted entry takes no draft. Drafts are not in the audit log.

## Path parameters

- `vhid` string, required

## Request body

- object
  - `draft` EntryDraft, required: An unsaved edit to an entry, in the editor’s own shape.
    - `vhid` string: The entry’s VHID. Optional when sending; it must be this entry’s.
    - `savedAt` number: When the draft was last changed, in milliseconds since 1970. Ignored when sending: the server keeps its own time.
    - `fields` object, required: The entry’s fields as edited. The description is HTML, kept through the same allowlist as a saved description.
      - `title` string
      - `subtitle` string
      - `description` string
      - `short` string
    - `handles` object[]
      - `platform_id` string, required
      - `value` string, required
      - `display` string, nullable
      - `kept` true: A masked email kept as stored.
      - `ref` string: Which stored email a kept one is.
    - `customOrder` boolean: The handles are in the entry’s own order.
    - `linkNames` object: VHID → name, for the entries the description links to.
    - `image` object, nullable: The lead image as picked: null when removed, absent when untouched.
      - `id` string, required: The image’s id.
      - `kind` 'commons' | 'local', required
      - `commons_filename` string, nullable, required
    - `gallery` object[]: The images after the lead, when changed.
      - `id` string, required: The image’s id.
      - `kind` 'commons' | 'local', required
      - `commons_filename` string, nullable, required
    - `imageLinks` object: Image id → link as typed, when changed.
    - `relinquish` string[]: Fields to hand to Wikidata on save.
    - `takeover` string[]: Fields to take back from Wikidata on save.
    - `dropCredit` true: Remove the Wikipedia credit on save.
    - `creditPage` string: A Wikipedia page named for the credit, as typed.
    - `creditManage` false: With `creditPage`: the description is not to go to the sync.
    - `handleTakeover` string[]
    - `handleRelinquish` string[]
    - `handleRelease` string[]
  - `base_revision_id` string, nullable: The revision the edit started from (the editor’s base revision), or null.

## Response `200`

Kept.

- object
  - `ok` true, required
  - `vhid` string, required
  - `base_revision_id` string, nullable, required: The revision the draft was edited against, or null.
  - `saved_at` string, date-time, required: Its last change.
  - `expires_at` string, date-time, required: When it is deleted unless changed again: 30 days after `saved_at`.

## Other responses

- `400`: `bad_json`: the body is not JSON. `bad_payload`: the body or the draft is not the editor’s shape; `field` names the part. `bad_base_revision`: `base_revision_id` is not one of this entry’s revisions. 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`).
- `404`: No entry has that VHID (`not_found`), or it is deleted.
- `409`: You already keep 100 drafts: save or discard one first.
- `413`: The body is over 256 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)