How to Audit a Confluence Page Inventory Before an AI Migration

A safe Confluence migration starts with a permission-scoped, paginated inventory, not a keyword search. Enumerate every visible space, list every page in each space until the cursor ends, record stable space and page IDs, and then compare the count and hierarchy with a space-admin inventory. Only after those checks agree should an AI agent fetch page bodies or prepare destination writes.

This guide is for workspace owners and migration leads moving Confluence knowledge into another system. Success means you can explain which spaces and pages were checked, which identity could see them, where pagination ended, and which restricted or orphaned pages require a human decision.

Why a Confluence search is not an inventory

Search answers "which visible titles match this phrase?" An inventory answers "which pages should this migration account for?"

Those jobs have different failure modes. The current Aident Confluence Search Content Action searches page titles, fetches at most 300 pages before local filtering, cannot filter by author, date, or labels, and warns that a supplied space key is not a strict scope. Its result is useful for discovery, but it cannot prove completeness.

The Confluence Cloud REST API v2 also returns only content visible to the authenticated user. Atlassian documents cursor pagination for endpoints that return multiple objects. A first page with 100 results therefore means "100 visible results returned," not "this space contains 100 pages."

Prerequisites and safety boundary

Before the audit, name:

• the Confluence site and authenticated identity;

• the spaces in scope;

• accepted page states, such as current only;

• whether restricted, archived, personal, and draft content belongs in the migration;

• a destination owner who will review the inventory before any write.

Keep the audit read-only. Do not create, update, archive, delete, or change restrictions while collecting the inventory. An empty result can mean either no matching content or insufficient access, so never treat it as deletion authority.

If Aident Loadout is not installed, tell your agent:

Follow https://aident.ai/SETUP.md

Then verify the account and Vault connection:

aident account auth status
aident vault vault --action status

Expected result: the account is authenticated and the Confluence connection is available. If the connection is missing, stop and connect the intended read-only or least-privilege account. Do not paste an Atlassian token into the prompt or repository.

Step 1: discover the current read Actions

Search the live catalog rather than relying on action names copied from an old prompt:

aident capabilities search \
  --query "Confluence list spaces list pages get page ancestors" \
  --types '["action"]'

Expected result: current Actions for listing spaces and pages, plus optional page-detail, ancestor, or child-page reads. Copy the exact public Action name and version returned in your environment. Do not publish or hard-code internal provider identifiers.

Inspect each selected Action before execution:

ACTION_NAME="paste-the-returned-action-name"
ACTION_VERSION="paste-the-returned-version"
aident capabilities get --name "$ACTION_NAME" --version "$ACTION_VERSION"

Confirm the input schema, pagination field, output shape, connection requirement, and risk classification. If the schema does not expose a cursor or another complete traversal method, do not call that Action an inventory tool.

Step 2: enumerate visible spaces

Ask the agent to run the discovered List Spaces Action and continue through every returned next cursor. Preserve this minimum record for each space:

{
  "spaceId": "123456",
  "spaceKey": "ENG",
  "spaceName": "Engineering",
  "status": "current",
  "pageCursorComplete": false
}

Space names are labels for humans; IDs are the stable join key. Atlassian's v2 space endpoint says results are permission-scoped and additional results appear through the next link. Record the identity and the time of the run beside the inventory so a later permission change does not silently rewrite what "all spaces" meant.

Expected result: the final space response has no next cursor, and the inventory contains a stable ID for every visible in-scope space.

Step 3: enumerate every page in each space

For each recorded space ID, run the current List Pages Action with an explicit status and space filter. Continue until no next cursor is returned. Store one row per page:

{
  "pageId": "987654",
  "spaceId": "123456",
  "title": "Release checklist",
  "status": "current",
  "parentId": "456789",
  "version": 12
}

Do not fetch every body during the counting pass. A metadata-first inventory is easier to retry, deduplicate, and review. Use pageId as the unique key; duplicate titles are normal.

After each space finishes, set pageCursorComplete to true and record the page count. A space is incomplete if the run stopped on an error, timeout, or cursor that was never followed.

Expected result: every in-scope space has a terminal cursor state, a count, and page IDs that are unique within the site inventory.

Step 4: reconcile permissions and hierarchy

The agent can only report what its connected identity can see. Atlassian explains that page restrictions can be inherited from a parent and that restricted content is absent for people without view permission. That makes a permission comparison part of inventory quality, not an optional security review.

Give a space admin the per-space counts and ask them to compare those counts with Confluence's content-management view. Investigate any difference before migration. Common causes include:

• a restricted parent hiding its descendants;

• a personal or archived space excluded from the declared scope;

• a recently deleted or deactivated restriction owner;

• a page status omitted by the list filter;

• an interrupted cursor traversal.

When navigation structure must survive the migration, sample root pages and retrieve their ancestors or direct children. Confirm that every non-root page points to a parent present in the same inventory or appears in an explicit orphan list.

Expected result: differences are resolved or recorded as named exceptions with an owner. "The API returned no more rows" is not sufficient evidence when the agent and admin counts disagree.

Step 5: freeze and approve the manifest

Sort the manifest by stable ID, serialize it deterministically, and calculate a SHA-256 hash:

shasum -a 256 confluence-page-inventory.json
# On Linux: sha256sum confluence-page-inventory.json

Record the hash, collection time, authenticated identity, site, filters, final space and page counts, and unresolved exceptions. Have the workspace owner approve that exact manifest before fetching full bodies or preparing destination writes.

If the source changes during migration, create a new inventory and hash. Do not quietly append pages to an already approved manifest.

Common failures

A title search returns only part of the space

That is expected: title search is a discovery tool. Switch to the paginated page-list Action for the inventory, then use search only to locate a known page or investigate a discrepancy.

A space key filter includes unexpected results

Treat the returned spaceId as authoritative. The current Search Content contract warns that its space-key scope is not strict. Filter and reconcile by returned IDs, or use the page-list Action's explicit space ID input.

The second page repeats records

Deduplicate by page ID and verify you passed the latest returned cursor rather than the original one. Stop if a cursor loop repeats; preserve the last response and rerun that space instead of guessing where to resume.

The agent finds fewer pages than an admin

Assume a permission or scope mismatch first. Compare spaces, page statuses, parent restrictions, and the connected identity. Do not grant broader access automatically; a workspace owner should decide whether restricted content belongs in the migration.

The inventory is complete but bodies are missing

Inventory and extraction are separate phases. Fetch each approved page by ID only after the manifest is frozen. Preserve the version number so edits made after approval can be detected before import.

Run the audit with a human checkpoint

Use this request after connecting Confluence through Aident Loadout:

Build a read-only Confluence page inventory. Discover and inspect the current Actions first. Enumerate every visible space and every page with complete cursor traversal, preserve stable IDs and versions, and report counts and exceptions. Do not fetch full bodies or write anywhere. Stop after producing a deterministic manifest and SHA-256 hash for my review

Success is not a large JSON file. It is an approved, reproducible boundary between source discovery and migration writes.

For the wider tool-connection model, read how Claude Code and Codex connect to real-world tools. To evaluate governance and portability, compare Aident Loadout with Zapier. If this is your first Loadout workflow, follow the ten-minute first-task guide.

Create one reviewed Confluence inventory, then approve its hash before any migration write. The attributable outcome is a setup start followed by one completed, owner-reviewed inventory manifest.

Why this works

The workflow separates four questions that broad search blends together: what the connected identity can see, whether every response page was traversed, which stable records belong in scope, and which exact manifest a human approved. That boundary makes missing pages visible before a write path can amplify the mistake.

Sources

• Confluence Cloud REST API v2 introduction, Atlassian, accessed September 10, 2026

• Confluence Cloud REST API v2: Space, Atlassian, accessed September 10, 2026

• Change who can find content and what they can do with it, Atlassian, accessed September 10, 2026

• Aident Loadout live staging catalog and Confluence Action schemas, inspected September 10, 2026

Refresh this guide when Atlassian changes v2 pagination or restriction behavior, or when the public Confluence Action schemas change their scope, limits, or cursor contracts.