Proposing changes

Propose or make many changes at once

Up to 25 edits in one request, each to a different entry: all proposals (mode: "propose", as POST /api/entity/{vhid}/proposals) or all live edits (mode: "live", as the editor’s Save makes them). Each edit is judged and made exactly as the single route makes it: whether this account may (entry by entry: a live edit needs edit_live, or edit_locked on an entry locked to admins), the conflict check against base_revision_id, one revision and one audit row per entry. A batch grants nothing a single call would refuse. One thing it refuses that a single call takes: naming a Wikipedia page for the credit (credit_in_batch), which the server reads from Wikipedia; send that one alone.

One at a time (the default): each edit in its own transaction, in order. One edit refused leaves the others made; the answer is 200 with each edit’s outcome, in request order, with the code and status the single route would have answered.

atomic: true: all or nothing. Every entry is locked first, in VHID order, and any refused edit undoes the whole batch: 422 batch_failed, naming every refused edit and why; the rest are not_applied, and nothing is written.

Replaying a batch whose answer was lost is safe: an edit already made answers conflict, with revisions_since_base: 1 and all_since_base_by_you: true; a proposal already filed answers its own submission_id. Every audit row of a batch carries its batch_id.

Rate limit. Every edit counts as one change against the IP address, account and key, so 25 edits cost what they would cost sent one by one; the request is refused (429) before any edit runs when they do not fit. Takes an optional Idempotency-Key, so a request whose answer was lost can be sent again safely: the retry gets the first answer back.

post/api/entity/batch

Request

  • Base URL: https://verifiedhandles.org
  • URL: https://verifiedhandles.org/api/entity/batch
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A key you choose for this one request (1–255 printable ASCII characters, e.g. a UUID). Send the same request with the same key again, within 24 hours, and the first answer comes back (Idempotency-Replayed: true) with nothing written again. The key is your account’s and this route’s alone. "The same request" is the same path and the same JSON (key order and spacing aside; base_revision_id aside, so a retry made after re-reading the entry still matches). Only a 2xx answer is kept: after any other, nothing was written and the key is free to retry.

Request body

mode'live' | 'propose' required

Live edits or proposals: one kind per batch.

atomicboolean

All or nothing. Default false: each edit on its own.

summarystring

Each live edit’s why, unless it gives its own. A proposal takes none.

Response

Each edit’s outcome, in request order (one at a time, or an atomic batch that was made whole).

batch_idstring required

This batch, as its audit rows name it (detail.batch).

mode'live' | 'propose' required
atomicboolean required
succeededinteger required

How many edits were made or filed.

failedinteger required

How many were refused.

Changes

No recorded changes to this operation across all 1 revision of this API.