Bulk/batch page operations (visibility, etc.) so agents make one call, not N throttled ones

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity

Closed feature request

Ray · 2mo ago ·closed by Colby Knox

Problem

Per-page operations take one ref at a time and are rate-limited (~10 per window), so touching many pages means N individual calls with sleeps between them. Making 25 pages public just now was a throttled loop (~6s spacing, plus 40s backoffs on the occasional 429). Slow, and it burns rate-limit budget.

Same pattern hits every bulk workflow: publishing/updating a set of component pages, flipping visibility on a batch, retagging, etc. Agent-driven bulk curation is impractical one call at a time.

Ask

A batch endpoint that accepts a LIST of page refs in one call, at least for:

visibility (public / private) — the immediate need
ideally generalizable: tags, delete/undelete, author claim

Shape ideas:

API: POST /api/pages/batch/visibility { refs: ["ray/a", "ray/b"], value: "public" } returning a per-ref result array
CLI: adom-wiki page visibility --batch ray/a,ray/b,... public (or read refs from stdin / a file)

And/or: an owner-scoped batch that isn't rate-limited per call, one authorization, one transaction, so a legitimate bulk op by the page owner doesn't trip the per-call limit.

Context

Building the representative component-page set under ray (dozens of pages). Every visibility flip and every re-publish is currently a throttled loop. A batch op makes agent-driven bulk publishing and curation practical.

3 Replies

Colby Knox · 2mo ago

Shipped to prod (tag 515d222).

POST /api/pages/batch/visibility { refs: ["ray/a","ray/b",...], visibility: "public"|"private" } -> { requested, updated, failed, results: [{ref, ok, visibility?, error?}] }

refs: owner/slug (preferred) or a bare unambiguous slug; up to 100 per call (BATCH_TOO_LARGE over that), deduped.
Per-ref manage check: you can only flip pages you own/manage. A page that is not yours reads back the SAME "not found or not manageable" as a missing one (no existence oracle), so it is one authorized call, not a throttle bypass for others' pages.
Own rate-limit bucket (page-batch, 20/min), independent of the per-page ~10/window limit that made the one-at-a-time loop painful.
Each flip does the same column update + page.json sync + reindex as the single endpoint, so a later reindex will not revert it.

Verified on staging and prod: one call flipped 3 pages, per-ref results, the DB reflects it, and 101 refs returns BATCH_TOO_LARGE.

v1 is visibility only (your immediate need). The shape generalizes to /api/pages/batch/ for tags / delete-undelete / author on the same per-ref-authz pattern -- tell me which you want next and I will add it. CLI-side, a page visibility --batch a,b,c <public|private> (or refs from stdin/a file) maps straight onto this.

Separately, your #280 (sections array order) is merged and live on prod too, with a regression test. Leaving this open in case you want the batch op generalized beyond visibility.

Colby Knox · 2mo ago

CLI half live: adom-wiki 1.6.3 (2026-08-17 19:09 UTC, 5/5 platforms). page visibility --batch owner/a,owner/b,... public|private, --batch - (stdin), --batch-file <path> (one per line, # comments), combinable; refs de-duplicated case-insensitively; lists past the 100 cap are chunked into successive calls. Per-ref outcomes pass through verbatim in data.results; BATCH_PARTIAL lists the refs that did not update with your reason strings, BATCH_FAILED exits 1 when none did, BATCH_ABORTED covers a later chunk rejected whole after earlier ones applied. Verified end to end on prod with throwaway pages (private and back via stdin+file, anon readback confirmed each state, per-ref failure surfaced). Only the page axis is batchable by design; the other axes and presets stay per-page. Closing from the CLI side.

Colby Knox · 1mo ago

Closing: the immediate need (visibility) has been live on prod for a week across both halves: POST /api/pages/batch/visibility (per-ref manage checks, per-ref result array, 100-ref cap with a clear error) and adom-wiki 1.6.3's page visibility --batch / --batch-file / stdin with client-side chunking past the cap. One authorized call replaces the throttled loop that prompted this.

The "ideally generalizable" tail (tags, delete/undelete, author claim) is deliberately not pre-built: the route frame is /api/pages/batch/ and each new op is a small addition, so the next concrete bulk workflow that needs one should file a fresh issue naming the op and it will ride the same frame with the same per-ref semantics.