keelapps/Curator/Documentation

Documentation

Curator has one shape, repeated: choose pages, read what would happen to them, then let it happen — and take it back afterwards if it should not have. Everything below is a variation on those four steps.

Where Curator lives

Four surfaces, each scoped to what you can see from it:

• Space → Curator — the space console. Filter the space, choose an operation, read the preview, run it, and see this space's history.
• A page's action menu → Curate this page tree — the same operations over one page and its descendants, without leaving the page.
• Apps → Curator — the label catalogue: every shared label on the site with its usage count, readable by anyone.
• Settings → Curator — label administration. Renaming, merging and deleting labels site-wide, for site admins only.

Every read and every write runs as you, so Confluence's own permissions decide what a batch can touch. A page you cannot edit is a page Curator cannot change on your behalf — the preview says so before you commit rather than failing halfway through.

Selecting pages

A selection is a filter, not a list of ticked boxes, so it keeps working as the space grows. The available criteria:

• Scope — a whole space, or one page and its subtree.
• Title contains — a substring match.
• Last updated — before a date, after a date, or between two.
• Author — the person who last changed the page.
• Has all of these labels — every one must be present.
• Has none of these labels — the exclusion half.
• Include archived pages — off by default.

Curator counts the matches before you choose an operation, so the first number you see is “how big is this?” rather than “what did I just do?”.

The operations

Moving into another space is expressed as “move under this page”, because Confluence's move API takes a target page rather than a space. Curator resolves a space you pick to its home page for you.

The dry run

Nothing is written until you have read a preview. Every preview answers the same five questions:

• How many pages change, out of how many matched.
• The first fifty, individually, each with the exact edit it would receive — not “labels will be updated” but which labels, on which page.
• How many are skipped, and why. Every skip reason gets its own sentence: already has the label, no edit permission, archived and excluded, the move target is inside the selection, and so on. A page never disappears from a batch without an explanation.
• What it will cost, in Confluence API points.
• Whether it can be undone.

A preview describes the site as it was when the preview was built, so it stops being runnable after 24 hours. Build a fresh one rather than trusting a day-old description of a space other people have been editing.

Undo

Every run records a per-page inverse as it goes: the labels to put back, or the parent page and space to move the page back to. Undo replays that journal.

Each page is guarded. Before Curator reverses a page it checks the values it recorded at the time — the parent and the space the page was left in. If they no longer match, somebody else has moved or changed that page since, and Curator leaves it alone and reports it rather than overwriting their work. A partially applied undo is an honest outcome; a silently clobbered edit is not.

The undo is itself an operation in the history, with its own counts and its own record of who ran it.

The label catalogue

Apps → Curator lists every shared label on the site with its name, its prefix and a usage count.

Those counts are derived. Confluence's label endpoint returns names and ids and nothing else — there is no count in the payload — so Curator walks each label's pages in the background and counts them itself. Every row therefore carries the time its count was taken, and counts past two thousand are shown as 2,000+ rather than pretending to a precision the walk did not buy.

Personal favourites — the labels Confluence stores with a my prefix — are never listed and never touched.

Renaming, merging and deleting labels

Settings → Curator, site admins only. Three operations, all site-wide, all previewed and all undoable:

• Rename — every page carrying the old label ends up carrying the new one.
• Merge — two or more labels collapse into one.
• Delete — the label is detached from every page that has it.

Confluence has no rename or merge endpoint, and Curator does not pretend otherwise. A label is a string on a page, not an entity, so a rename is a bulk edit: remove the old label and add the new one on every page carrying it. That is not an atomic operation — it is hundreds or thousands of individual page edits, and it can be interrupted. Which is why this is exactly where the dry run, the resumable checkpoint and the whole-batch undo earn their keep. A run that stops halfway resumes from its checkpoint; a run that finished wrong can be reversed.

History and CSV export

Every run and every undo becomes one history record: the operation and a description of it, the selection it ran over, the space, the acting person's name, start and finish times, how many pages succeeded, were skipped or failed, whether it can still be undone, any note you typed, and up to a hundred per-page failures with their reasons.

History is capped at 2,000 entries per site; beyond that the oldest are dropped. Export it as CSV whenever somebody needs the trail outside Confluence.

API points and pacing

Confluence Cloud charges apps for API calls in points, and the hourly allowance belongs to the app — shared across every customer running it, not per-site. Exhausting it would block every other site until the next hour. Curator therefore meters itself in three places:

• The dry run prices the batch before you commit to it.
• An operation too large to be neighbourly is refused, with a reason — not queued to run overnight at everyone else's expense.
• Anything below that ceiling is paced: when this site has used its share, the batch pauses and resumes in the next hourly window from its checkpoint.

A long batch that says “paused until the next window” is working as designed. It will finish.

What cannot be undone

Archiving. Confluence Cloud has no restore API — there is no unarchive route in either the v1 or the v2 specification, and CONFCLOUD-75065, the request for one, is still Gathering Interest.

Curator does not hide this behind a support article. Archive is marked non-reversible in the preview, on the confirmation button and in the history entry it leaves behind. Every other operation is reversible.

Archiving also depends on your Confluence plan: the archive API accepts a limited number of page ids per call, permits only one archive task per site at a time, and is unavailable on Free. Below Premium it accepts a single page id per call, which makes a large archive slow. Curator detects what your site allows and says so rather than letting you find out from a progress bar that will not move.

Permissions the app requests

There is no permissions.external block: the app cannot make an outbound call even if it tried to, which Atlassian enforces at the platform level.

Not in this release

• Attachments — deliberately out of scope. See Satchel for Confluence.
• Deleting pages. Curator archives; it never deletes.
• Editing page content or page titles.
• Changing page or space permissions and restrictions.
• Scheduled or recurring batches.
• Cross-site operations.

Support

Questions, bug reports and feature requests: raise a support request. Security issues: report privately.