How to Migrate From Cosmic to a Self-Hosted CMS

Cosmic (formerly Cosmic JS) is a hosted headless CMS with a friendly API and a quick setup — popular for JavaScript projects that want content without running a server. Like any SaaS CMS, the reasons to leave are cost as you scale, content living on Cosmic's platform, API rate limits, and no self-hosting option. Migrating off Cosmic to a self-hosted CMS is straightforward: its API is clean and its content model is simple. Here's the path, with SEO protected.

TL;DR: Export Cosmic content via its REST API, map objects to posts and pages, import into a self-hosted CMS like UnfoldCMS, preserve slugs, set up 301 redirects for any changed URLs, and repoint your front end. Both sides are REST, so the front-end rewrite is light.

Why migrate off Cosmic?

Pin down your reason — it guides the work:

• Cost at scale. Cosmic pricing rises with API requests, users, and storage. Growth means a bigger bill.
• Hosted-only. Cosmic is SaaS. If you need content on your own infrastructure, you have to move.
• Data ownership. Your content lives on Cosmic's servers. A self-hosted CMS puts it in your own database. See data ownership and your CMS.
• Rate limits. You're metered on API calls — a constraint for high-traffic or build-heavy sites.

If Cosmic's convenience is worth the fee, staying is fine. If ownership or cost drives you, read on.

What you're moving to

This guide targets UnfoldCMS, a self-hosted CMS on Laravel with a REST API at /api/v1/*, content in your own SQLite or MySQL database, and a one-time cost. Good news for the migration: Cosmic is REST-based and so is UnfoldCMS, so unlike leaving a GraphQL CMS, your front-end rewrite is minimal — mostly changing URLs and adjusting the response shape.

Step 1 — Export from Cosmic

Cosmic exposes content through its REST API. Pull all objects (its term for entries):

curl "https://api.cosmicjs.com/v3/buckets/YOUR_BUCKET/objects?limit=100&props=slug,title,content,metadata,created_at" \
  -H "Authorization: Bearer YOUR_READ_KEY"

Page through with skip/limit until you have every object. Each returns clean JSON with title, slug, content (often HTML), and any metadata fields. Save the full export and download media referenced in your objects to rehost.

Step 2 — Map objects to posts and pages

Cosmic objects are typed (you defined Object Types). Map them to the target CMS:

Cosmic's content model is flat and simple, so this mapping is quick — no nested block tree to flatten.

Step 3 — Handle body format

Check how content is stored. Cosmic's rich-text editor typically outputs HTML, which drops straight into UnfoldCMS (it stores body as HTML). If any content is markdown, convert it on import. Verify a few records first — check headings, links, and images survive.

Step 4 — Import into the CMS

Write a migration script that reads the Cosmic export and creates a post or page per object. Preserve slugs for SEO, set posted_at from the original date to keep chronology, map metadata to SEO fields, and attach media to the library. Since both sides are REST APIs, you can script the whole read-transform-write loop end to end.

Step 5 — Preserve SEO with redirects

If URLs change, set up 301 redirects from old to new paths. UnfoldCMS ships a redirects system. Preserve slugs to keep most URLs identical and redirects minimal — but audit every path. This protects rankings; don't skip it. See migrate a blog without losing SEO.

Step 6 — Repoint your front end

Your front end calls Cosmic's REST API. Update it to call UnfoldCMS's REST API and adjust the response mapping — read data.data from the { success, message, data } envelope instead of Cosmic's objects array. Because both are REST with similar shapes, this is a light change, not a rewrite.

// Before (Cosmic)
const res = await fetch(`${COSMIC}/objects?type=posts`);
const { objects } = await res.json();

// After (UnfoldCMS)
const res = await fetch('https://cms.yoursite.com/api/v1/posts?per_page=20');
const { data: posts } = await res.json();

Step 7 — Rebuild-on-publish

If Cosmic webhooks triggered rebuilds, replicate with UnfoldCMS's outgoing HMAC-signed webhooks pointed at your deploy hook. Publishing fires the rebuild — same flow, self-hosted.

Migration checklist

• [ ] Export all objects via the REST API
• [ ] Download referenced media
• [ ] Map object types to posts and pages
• [ ] Confirm body format (usually HTML) and convert if needed
• [ ] Import content, preserving slugs and dates
• [ ] Attach media to the library
• [ ] Set up 301 redirects for any changed URLs
• [ ] Repoint front-end API calls (light — REST to REST)
• [ ] Replicate rebuild webhooks
• [ ] Verify sample pages before go-live

FAQ

Can I export my content from Cosmic? Yes. Cosmic's REST API returns every object with its fields, and media is downloadable. You get a full, exportable copy of your content.

Will I lose SEO migrating off Cosmic? Not if you preserve slugs and set up 301 redirects for any changed URLs. Same-slug migrations need minimal redirects.

Is migrating off Cosmic hard? It's one of the easier migrations. Cosmic's content model is flat, its API is REST, and content is usually HTML — so both export and the front-end rewrite are light. The main work is mapping object types to posts and pages.

Do I have to rewrite my front end? Only lightly. Both Cosmic and UnfoldCMS are REST APIs, so you change endpoint URLs and adjust the response shape — no GraphQL-to-REST rewrite like some migrations require.

Bottom line

Migrating off Cosmic is one of the smoother CMS moves: export via REST, map objects to posts and pages, import into a self-hosted CMS, and protect SEO with redirects. Because both Cosmic and UnfoldCMS are REST-based with simple content models, the front-end change is minor. You gain data ownership and drop the subscription with little friction.

See UnfoldCMS in the demo or read the blog migration SEO guide.

Related: Migrate from Contentful · How to migrate a blog without losing SEO · Self-hosted vs SaaS CMS