Migrate from WordPress or Webflow

Most people arriving at a new CMS are not starting from nothing. They have a few hundred posts somewhere else, a set of URLs that already rank, and no appetite for copying content by hand.

This lesson covers moving that content into Cosmic: what to decide before you start, the agent-assisted path, the scripted path, and how to check the result.

---

Before You Start

• A Cosmic bucket with your object types already created. Migrating into a model you have not designed yet produces a mess you will migrate again. Lesson 6 covers modeling

• An export from your current system

• Your Write key, found under Settings > API keys, if you take the scripted path

---

Step 1: Decide What Actually Comes Over

The instinct is to bring everything. Resist it.

A migration is the one moment when deleting content costs you nothing extra. Posts that get no traffic, duplicates from a redesign three years ago, drafts nobody finished: leaving them behind is faster than moving them and makes everything afterwards easier.

Pull a traffic report from your current analytics, sort by pageviews, and draw a line. Everything above it migrates. Everything below it needs a reason.

---

Step 2: Make Three Schema Decisions

These are much cheaper to get right now than later.

Slugs. If your old URLs rank, keep them. Cosmic lets you set explicitly when creating an object, so can stay . If you do not set one, Cosmic generates it from the title, which is usually close but not identical, and "close" means a broken link.

Authors and categories. In WordPress these are taxonomies attached to a post. In Cosmic the better shape is usually separate object types with an object relationship pointing at them, so an author has a bio and photo in one place rather than repeated on every post. Create those object types and their objects first, then reference them as you import posts.

Dates. This one has a real constraint. You cannot set through the API; Cosmic sets it to the moment of the write. You can set , so if your site sorts or displays by publish date, map your original dates into that field. If you sort by , everything you migrate will appear to have been written today.

---

Step 3: The Agent Path

Cosmic ships an agent template built for this, which is the fastest route if you would rather not write a script.

1. Go to Agents and click New Agent

2. On the Use a template tab, find Sam, Migration Specialist under the Migration & Import category, and click Hire Sam

3. Open his Settings, go to Tools & Capabilities, and find Migrate from in the integrations catalog to pick your source

WordPress and Webflow both have prepared prompts, as do Contentful, Strapi, Sanity, Ghost, Drupal, and Prismic. Give the agent access to your export file and tell it which object type each content set should land in.

Give it a handful of posts first, not the whole archive. Look at what it produced in the dashboard: are the fields mapped to the right metafields, did the slugs survive, did the images come across. Fix the instructions, then let it run the rest. An agent that maps a field wrong on ten posts is a five-minute correction. On a thousand posts it is a re-import.

---

Step 4: The Scripted Path

For a large or unusual migration, a script gives you exact control.

Get your export. WordPress exports WXR, an XML format, from Tools > Export. Webflow exports one CSV per collection from the collection settings. Either way you are parsing a file into a list of records.

Note that Cosmic's dashboard import expects a file, which is Cosmic's own export format. There is no CSV or WordPress importer in the dashboard, so a WordPress or Webflow export becomes objects through the API rather than through an upload.

Write the records. Create objects one at a time with :

Or use to send up to 25 operations in a single request, which is meaningfully faster over a few hundred posts:

Handle media separately. Images in your old system are URLs. Cosmic has no way to pull from a remote URL, so your script has to download each file and upload the buffer:

Upload the images before the posts that reference them, and keep a map from old URL to new media name so you can rewrite the image references in the body content.

---

Step 5: Verify

Do not trust a script that printed no errors.

Open API Tools from the objects list and run a query against the type you imported. Check the count against the number you expected, then open two or three objects and confirm the fields landed where you meant them to.

Two checks worth doing specifically:

Query for objects with an empty required field. If your source had inconsistent data, this is where it shows up.

Spot-check slugs against your old URLs. If Cosmic found a duplicate slug during import it appended a unique suffix rather than failing, so a handful of posts may have URLs you did not intend.

---

A Tip on Sequencing

Run the migration in this order, and test after each stage rather than at the end:

1. Object types

2. Authors, categories, and anything else that gets referenced

3. Media

4. Posts, which reference all of the above

The temptation is to write one script that does everything in a single pass. The problem is that when it fails halfway through, you are left with a partially populated bucket and no clean way to retry. Separate stages can each be re-run.

If you do need to start over, Settings > Import / export has a Replace mode that clears the bucket's content before importing, which is a faster reset than deleting objects by hand.

---

Going Further

Rate limits are generous but not infinite: the API allows 100 requests per second. A migration script firing without any pacing can hit that. Batching in groups of 25 keeps you well clear.

Check your plan's object limit before importing a large archive. Exceeding it returns an error mid-migration rather than silently truncating.

For moving content between Cosmic buckets, you do not need any of the above. Settings > Import / export exports a with your content and media, and imports it into another bucket. Clone on a bucket's menu does the same thing in one step.

---

Do This in Your Project

1. Export your content from your current system

2. Confirm your object types exist in Cosmic and include a field for every piece of data you are bringing over

3. Import five posts, either with Sam, Migration Specialist or a script

4. Open them in the dashboard and check the fields, slugs, and images

5. Fix the mapping, then run the rest

The five-post test is the whole discipline here. Everything that goes wrong in a migration goes wrong in the first five records.

---

Up Next

Lesson 8: REST API Integrations and Webhooks

Your content is in Cosmic. Lesson 8 covers getting it out to other systems, and having Cosmic tell them when something changes.