Documentation & guides

AIRA migrates content into Advanced Custom Fields. To get the most out of it, make sure your new build meets the following.

AIRA turns the slowest part of a rebuild — moving content into ACF — into a guided, mostly-automatic process.

1. 1Generate a mapping spec from your ACF field-group export — AIRA learns every placeable block, field key, and repeater, and (with AI) labels each block and writes trigger rules.
2. 2Point AIRA at the old site. It discovers the sitemap, crawls each page, and classifies every section into your ACF blocks, attaching a confidence score to each.
3. 3Commit the finished run and download bundle.json — that spends one credit per page in the bundle (1 credit = 1 page). Crawling and classifying were free.
4. 4Open the bundle in the ACF Migrate importer plugin, review block choices, and import as drafts. AIRA sideloads images, rewrites internal links, and migrates SEO.

Work through this checklist to migrate your first page end to end.

• check_boxRegister your ACF blocks on the new site and export the field groups as JSON.
• check_boxInstall and activate the ACF Migrate importer plugin on the new site.
• check_boxSign in at app.wpaira.com and upload the ACF export to generate your mapping spec.
• check_boxEnter an old site URL (set max pages and exclude paths) and run the crawl — this is free.
• check_boxReview the results in the app, then commit the run and download bundle.json (1 credit per page in the bundle).
• check_boxGo to Tools → ACF Migrate, upload the bundle, and review the block choices and confidence scores.
• check_boxChoose Draft and click Import — this creates draft pages on your new site at no extra credit cost.

AIRA reads your field structure from an ACF JSON export. This is what makes the mapping accurate.

1. 1In WordPress admin go to ACF → Field Groups.
2. 2Tick the field groups used by the pages you want to migrate.
3. 3From the bulk actions dropdown choose Export → Export As JSON.
4. 4Download the .json file.
5. 5Upload that file into your AIRA project.

AIRA crawls and classifies in the cloud, then hands you a bundle.json. The free ACF Migrate importer plugin reviews and imports that bundle on your new site.

1. 1Download the ACF Migrate importer plugin from the AIRA app (app.wpaira.com).
2. 2In WordPress admin go to Plugins → Add New Plugin → Upload Plugin, choose the ZIP, and activate it.
3. 3Go to Tools → ACF Migrate.
4. 4Drag your bundle.json onto the upload area, choose an import status (Draft is recommended), and click Upload & review.

Each page is split into sections (using its <section> containers, or H1/H2 boundaries when the theme has none). Every section is classified independently into one of your ACF blocks.

• arrow_rightComposite blocks (hero, cards, stats, FAQs, services, steps…) are matched by AI, which fills their fields — including image and link sub-fields — from the section HTML.
• arrow_rightAtomic fallbacks always produce a valid result: prose becomes an acf/generic-text WYSIWYG block (inline formatting kept), 3+ images become a gallery, a lone image becomes a full-width image, a blockquote becomes a quote, and video becomes a full-width video.
• arrow_rightEvery block gets a confidence score and any un-scrapeable fields are flagged for review.

On import, the ACF Migrate plugin sideloads every image referenced on the page into your new site's Media Library and attaches it to the correct ACF image or gallery field.

• arrow_rightImages are sideloaded via WordPress's media_sideload_image — any that fail are listed so you can re-host them.
• arrow_rightInternal links pointing at the old site are rewritten to your new page paths automatically.
• arrow_rightExternal links are left untouched.

AIRA outputs real Gutenberg blocks. On import, each block is built with WordPress's own serialize_block() using the field keys from your export, so it opens natively in the block editor.

The crawler reads a live page and extracts its content into clean, structured data — no scraping scripts or manual copy-paste required.

• arrow_rightDiscovers pages from the site's sitemap, or migrates a single URL.
• arrow_rightReads headings, paragraphs, lists, images, and links with the full DOM intact (so images and link hrefs reach the classifier).
• arrow_rightInclude/exclude path filters and a max-pages cap let you skip /blog/, /tag/ and the like.
• arrow_rightIf the site is behind Cloudflare, use your Crawl setup token in a WAF rule, or configure a BYO residential proxy.
• arrow_rightAIRA tries plain requests first, then TLS impersonation, then your proxy — only when a page is genuinely blocked.

In Tools → ACF Migrate you review the whole bundle before importing. Each block shows a confidence bar and any review flags, so the uncertain ones are easy to spot.

1. 1Expand any page to see its blocks in order, with confidence scores.
2. 2Reassign a block to a different type from the dropdown, reorder with the arrows, or drop junk blocks entirely.
3. 3Edit the new page path/slug for each page.
4. 4Choose Draft, Pending, or Published, then import all pages — one credit per page.

Point AIRA at the old site and it discovers every page from the sitemap, crawls and classifies them in one run, and bundles them together. You still review and import each page, so you stay in control of every credit spent.

AIRA carries your SEO over and helps you avoid broken links when the URL structure changes.

• arrow_rightPage title, meta description and canonical are written into Yoast SEO or Rank Math (or stored generically if neither is active).
• arrow_rightOpen Graph title, description and image are migrated too.
• arrow_rightAfter importing, the plugin generates a redirect map (old → new) you can download as redirects.csv.

AIRA reads a site by fetching its pages from our servers. Most sites work with no setup. Some sites sit behind a firewall or bot protection — Cloudflare is the most common — that blocks automated requests from datacenter IP addresses, so the crawl comes back empty or with an access-blocked message.

There are two ways to fix this. Pick whichever fits your situation.

• arrow_rightOption 1 — Allowlist AIRA in Cloudflare (recommended if you manage the site). One WAF rule, no IP addresses to maintain.
• arrow_rightOption 2 — Bring your own proxy. Route the crawl through a residential IP if you don't control the site (e.g. a prospect pitch).

If you (or your client) control the site's Cloudflare account, this is the cleanest fix. Add one rule that tells Cloudflare to let our crawler through when it sees a secret header we send. No IP addresses to maintain, nothing extra to pay for.

1. 1Log in to the Cloudflare dashboard and select the domain you're migrating.
2. 2Go to Security → WAF → Custom rules (on newer dashboards: Security → Security rules).
3. 3Click Create rule and name it something like Allow AIRA crawler.
4. 4Switch the condition builder to Edit expression and paste: any(http.request.headers["x-aira-crawl"][*] eq "aira-YOUR-TOKEN-HERE") — replace with your token from Crawl setup. Header names are lower-cased in Cloudflare's expression language.
5. 5Under Then take action, choose Skip.
6. 6In the skip options, tick the protections blocking the crawl — usually All managed rules and, if enabled, Super Bot Fight Mode. Also tick Rate limiting rules for large sites.
7. 7Deploy the rule and run the crawl again.

If you don't control the site — for example, you're putting together a pitch for a prospect — route the crawl through a proxy that uses a residential IP, which these firewalls trust.

1. 1Sign up with a residential-proxy provider. Common options include Bright Data, Oxylabs, Smartproxy/Decodo, and IPRoyal. They bill by bandwidth, so a migration (a few hundred pages of HTML) costs very little.
2. 2From the provider, get your proxy endpoint URL — it looks like http://USERNAME:PASSWORD@gateway.provider.com:7000
3. 3In AIRA, open Crawl setup, paste the URL into the proxy field, and save.
4. 4Run the crawl. AIRA only uses the proxy when a site blocks the direct request.

• arrow_rightConfirm the token in your Cloudflare rule matches the one in Crawl setup exactly (no trailing spaces).
• arrow_rightCheck whether the block is Cloudflare or something else — the crawl log names what it detected (e.g. "Cloudflare; WAF hard block" or "JavaScript challenge / Turnstile detected").
• arrow_rightSites showing a full "Just a moment…" JavaScript challenge need a real browser to solve it; the Cloudflare header rule removes that challenge for our crawler when you control the site.
• arrow_rightFor a quick prospect demo, crawl a single public page that isn't behind the firewall, or use the client's staging site once you're engaged.

A credit is the unit AIRA uses to measure migrations. The rule is deliberately simple: 1 credit = 1 page in your committed bundle.

• arrow_rightCrawling and classifying pages is free.
• arrow_rightReviewing the bundle in the ACF Migrate plugin is free.
• arrow_rightCommitting a finished run and downloading bundle.json spends one credit per page in that bundle.
• arrow_rightImporting the bundle into WordPress does not cost additional credits.

Every plan includes a set number of credits each month that refresh at the start of your billing cycle.

Because 1 credit = 1 page, your plan size maps directly to how many pages you migrate each month.

Need more than your monthly allowance? Top up at any time. Extra credits are always 79p each, and bulk packs are cheaper per credit.

• arrow_rightMonthly plan credits reset at the start of each billing cycle and do not roll over — any unused monthly allowance is replaced on renewal.
• arrow_rightPurchased top-up credits never expire and sit in a separate balance.
• arrow_rightWhen you commit a run, AIRA spends monthly credits first, then dips into purchased credits.
• arrow_rightIf you cancel a subscription, your purchased credits remain — only the monthly allowance is cleared.

Choose annual billing on any paid plan and you get two months free — you pay for ten months and receive twelve months of credits.

You can upgrade, downgrade, or cancel at any time from the AIRA app (Manage subscription in the app header).

• arrow_rightUpgrades take effect immediately with the new credit allowance.
• arrow_rightDowngrades and cancellations take effect at the end of your current billing cycle.
• arrow_rightAny extra credit packs you've purchased remain in your balance regardless of plan changes.

• arrow_rightIn the review screen, use the block dropdown to reassign the section to the correct block before importing.
• arrow_rightRegenerate your spec with AI enabled — it writes sharper trigger rules and distinguishes near-identical blocks.
• arrow_rightMake sure your ACF export is current; if you've added blocks or fields since exporting, re-export and regenerate the spec.
• arrow_rightGive blocks and fields clear, descriptive names and labels — the classifier uses them to decide what goes where.

• arrow_rightCheck the old page is publicly reachable — content behind logins or popups can't be crawled.
• arrow_rightContent loaded by JavaScript after page load may not appear; provide a direct URL to the rendered content where possible.
• arrow_rightConfirm your ACF export actually contains a field for that content type — AIRA can only place content into fields that exist.
• arrow_rightRe-crawl the page; transient network issues on the old site can cause partial reads.

• arrow_rightConfirm Import images is enabled in your project's media settings.
• arrow_rightCheck the destination site allows uploads and has enough disk space.
• arrow_rightSome old hosts block hotlinking — if image URLs return 403, the files can't be fetched.
• arrow_rightVery large images may exceed your server's upload limit; set a Max image width to downscale on import.

Before importing, the ACF Migrate screen shows how many field keys it recognises (e.g. 42 / 48). A low number means the blocks on the destination site don't match the export your spec was built from.

• arrow_rightConfirm the same ACF blocks are registered and active on the destination site.
• arrow_rightMake sure the field keys match — re-import the field groups from the same ACF export.
• arrow_rightRegenerate the spec from the destination site's current export if the structure has changed.
• arrow_rightIf the import job says it expired, simply re-upload the bundle.json — jobs are held for an hour.

A credit is how AIRA measures migrations: 1 credit = 1 page in your committed bundle. You spend credits when you commit a finished crawl and download bundle.json — not when you import into WordPress. Crawling, classifying, and reviewing are always free.

Yes, at any time. Extra credits are always 79p each, and you save more by buying in bulk — 100, 250, or 500-credit packs bring the per-credit price down. Purchased credits are added straight to your balance.

Nothing breaks. You can keep crawling and classifying for free. You just won't be able to commit and download a bundle until you top up or your monthly credits renew. AIRA checks your balance before starting large runs and again at commit time. There are no overage fees or surprise charges.

Monthly plan credits reset at the start of each billing cycle and don't roll over. Extra credits you purchase in a pack never expire — they stay in your balance until you use them.

AIRA produces native ACF blocks (Gutenberg), built on import with WordPress's own serialize_block() using your exact field keys. Your new site needs the matching ACF block library registered and the free ACF Migrate importer plugin installed.

AIRA only reads your old site — it never modifies it. Pages are imported to your new build as drafts by default, so nothing goes live until you review and publish. Bought credits are never lost.

No. The AI classification is powered by Claude and runs on our servers — there are no separate API keys to set up or AI bills to manage, and your key never touches the browser. Your credits cover everything. AIRA can even run deterministically without AI, falling back to a generic-text block so you always get a valid result.