Migrating to Agility

Moving a website or content hub to Agility CMS is a project with a predictable shape. This page breaks it into six phases, says who usually does what, shows where an AI agent saves time, and links to guides for specific source systems and for launch day.

The six phases

Phase	Goal	What you end up with
1. Inventory	Know exactly what you are moving	Counts per content type, fields in use, relationships, assets, URLs, integrations
2. Model	Design the target in Agility	Content models, component models, page models, containers, locales
3. Map	Decide how each source field becomes an Agility field	A field map, a URL map and transform rules
4. Import	Load content into Staging	A re-runnable import script and a source ID to Agility content ID map
5. Verify	Prove the import is complete and correct	Counts, spot checks, preview review, sign-off
6. Cut over	Move traffic to the new site	Content freeze, final sync, redirects, DNS change, rollback plan

Phases 3 to 5 usually loop. Import a small sample, check it, fix the model or the map, and import again. Changing a model is much cheaper before thousands of items exist.

1. Inventory

• Count the items of each content type in the source, and list the fields that are actually populated, not every field the source system supports.
• Record relationships between records (authors, categories, related items). They become linked content in Agility.
• List the assets you need to move: featured images, inline images, downloadable files.
• Export every public URL now, from the old site's sitemap, its CMS and your analytics. You need this list for redirects. See Keep Your Search Rankings Through a Migration.
• List the integrations that read from or write to the old system: forms, search indexes, feeds, webhooks.
• Note anything awkward: shortcodes, page-builder markup, embedded scripts, content that differs per locale.

2. Model

Design the destination before you move anything. Decide which source patterns become:

• Content models and containers for lists of structured content such as articles, authors and categories. See Content Models.
• Component models for the building blocks editors place on pages, and page models for page layouts and their zones. See Component Models and Page Models.
• Pages in the sitemap, including dynamic pages that generate one page per item in a list. See Generating Dynamic Pages From Content.
• Linked content relationships. See Getting Started with Linked Content.
• Locales, if the source is multilingual.

Aim for structure, not HTML blobs: authors, dates, images and categories should be their own fields or linked items. Legacy Content Migration explains why. Use letters and numbers only in reference names; a hyphenated container name can't be queried through GraphQL.

3. Map

Write down, for every source content type, which Agility model and container it goes to, and for every field, the Agility field and any transform. A field map is a simple table:

Source field	Agility field	Field type	Transform
title	Title	Text	Decode HTML entities
body	Body	HTML	Rewrite internal links and image URLs
author (ID)	Author	Linked Content	Look up the Agility content ID of the imported author
id	SourceID	Text	Store as-is, so re-runs update instead of duplicating

Decisions to make in this phase:

• Rich text: keep it as HTML in an HTML field, convert it to Markdown for a Markdown field, or break recurring patterns into fields and components.
• References: which items must exist first so others can link to them.
• Assets: which files to upload to the media library, and how to rewrite their URLs in body content.
• URLs: the new path for every old URL, and which ones need a redirect.

Field Types and What the APIs Return shows what each Agility field type stores and returns, which helps you pick types.

4. Import

Pick the tool that fits the volume and the job:

Tool	Best for	Notes
AI agent with the Agility MCP Server	Creating models and importing a reviewable sample of dozens of items	Every call is visible in the conversation. See Migrating Content into Agility with an AI Agent.
Management SDK (JavaScript or .NET) or the Management API	Hundreds of items or more, and imports you need to re-run	Save in sequential batches. See the throughput notes below.
Content list Excel export and import	Small lists you want to edit by hand	See Importing Content.
URL Redirections import	Loading many redirects at once	See URL Redirections.
Agility CLI	Copying models and content between Agility instances, for example from a migration sandbox into a blank production instance	Not an importer for other systems. Sync into a blank target; synced items get new content IDs; sync never deletes on the target.

Import in dependency order: upload assets and create the items others point to (authors, categories, tags) first, keep a map from source ID to Agility content ID, then import the items that reference them, then build pages.

Throughput: batches, limits and tokens

• Writes are queued. Every Management API save, delete or workflow operation is queued as a batch and completes moments later. The SDKs wait for the batch by default. See Batches and the Batch API.
• Run batches one after another, not in parallel. Parallel calls can trigger rate limiting and batch conflicts.
• Use the bulk endpoints. One batch workflow call publishes, unpublishes or approves up to 250 items. One URL redirections call creates or updates up to 250 redirects.
• Check every item. A processed batch can still contain failed items, so read each item's errorMessage. The JavaScript SDK's saveContentItems returns -1 for an item that failed.
• Back off on 429. If the API answers 429 Too Many Requests, wait and retry with an increasing delay. Build the import to slow down when told to rather than aiming at a fixed rate.
• Page every list. Management API lists return 50 items by default and at most 250 per request. Page with take and skip until a short page comes back.
• Only re-save what changed. Every save creates a new version of the item.
• Use a Personal Access Token for long jobs. OAuth access tokens last 24 hours. See Personal Access Tokens.
• Your new site has limits too. The Content Fetch API allows 10 uncached requests per second; responses served from the CDN cache don't count. Keep this in mind for verification crawls and full-site builds. See Fetch API Status Codes and Caching.

5. Verify

Before anything is published, check:

• Item counts per container match the source, minus anything you skipped on purpose.
• Every failed save is accounted for, and re-runs updated items instead of creating duplicates.
• Linked content resolves in the editor (dropdowns show a value, not a blank).
• Image and file fields point at cdn.aglty.io, not the old site.
• Body content has no leftover shortcodes, page-builder markup or links to the old domain.
• Content is in the right locale.
• A sample renders correctly on the new site in preview mode.
• Every URL in your inventory either exists on the new site or has a redirect.

The full checklist, with a prompt that asks an agent to run the checks, is in Migrating Content into Agility with an AI Agent.

6. Cut over

Launch day has its own sequence: content freeze, final sync, publishing, redirects, the DNS change, cache and webhook checks, and a rollback plan. Follow the Migration Cutover Runbook, and use Keep Your Search Rankings Through a Migration for the SEO side.

Who does what

One person can hold several of these roles on a small project.

Role	Responsibilities
Project lead	Scope, timeline, freeze dates, the go or no-go decision
Content modeler	Inventory, content and component models, the field map. Creating models needs an Agility role that can manage models (Designer, Manager or Admin).
Developer	Export and import scripts, the front end, redirects, webhooks, preview
Content owners and editors	Review the sample, fix content that can't be mapped automatically, sign off
SEO owner	URL inventory, URL map, metadata, post-launch monitoring
Agility administrator	Users and roles, tokens, webhooks. Running the CLI needs the Org Admin, Instance Admin or Manager role.

Where an AI agent helps

An agent connected to the Agility MCP Server is most useful at the start and the end of a migration:

• Inventory: read the source API or export file and report content types, counts, fields in use and awkward cases.
• Model: propose content models from the inventory, check what already exists in your instance, and create the approved models and containers.
• Sample import: import 10 to 20 varied items into Staging so people can review them in the editor.
• Script: write the Management SDK import script from the approved models and the sample's field shapes.
• Verify: page through every container and report empty fields, leftover markup and broken asset URLs.

Keep people in the loop where it matters: approving the model, reviewing the sample and deciding when to publish. The agent acts with your Agility permissions. Move bulk volume to a script rather than individual tool calls. The whole flow, with prompts and code, is in Migrating Content into Agility with an AI Agent.

Guides in this section

• Migrate from WordPress to Agility
• Migrate from Contentful to Agility
• Migrate from Sitecore to Agility
• Migration Cutover Runbook
• Keep Your Search Rankings Through a Migration

Migrating from another system, or from hand-built HTML? The phases above still apply, and Legacy Content Migration covers parsing HTML into structured fields.

Related

• Migrating Content into Agility with an AI Agent
• Batches and the Batch API
• Getting Started with the Management SDK
• AgilityCLI (Command Line Interface)
• Website Deployment Checklist