DEV Community: Tony Spiro

Best Headless CMS for Astro in 2026: 4 Options Compared

Tony Spiro — Wed, 11 Nov 2026 17:01:56 +0000

Astro builds static HTML by default, which changes what you should want from a CMS. The content fetch runs once at build time, not on every request, so raw API latency matters far less than it does on a server-rendered stack. What matters instead is whether the SDK works cleanly inside Astro frontmatter, whether getStaticPaths can hydrate every page from a single query, and whether a rebuild gets triggered when an editor publishes.

This guide compares four headless CMS platforms on those terms. Every price below was read directly from the vendor's own pricing page on November 10, 2026, and each figure is linked to its source. Vendors whose pricing could not be read and cited on that date were left out rather than guessed at.

What Astro actually needs from a CMS

A JavaScript SDK that runs in frontmatter. Everything between the --- fences executes on the server at build time. An SDK that assumes a browser or a long-lived server process will fight you.

Lean queries. A list page needs a title, a slug, and an image. Pulling full post bodies you never render is the easiest performance mistake to make on a static build.

One query per route set. getStaticPaths runs once and enumerates every dynamic route. If you can pass the fetched record through props, you build the whole blog in a single request instead of one lookup per page.

A rebuild trigger. Static output does not change when content changes. You need a webhook that calls your host's deploy hook on publish.

Predictable empty-result behavior. At build time, an unhandled error from the CMS fails the entire build, not one page.

Cosmic

Cosmic is a SaaS headless CMS with a REST API and an official TypeScript SDK, @cosmicjs/sdk. It is a Y Combinator company (W19). Astro's own documentation ships a Cosmic integration guide, so the setup path is documented on both sides.

The SDK is a plain async client, which is what you want inside frontmatter:

// src/lib/cosmic.ts
import { createBucketClient } from '@cosmicjs/sdk';

export const cosmic = createBucketClient({
  bucketSlug: import.meta.env.COSMIC_BUCKET_SLUG,
  readKey: import.meta.env.COSMIC_READ_KEY,
});

Astro reads environment variables through import.meta.env, not process.env. That is the single most common porting error when you move example code over from a Next.js tutorial. Skip the PUBLIC_ prefix on these two values so they stay out of the browser bundle.

Building every post page from one query:

---
// src/pages/blog/[slug].astro
import { cosmic } from '../../lib/cosmic';

export async function getStaticPaths() {
  const { objects } = await cosmic.objects
    .find({ type: 'blog-posts' })
    .props(['title', 'slug', 'metadata'])
    .depth(1);

  return objects.map((post: any) => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
---

<article>
  <h1>{post.title}</h1>
  <div set:html={post.metadata.content} />
</article>

Because getStaticPaths already fetched every post, handing the record through props means no second lookup per page. .depth(1) resolves relationships, so an author reference comes back as the full author object rather than an ID.

One behavior worth knowing before your first build: when a query matches nothing, the SDK throws a 404 rather than returning an empty array, and both find() and findOne() do this. On a static build that fails the whole build, not one page. Wrap calls that can legitimately come back empty in a try/catch.

Pricing, read from the Cosmic pricing page on November 10, 2026: Free is $0 with 1 Bucket, 2 team members and 1,000 Objects. Builder is $99/month with 2 Buckets, 3 team members and 5,000 Objects. Team is $299/month with 3 Buckets, 5 team members and 20,000 Objects. Business is $499/month with 5 Buckets, 10 team members and 50,000 Objects. Enterprise is custom. Additional team members are $29/user/month. Webhooks, localization, revision history and automatic backups are per-project add-ons at $99/month each, or $199/month for all four bundled.

Be deliberate about that last line if you are costing out an Astro project: the publish-triggers-rebuild workflow depends on webhooks, so price the add-on in from the start rather than discovering it later.

Good fit if: you want a hosted CMS with a typed SDK, an editor UI non-technical teammates can use without training, and every price published in full.

Think twice if: you need to self-host or keep content on your own infrastructure. Cosmic is SaaS only.

Sanity

Sanity is the most configurable option here. Content is queried with GROQ, its own query language, and the editing environment (Sanity Studio) is a React application you deploy and maintain yourself. If you have strong opinions about how your editing UI should behave, Sanity will let you build exactly that.

For Astro specifically, the tradeoff is front-loaded work. Standing up Studio, writing your schemas, and learning GROQ is a development project before you render your first page. Teams with frontend engineering capacity get real value from it. Teams who want to ship a content site this week usually do not.

Pricing, read from the Sanity pricing page on November 10, 2026: Free is $0 and includes up to 20 seats, 2 public datasets and 10,000 documents. Growth is $15 per seat/month, up to 50 seats, with 25,000 documents. Enterprise is custom.

The free tier is unusually generous on seats, which makes Sanity cheap to evaluate. Model your costs on documents and datasets rather than seats, since that is where the ceilings bite first.

Storyblok

Storyblok's distinguishing feature is its visual editor. Editors click a component on a live preview of the page and edit it in place. For a marketing site where layout changes constantly, that shortens the feedback loop a lot.

The component-based model shapes how you structure content, which suits page building well and application-style content less well. On Astro, the visual editor needs a preview route your editors can load, so budget setup time for it rather than assuming it works against a static build out of the box.

Pricing, read from the Storyblok pricing page on November 10, 2026: Starter is free with 1 space and up to 2 seats. Growth is $99/month. Growth Plus is $349/month. Premium and Elite are custom. Additional seats on Starter and Growth are $15/month each, and annual billing is discounted below the monthly list price.

The detail to catch is that Storyblok prices per space. If you run several distinct sites, that is several subscriptions, and the comparison against per-project competitors changes shape.

Strapi

Strapi is the open-source option. You can self-host it, read and modify the codebase, and keep your data on your own infrastructure. For teams with data residency or compliance requirements, that is a decisive advantage no SaaS platform can match.

The cost is operational. You own deployments, version upgrades, security patches, and the database. Major-version upgrades have historically needed real migration work. Strapi Cloud removes most of that burden and adds a bill.

Pricing, read on November 10, 2026: on the Strapi Cloud pricing page, Starter is $35 per project/month, Pro is $90 per project/month, and Business is $450 per project/month. On the Strapi CMS pricing page, the self-hosted Community edition is free and open source, with paid self-hosted editions quoted on the same page.

Note that Cloud is priced per project, so a multi-site Astro setup multiplies that figure rather than sharing it.

How to choose

You want to ship an Astro site quickly, with a typed SDK and an editor UI your marketing team can use: Cosmic.

You have frontend engineers and want to shape the editing experience yourself: Sanity.

Your editors need to click a live page and edit it in place: Storyblok.

You must self-host, own the data, or meet residency requirements: Strapi.

For most Astro projects the deciding factor is not raw API capability, since all four will serve content to a build step perfectly well. It is how much setup work sits between npm create astro@latest and an editor publishing without filing a ticket.

Build it

The fastest way to judge any of these is to put a real site on it. The Astro lesson in Cosmic Learn walks the whole path: SDK install, lean queries with .props(), static routes with getStaticPaths, and a Vercel deploy with the rebuild webhook wired up. The Astro CMS overview covers content modeling and the editor experience on one page, and the API documentation has the full query reference.

If you want the wider field rather than the Astro-specific one, we compare ten platforms in Best Headless CMS in 2026.

Start free with Cosmic, no credit card required. If you would rather talk through a migration or a multi-site setup first, book time with our CEO.

Best Headless CMS for Nuxt in 2026: 7 Options Compared

Tony Spiro — Tue, 10 Nov 2026 17:19:58 +0000

Nuxt gives you server routes, useAsyncData, Nitro caching, and hybrid rendering out of the box. The CMS you put behind it decides three things: how fast your editors can publish without filing a ticket, how much infrastructure your team ends up owning, and what the bill looks like when the second and third site show up.

This is a comparison of seven options that work well with Nuxt 3 and Nuxt 4. I fetched every vendor's pricing page on November 10, 2026 and linked each figure to the page it came from, with the date. Pricing moves. When you read this, check the links.

A note on what is here: a vendor only made the list if its current pricing page could be fetched and cited. No remembered numbers, no "approximately," no vendor quoted from an older version of this article.

Quick comparison

CMS	Hosting model	Content lives in	Best fit
Cosmic	Managed SaaS	Hosted API	Teams running several sites or brands who want editors publishing without engineering
Nuxt Content	Self-hosted, in your repo	Markdown/YAML/JSON files in git	Docs, blogs, and marketing sites where the authors are developers
Storyblok	Managed SaaS	Hosted API	Marketing teams who want visual, block-level page editing
Sanity	Managed SaaS	Hosted API	Teams who want a fully customizable editing environment and will build it
Strapi	Self-hosted or Strapi Cloud	Your own database	Teams who need the content layer inside their own infrastructure
Prismic	Managed SaaS	Hosted API	Small sites and single-repository projects with a tight budget
Directus	Self-hosted or Directus Cloud	Your own SQL database	Teams wrapping an existing database with an admin and API layer

1. Cosmic

Cosmic is a managed headless CMS. You model content in a dashboard, editors publish there, and Nuxt reads it over a REST API or the TypeScript SDK. There is nothing to deploy, patch, or scale on your side. Cosmic is a Y Combinator W19 company.

For Nuxt specifically, the fit is straightforward. Content comes back as plain JSON from an edge-cached API, so it drops into a Nitro server route or useAsyncData with no adapter layer in between. Image optimization and video delivery are handled on the CDN, so you are not wiring up a separate transform service for your <NuxtImg> sources.

Where Cosmic separates from the rest of this list is the multi-property case. If you run five brand sites, or a franchise network, or a set of client sites, you can keep a Bucket per brand while sharing content models and billing across them, instead of standing up a separate install or a separate space per site.

Pricing (cosmicjs.com/pricing, read November 10, 2026): Free at $0/month with 1 Bucket, 2 team members, and 1,000 Objects. Builder $99/month, Team $299/month, Business $499/month, and Enterprise at custom pricing. Additional users beyond a plan's included team members are $29/user/month. Per-project feature add-ons (Webhooks, Localization, Revision History, Automatic Backups) are $99/month each or $199/month for all four.

Cosmic charges per seat once you pass your plan's included team members, so price it on the real size of your editorial team rather than the base plan alone.

The editorial argument, from a real customer:

"Cosmic is: us never having to ask a developer to change anything on the backend of our website."
— Maximilian Wuhr, Co-Founder at FINN

Strengths: No infrastructure to run. Editors ship independently. Clean multi-site and multi-locale story. REST API, TypeScript SDK, and a CLI.

Trade-offs: It is a hosted service, so self-hosting is not an option. The free tier's 1,000 Objects is fine for a marketing site and tight for a large content archive.

Reading Cosmic content in Nuxt

Install the official SDK, @cosmicjs/sdk, then create a server route so your read key never reaches the browser:

// server/api/posts.get.ts
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
})

export default defineEventHandler(async () => {
  const { objects } = await cosmic.objects
    .find({ type: 'posts' })
    .props(['id', 'title', 'slug', 'metadata'])
    .depth(1)

  return objects
})

Then consume it in a page with Nuxt's own data layer:

<!-- pages/blog/index.vue -->
<script setup lang="ts">
const { data: posts } = await useAsyncData('posts', () => $fetch('/api/posts'))
</script>

<template>
  <ul>
    <li v-for="post in posts" :key="post.id">
      <NuxtLink :to="`/blog/${post.slug}`">{{ post.title }}</NuxtLink>
    </li>
  </ul>
</template>

That is the whole integration. No adapter package, no build step, no schema generation. Full method reference is in the Cosmic docs.

Running more than one Nuxt site? That is where a managed CMS stops being a convenience and starts being the thing that keeps your team off the critical path. Start free on Cosmic and model your first content type in a few minutes.

2. Nuxt Content

Nuxt Content is the first-party option, and for a certain kind of project it is the correct answer before you evaluate anything else. Content lives as Markdown, YAML, CSV, or JSON files inside your repository, and you query it with a MongoDB-like query builder backed by SQLite (content.nuxt.com, read November 10, 2026).

The feature that makes it distinctly Nuxt is MDC syntax: you use Vue components, with props and slots, directly inside Markdown files. Your content authors get a hero block or a callout component without you building a block renderer.

// content.config.ts
import { defineContentConfig, defineCollection } from '@nuxt/content'
import { z } from 'zod'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      source: 'blog/*.md',
      type: 'page',
      schema: z.object({
        tags: z.array(z.string()),
        image: z.string(),
        date: z.Date(),
      }),
    }),
  },
})

Collections give you schema validation and type-safety on frontmatter, with autocompletion in your Vue files. Querying is queryCollection('blog').all().

For non-developer editing, Nuxt Studio is the visual layer. Per content.nuxt.com (read November 10, 2026), Studio is described as a free and open-source visual interface for editing content in production, with live preview on the production site, visual editing of Markdown, YML, and JSON files, and publishing changes directly to your git provider.

Pricing: Nuxt Content is an open-source Nuxt module. Your cost is your hosting.

Strengths: Zero external service. Content versioned in git alongside code. Vue components inside Markdown. Type-safe queries.

Trade-offs: Content is coupled to deploys and to your repository. Editors need git as the system of record, which suits documentation sites and suits a 12-person marketing team considerably less. There is no hosted media pipeline, roles and permissions layer, or multi-brand content model to inherit.

3. Storyblok

Storyblok is a managed CMS built around a visual editor, where editors compose pages from reusable blocks and see the result rendered live. Its Vue and Nuxt support has been a focus for years, which is why it shows up in nearly every Nuxt CMS shortlist.

If your buyers are marketers who want to build landing pages without a developer, the block-based visual editing model is the main reason to pick it.

Pricing (storyblok.com/pricing, read November 10, 2026): a free Starter tier, Growth at $99/month (lower on annual billing), Growth Plus at $349/month, and Enterprise at custom pricing. Seats are limited per tier, with additional seats billed per seat on top of the plan price, so check the current seat count on the plan card against your editorial headcount.

Strengths: Strong visual page building. Long-standing Vue and Nuxt focus. Component-shaped content models that map cleanly to Vue components.

Trade-offs: The block model is opinionated. Content that is not page-shaped, like a product catalog or a structured data set, fits it less naturally.

4. Sanity

Sanity pairs a hosted content backend with Studio, an editing environment you configure in code and deploy yourself. If you want the authoring experience to be a first-class part of your codebase, that is the draw. It also means the editor UI is a project you own and maintain.

Pricing (sanity.io/pricing, read November 10, 2026): a Free tier at $0 with generous seat allowance and capped documents, datasets, and API requests. Growth is billed per seat at $15/seat/month, with document and dataset caps and paid add-ons for additional quota and support. Enterprise is custom.

Watch the add-on line items rather than the headline seat price. On the plan page read November 10, 2026, extra datasets and increased quota are separately priced and can dominate the bill well before seat count does.

Strengths: Highly customizable editing environment. Real-time collaboration. Strong structured content modeling.

Trade-offs: You are building and maintaining the Studio. Usage-based caps on documents, datasets, and API requests mean cost scales with what your site actually does, which takes modeling before you commit.

5. Strapi

Strapi is the default answer when the requirement is "the content layer runs in our infrastructure." It is a Node.js CMS with an admin panel, running against your own database. For a Nuxt team already deploying Node services, there is nothing unfamiliar about it.

Pricing, self-hosted (strapi.io/pricing-cms, read November 10, 2026): a free Community edition under the MIT license. Growth at $45/month including 3 users, with additional users at $15/user/month, an SSO add-on priced separately, and Enterprise at custom pricing.

Pricing, Strapi Cloud (strapi.io/pricing-cloud, read November 10, 2026): Starter at $35/project/month, Pro at $90/project/month, and Business at $450/project/month.

The per-project structure on Cloud is the number to model carefully if you run several sites. Five properties on Pro is five times $90/month, before seats.

Strengths: Open source and self-hostable. Your data in your database. Extensible via plugins.

Trade-offs: Self-hosting means you own upgrades, scaling, backups, and uptime. Cloud pricing is per project, which gets expensive across a portfolio of sites.

6. Prismic

Prismic is a managed CMS organized around a repository per project, with a page-builder style authoring experience. Its appeal is the price of entry for small projects.

Pricing (prismic.io/pricing, read November 10, 2026): Free at $0 with a single user, then Starter at $10/month, Small at $25/month, Medium at $150/month, and Platinum at $675/month, with Enterprise custom. Plans are priced per repository, and user counts and locale counts step up with each tier.

The per-repository structure is the thing to check. One site on Small is inexpensive. Eight sites on Small is eight subscriptions.

Strengths: Low entry price. Page-builder authoring that non-developers pick up quickly. Solid Nuxt community support.

Trade-offs: Per-repository pricing scales poorly across a portfolio. Locale allowances are tier-gated, which matters if you are international early.

7. Directus

Directus wraps an existing SQL database with an admin interface and an API, which makes it a strong pick when the data already exists and you want a content layer over it rather than a new content store.

Pricing (directus.com/pricing, read November 10, 2026): Core at $89/month billed yearly, or $99 monthly, including 3 user seats, 25 collections, and 5 flows. Additional seats are listed at $50/seat/month and additional collections at $100 per 25-pack. There is also an Open Innovation Grant: the page states that organizations under $5M in annual revenue with fewer than 50 employees qualify for fully permissive access at no software cost when self-hosted, with cloud hosting at $99/month.

One caveat worth flagging, because it affects budgeting. On the page as read on November 10, 2026, the Team tier is stated two different ways on the same page: the plan card shows $588/month billed yearly, or $698 monthly, while the FAQ further down states $499/month on an annual commitment ($5,988/year), or $599/month monthly. Both were live when I read it. Confirm the current figure with Directus before you plan around it.

Strengths: Works against your existing database schema. Self-hostable. Flows for automation. Granular access control on paid tiers.

Trade-offs: It is a data platform first and a publishing tool second, so the editorial experience needs more shaping for a marketing team. Seat and collection limits on Core are tight, and the next tier is a significant step up.

How to choose

Your authors are developers and the site is a blog or docs. Use Nuxt Content. It is first-party, free, and MDC is genuinely better than a block renderer you would build yourself.

You have non-technical editors and one site. Storyblok or Prismic. Both give editors a visual surface, and Prismic's entry tiers are cheap for a single repository.

You want the editing environment to be code you own. Sanity, with the understanding that Studio becomes a project on your roadmap.

Regulatory or infrastructure requirements say the content layer stays in-house. Strapi self-hosted, or Directus if you are putting a content layer over a database that already exists.

You run several sites, brands, or client properties and editors keep waiting on engineering. Cosmic. The per-property math is where this gets decided: per-project and per-repository pricing models compound fast across a portfolio, and running your own installs multiplies the upgrade and uptime work by the number of sites.

Frequently asked questions

Does Cosmic work with Nuxt 3 and Nuxt 4?
Yes. Cosmic is framework-agnostic. You call the REST API or the TypeScript SDK from a Nitro server route or inside useAsyncData, exactly as in the example above.

Does Cosmic offer GraphQL?
No. Cosmic provides a REST API, the TypeScript SDK (@cosmicjs/sdk), and a CLI. If a GraphQL layer is a hard requirement for your stack, that is a real consideration to weigh.

Can I preview drafts in Nuxt?
Yes. Fetch with a preview-enabled client in a server route guarded by a preview cookie or token, then render the draft on the real site.

How much does Cosmic cost for a small team?
Free at $0/month covers 1 Bucket, 2 team members, and 1,000 Objects. Builder is $99/month, Team is $299/month, Business is $499/month, and additional users beyond your plan's included team members are $29/user/month (cosmicjs.com/pricing, read November 10, 2026).

Start building

Pick the one that matches who edits your content and how many properties you run. Those two questions decide this more reliably than a feature matrix does.

If you are running Nuxt and you want editors publishing on their own schedule across every site you own, see Cosmic plans and start free. Free tier, no credit card.

Best Sanity Alternatives in 2026: 5 Compared

Tony Spiro — Tue, 10 Nov 2026 17:13:57 +0000

Sanity is one of the most capable headless CMSs available: a fully customizable editing app, real-time collaboration, and a flexible query language. Teams usually look for an alternative for one of four reasons: per-seat pricing as the content team grows, an editing interface that needs a developer for every change, GROQ as one more language to learn, or wanting visual page building out of the box.

This guide covers five alternatives. Every price and plan limit below was read directly from the vendor's own pricing page on November 10, 2026, and each one links to the page it came from. We make Cosmic, so weigh our take on it accordingly. Platforms are listed alphabetically.

Sanity's pricing, for reference

Sanity's Free plan includes 20 seats, 2 public datasets, and 10,000 documents. Growth is $15 per seat per month, so a 20-person team on Growth pays $300/month before any usage overages. Enterprise is priced on request. Source: sanity.io/pricing, read November 10, 2026.

Quick comparison

CMS	Free tier	Paid plans from	Source, read Nov 10 2026
Cosmic	$0: 1 Bucket, 2 team members, 1,000 Objects	$99/month (Builder)	cosmicjs.com/pricing
Hygraph	Hobby $0: 3 seats, 1,000 entries, 2 locales	From $199/month (Growth)	hygraph.com/pricing
Prismic	Free: 1 user, 4M API calls/month, unlimited documents	$10/month (Starter, per repository, paid annually)	prismic.io/pricing
Storyblok	Starter: free, 1 seat	$99/month (Growth, 5 seats)	storyblok.com/pricing
Strapi	No free tier listed on Strapi Cloud	Cloud from $35/project/month (Starter)	strapi.io/pricing-cloud
Sanity (incumbent)	Free: 20 seats, 2 public datasets, 10,000 documents	$15/seat/month (Growth)	sanity.io/pricing

What to check before switching

Portable Text. Sanity stores rich text as Portable Text, a JSON structure. Alternatives use a different format (HTML, Markdown, or their own JSON), so plan a conversion step and test how embedded objects and custom marks map over.

Customization you rely on. If your Studio has custom input components, document actions, or workflows, list them first. Hosted alternatives configured in a web interface trade that flexibility for not having to maintain an editor codebase.

References and queries. GROQ queries that join documents need rewriting against the new API. Check depth limits on references and how the new API returns nested content.

Real-time collaboration. Sanity's simultaneous editing is a genuine strength. Most alternatives offer drafts and versions with less real-time co-editing.

The alternatives

Cosmic

Versus Sanity: content models are built in the dashboard rather than in code, so editors and non-developers can add fields. Plans include a set number of team members rather than charging purely per seat, with additional members at $29 each per month.
Pricing: Free is $0 with 1 Bucket, 2 team members, and 1,000 Objects. Builder is $99/month, Team $299/month, Business $499/month, additional users $29/month. Source: cosmicjs.com/pricing, read November 10, 2026.
Watch for: less editor customization than Sanity Studio, no real-time co-editing on the same document, and a smaller community.

Hygraph

Versus Sanity: content federation. The Growth plan includes one remote source for unifying external APIs alongside your content, and Enterprise goes up to ten. Source: hygraph.com/pricing, read November 10, 2026.
Pricing: Hobby is free with 3 seats, 1,000 entries, 2 locales, and 500,000 API calls. Growth is from $199/month with 10 seats, 10,000 entries, and 3 locales. Enterprise is custom. Same source.
Watch for: the step from free to $199/month, and SSO sitting on Enterprise only.

Prismic

Versus Sanity: editors assemble pages from developer-defined slices in a Visual Page Builder, with Slice Machine on the developer side. Source: prismic.io/pricing, read November 10, 2026.
Pricing: Free includes 1 user, 4M API calls a month, and unlimited documents. Paid plans are per repository, paid annually: Starter $10/month (3 users), Small $25/month (7 users), Medium $150/month (25 users), Platinum $675/month (unlimited users). Same source.
Watch for: pricing is per repository, so several sites means several subscriptions. Locales are capped per plan (2 on Free, 8 on Platinum).

Storyblok

Versus Sanity: a visual editing workflow where marketers build pages from components.
Pricing: Starter is free with 1 seat. Growth is $99/month with 5 seats, Growth Plus $349/month with 15 seats. Source: storyblok.com/pricing, read November 10, 2026.
Watch for: seat limits per plan. Larger teams move to Growth Plus or a custom tier.

Strapi

Versus Sanity: open source and self-hosted, with content types built in an admin UI.
Pricing: Strapi Cloud starts at $35 per project per month (Starter), with Pro at $90 and Business at $450. The Cloud pricing page lists no free Cloud tier, and its FAQ covers migrating from the self-hosted Community and Enterprise editions. Source: strapi.io/pricing-cloud, read November 10, 2026.
Watch for: Cloud bills per project, so costs scale with the number of sites. Self-hosting means running the server, database, and upgrades.

How to choose

Your editors want to build pages visually: Storyblok or Prismic.
You need to federate content from external APIs: Hygraph.
You want open source with a UI-built schema: Strapi.
You want plan-based pricing with a set number of included seats: Cosmic.

Moving from Sanity to Cosmic

See the Sanity alternative overview for a side-by-side comparison.

Cosmic's Free plan is $0 with 1 Bucket, 2 team members, and 1,000 Objects, so you can model your Sanity schema and test an import before paying anything. See plans and start free.

Best Headless CMS to Replace WordPress in 2026

Tony Spiro — Wed, 04 Nov 2026 15:40:33 +0000

Teams leave WordPress for a headless CMS for familiar reasons: plugin updates and security patches, slow page builders, a theme that ties content to one site, and a frontend team that would rather work in Next.js, Astro, or Nuxt. The hard part is not picking a new CMS. It is moving years of posts, pages, media, and custom fields without breaking URLs or losing editors along the way.

This guide compares six headless platforms specifically as WordPress replacements. We make Cosmic, so weigh our take on it accordingly. Every price below links to the vendor page it was read from, and platforms are listed alphabetically.

Quick comparison

CMS	Best for teams coming from WordPress who...	Editor feel	Migration help	Paid plans from
Cosmic	...want a hosted CMS and someone to move the content	Structured forms, AI agents	Free hand migration on paid plans	$99/month (Builder) (source)
Payload	...want to self-host, like WordPress	Structured forms in your own app	Do it yourself	Free to self-host; Cloud prices no longer published (source)
Prismic	...build marketing pages from sections	Page Builder with slices	Import API	$10/month (Starter, annual) (source)
Sanity	...have developers to build a custom editor	Customizable Studio	Migration tooling for developers	$15/seat/month (Growth) (source)
Storyblok	...loved a visual page builder	Visual, drag-and-drop	Migration guides and partners	$99/month (Growth) (source)
Strapi	...want open source and self-hosting	Structured forms you host	Community plugins	Free to self-host; Cloud from $35/month (source)

What a WordPress migration involves

Content export. The WordPress REST API (/wp-json/wp/v2/posts, /pages, /media) gives you clean JSON, including posts behind custom post types if they are registered with show_in_rest. It is usually easier than the XML export.

Custom fields. Advanced Custom Fields (ACF) and similar plugins hold much of the real structure, on top of WordPress's own custom-fields post type support. Map each field group to a content type in the new CMS before importing anything.

Shortcodes and page builder markup. Content built with Elementor, Divi, or WPBakery stores layout as shortcodes or proprietary markup. That does not convert cleanly. Plan to rebuild those pages as components, and migrate only the posts that are plain content.

Media. Download every media attachment, upload it to the new CMS, and rewrite image URLs inside post bodies.

URLs and SEO. Keep slugs identical where you can, and set 301 redirects for anything that changes, including date-based permalinks, category archives, and /feed. Carry over SEO titles and descriptions from Yoast or Rank Math.

Editors. WordPress users are used to a single admin dashboard. Choose a CMS whose editor your team will actually accept, and give them a preview of drafts on the real site.

The options

Cosmic

As a WordPress replacement: hosted, so there is no server, plugin, or security patching to manage. Content types are built in the dashboard, which maps naturally from ACF field groups. AI agents can draft, edit, and translate content, and images are served through imgix.
Migration: on any paid plan, our team migrates your WordPress content for you at no extra cost. We model your content types, import posts, pages, and media, and check the result with you. You can also analyze your site to see what a migration would involve, or follow our step-by-step WordPress migration guide.
Pricing: Free is $0 with 1 Bucket, 2 team members, and 1,000 Objects. Builder is $99/month, Team $299/month, and Business $499/month. Each plan includes a set number of team members, and additional members are $29 each per month (Cosmic pricing).
Watch for: there is no drag-and-drop page builder, so pages built in Elementor or Divi become developer-built components. You also need a frontend; Cosmic does not render your site.

Payload

As a WordPress replacement: the most WordPress-like in spirit: open source, self-hosted, and fully under your control, with an admin panel inside your Next.js app.
Pricing: free to self-host. Payload's Cloud pricing page no longer publishes plan prices, and new Cloud project deployments are paused following Payload joining Figma (Payload Cloud pricing).
Watch for: you keep the operational work you were trying to leave behind (hosting, database, backups, upgrades).

Prismic

As a WordPress replacement: slices give editors a page-building experience closer to WordPress blocks, with developer control over each section.
Pricing: there is a free tier. Paid plans are priced per repository and billed annually: Starter $10/month, Small $25/month, Medium $150/month, and Platinum $675/month (Prismic pricing).
Watch for: blog-heavy sites with complex taxonomies fit less naturally than page-led marketing sites.

Sanity

As a WordPress replacement: the most customizable editing experience, with real-time collaboration and strong developer tooling for scripted imports.
Pricing: there is a free tier. Growth is $15 per seat per month, and Enterprise is custom priced (Sanity pricing).
Watch for: the Studio is configured in code, so editors depend on developers for changes, and rich text converts to Portable Text.

Storyblok

As a WordPress replacement: the closest to a WordPress page builder: editors drag components onto a page and see the result in place.
Pricing: Starter is free. Growth is $99/month and Growth Plus is $349/month, with additional seats at $15 each per month on those plans (Storyblok pricing).
Watch for: seat limits for larger editorial teams, and a component-first model that suits pages more than a large post archive.

Strapi

As a WordPress replacement: open source and self-hosted like WordPress, with content types built in an admin UI and a plugin marketplace.
Pricing: free to self-host. Strapi Cloud starts at $35 per project per month (Starter), with Pro at $90 and Business at $450 (Strapi Cloud pricing).
Watch for: self-hosting brings back server and security maintenance.

How to choose

Your editors live in a page builder: Storyblok, or Prismic for section-based pages.
You want to keep self-hosting, just headless: Strapi or Payload.
You have developers to build a tailored editor: Sanity.
You want to stop running servers and have the migration done for you: Cosmic.

If you want to see what your own WordPress site looks like as structured content, you can model it on the Cosmic free plan today, no credit card required.

Start free or book 15 minutes with our CEO to walk through your migration.

Originally published on the Cosmic blog.

Connect a Cosmic Agent to Google Sheets

Tony Spiro — Fri, 25 Sep 2026 15:28:20 +0000

Letting an agent write to a Google Sheet is a small capability with a surprisingly sharp setup. The auth is a service account, the API is public and well documented, and the create payload is three fields. The working version also calls a different Google API than the task description implies.

This is the setup end to end, written so you can follow it with your own Google account and your own Cosmic agent. If a step fails on you, the Troubleshooting section at the end covers what this path actually produces.

What you will have at the end

An agent that can:

Create a new spreadsheet in a location your team owns
Write multiple tabs into it in one pass, some tabular, some prose
Share it with a human reviewer
Read that spreadsheet back later, including whatever the human changed

That last item is what makes this worth wiring up. A one-way export is a file. A sheet the agent can re-read is a two-way surface between a run and a person.

You need a Google account that can create a service account and a Shared Drive, which in practice means Google Workspace rather than a personal Gmail account. You also need a Cosmic agent with the API request capability enabled.

Step 1: Set up the Google side

Four things, in this order, in the Google Cloud console.

1. Create a project, or pick an existing one. The API enablement and the service account below both happen inside this project.

2. Enable both APIs. Google Sheets API and Google Drive API. Both, because the call that actually creates the file is a Drive call.

3. Create a service account and download its JSON key. IAM and Admin, Service Accounts, Create Service Account, then Keys, Add Key, JSON. The file you get contains a client_email, a private_key, and the project identifiers. Treat it like a password. It is one.

4. Create a Shared Drive, then add the service account to it as a member. Google Drive, Shared drives, Create shared drive. Open Manage members, paste the service account's client_email, and grant it Content manager or Manager. Copy the Shared Drive ID out of the URL when you open the drive: it is the segment after /drive/folders/.

Step 2: Set up the Cosmic side

Three pieces, all of which live in your own Cosmic account.

Store the key as a secret. Ask your agent to save the service account JSON with manage_secrets. It gets stored encrypted and referenced by id, so it never appears in a prompt, a log, or a saved request body. This is the part people get wrong by pasting a private key into an agent instruction and hoping.

Save the Google calls as endpoints. Your agent can register saved API endpoints with default headers, so the Drive create, the Sheets batch update, the values write, and the read-back each become a named endpoint instead of a URL it has to reconstruct from memory every run. Reference the token in the default Authorization header as a secret placeholder rather than a literal.

Call them with api_request. From there the agent makes plain HTTPS calls to googleapis.com. There is no Cosmic-side Google integration doing anything clever underneath. Every call in the rest of this post is a call you could paste into curl.

One honest rough edge before you start. A service account authenticates by signing a JWT with RS256 and exchanging it at https://oauth2.googleapis.com/token for an access token that lasts an hour. The exchange is a plain HTTP POST your agent can make. The RS256 signing is not something an agent does with an HTTP tool alone. Two practical ways through it:

For following this walkthrough: mint a token once from your own machine and store that token as a secret. gcloud auth print-access-token --impersonate-service-account=YOUR_SERVICE_ACCOUNT_EMAIL does it in one line, as does a five-line Node script using google-auth-library. It expires in an hour, which is plenty to work through these steps.
For anything running on a schedule: put the signing in a small endpoint you own, have it return a fresh access token, and register that as one more saved endpoint the agent calls before the Google calls. Store its shared secret with manage_secrets the same way.

Request both scopes on every token, not just the one matching the call you think you are making:

https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive

Creation happens through Drive and writing happens through Sheets, so a token carrying both keeps a single token path across every call in this post. The broader scope is acceptable here because the identity holding it is a service account whose only access is the one Shared Drive you added it to.

Step 3: Create the file through the Drive API

Create the spreadsheet with a Drive call rather than sheets.spreadsheets.create, because a service account has no Drive storage quota of its own and therefore has to create the file inside a Shared Drive it has been added to as a member.

This is the call:

POST https://www.googleapis.com/drive/v3/files?supportsAllDrives=true&fields=id,webViewLink
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Weekly content report",
  "mimeType": "application/vnd.google-apps.spreadsheet",
  "parents": ["YOUR_SHARED_DRIVE_ID"]
}

The response gives you an id, which is the spreadsheet id every later Sheets call uses, and a webViewLink, which is the URL you hand to a human.

Three parts of that request carry weight. mimeType is what makes Drive mint a native Google Sheets file the Sheets API can address by id, rather than an opaque blob. parents assigns the file to the Shared Drive, so the Drive owns it and the service account is simply the thing that created it. supportsAllDrives=true is required on every Drive call that touches a file in a Shared Drive, including this one and the permissions call below.

Step 4: Write multiple tabs, then read the edits back

The first tab exists as soon as the file does. Every additional tab is two calls.

Add the sheet:

POST https://sheets.googleapis.com/v4/spreadsheets/<id>:batchUpdate
Authorization: Bearer <token>
Content-Type: application/json

{
  "requests": [
    { "addSheet": { "properties": { "title": "Code snippets" } } }
  ]
}

Then write values into it:

PUT https://sheets.googleapis.com/v4/spreadsheets/<id>/values/Code%20snippets!A1?valueInputOption=RAW
Authorization: Bearer <token>
Content-Type: application/json

{
  "values": [["Slug", "Status"], ["pricing", "live"]]
}

values is an array of rows, each row an array of cells. For narrative content rather than a table, split the prose on blank lines and make each paragraph a single-cell row, which puts one paragraph per row in column A.

Two practical notes. Sheet names with spaces have to be URL-encoded in the range, which is the Code%20snippets!A1 above. And when you are writing a dozen tabs, collect per-tab failures rather than aborting the whole job on the first bad one. A partial write that reports what it could not do beats losing eleven good tabs because the twelfth had an invalid name.

Share it with a human using the Drive permissions endpoint:

POST https://www.googleapis.com/drive/v3/files/<id>/permissions?supportsAllDrives=true&sendNotificationEmail=false
Authorization: Bearer <token>
Content-Type: application/json

{ "role": "writer", "type": "user", "emailAddress": "reviewer@yourcompany.com" }

Note supportsAllDrives=true again. It is required on this call for the same reason it was required on the create.

Then read the whole thing back, including whatever the human changed:

GET https://sheets.googleapis.com/v4/spreadsheets/<id>?includeGridData=true&fields=properties.title,sheets(properties.title,data.rowData.values.formattedValue)
Authorization: Bearer <token>

The narrow fields mask is the detail worth copying. Without it, includeGridData=true returns the entire grid including every formatting property on every cell, and the payload gets very large very fast on a sheet a human has been editing for a week. With the mask you get titles and formattedValue strings and nothing else. Normalize missing cells to an empty string on your side so whatever consumes this never has to null-check a cell.

That read-back closes the loop. Your agent wrote a draft, a person edited it in a tool they already had open with no new login and no new app, and the next run can see exactly what they left behind.

Three things this makes possible

Creating a file is a small capability with a large operational consequence attached. The destination has to be a Shared Drive the team owns, because the service account cannot own anything itself. That same constraint shows up in any content operation spanning many properties: one shared credential writing into one owned destination, rather than a separate identity and a separate orphaned folder per property.

1. A draft handoff a human can actually edit

An agent writes a draft into a sheet and shares it with a reviewer. The reviewer edits in place. A later run reads the spreadsheet back and picks up exactly what the human left behind. The read-back is what turns the sheet into a two-way surface instead of an export.

2. Structured exports that are not one flat table

Most real reports have more than one shape in them. A content audit has a table of pages with statuses, and it also has a pile of prose that does not fit in a grid. Multi-tab writing handles both in one pass: rows for the tabular tab, paragraph-per-row for the narrative tab. Collecting per-tab failures means a twelve-tab export that hits one bad tab name still delivers eleven tabs and tells you which one it dropped.

3. One credential across many properties

This is the use worth the most attention, and it is where the Shared Drive constraint stops being an annoyance and starts being the point.

A team running five to twenty distinct web properties has the same reporting job repeated per property: pull what changed, write it somewhere a human will actually read, keep the history. The naive version gives every property its own credential, its own destination folder, and its own half-remembered setup. Six months later nobody knows which service account owns which folder, and the person who configured property nine has left the company.

Creating through Drive with an explicit parents forces the better shape by default. The file is owned by a Shared Drive from the moment it exists. Access is governed by the Drive permissions the team already maintains, not by whoever happens to hold the key. Removing someone from the Drive removes them from every sheet the agent has ever written, across every property, without touching the agent or rotating anything. Adding a property means passing a different parent folder id on the request and provisioning no new identity at all.

The read-back compounds this. Once each sheet is a real addressable destination with a stable id, a run next week can read what a human changed this week and act on it, which holds across properties and across time rather than only within a single job. If your team is already running a dozen properties, the same consolidation argument applies one level up to the content layer itself: Workspaces puts every brand on one bill and one team.

Where this stops is worth naming plainly. The capability is that an agent can create, write to, share, and read a spreadsheet in a location the team owns. What gets built on top of it, whether per-property reporting, a review queue, or a staging area for bulk import, is a workflow decision you make. The setup guarantees the destination is owned by the team and reachable by the next run, and deliberately assumes nothing beyond that.

If you are wiring agents into systems that write, the same question applies to your content layer: what exactly is the credential allowed to do, and can you verify it rather than assume it. We wrote up the Cosmic answer in AI Agent Write Access: The 4 Real Controls You Get With Your CMS, including the two controls we do not ship yet. The broader picture of agents reading and writing structured content is on the Cosmic for AI teams page, and you can start on the Free plan, no credit card required, and give an agent its first saved endpoint in about ten minutes.

Troubleshooting

403 PERMISSION_DENIED on POST /v4/spreadsheets. The service account has no Drive storage of its own, so it cannot own the file that call is asking Google to create. Create the spreadsheet through the Drive API instead, into a Shared Drive the service account has been added to as a member, and pass supportsAllDrives=true.

A reviewer cannot open the sheet. The file inherits the permissions of the Shared Drive it was created in, so anyone who is not a member of that Drive has no access until you share the file explicitly. Grant it with the Drive permissions call in Step 4.

A write lands somewhere other than the tab you expected. The tab name in the range has to match a sheet that already exists, and a range with no tab name goes to the first sheet in the file. Add the tab with batchUpdate before writing to it, and URL-encode any spaces in the name.

Give your agent an inbox, then sign it up for Cosmic

Tony Spiro — Wed, 23 Sep 2026 14:55:04 +0000

Hand an agent a task like "build me a recipe blog" and it can scaffold the app, write the content, and ship it. Then it hits a wall. The CMS wants an account, the account wants an email address, and the verification code lands in a human's mail client. The run stops and waits for someone to paste six digits back.

This tutorial removes that stop. The agent provisions its own email inbox from AgentMail, passes that address to Cosmic agent signup as human_email, reads the claim code out of its own inbox, and submits it to verify. Working curl for every step, and no human in the loop.

Why it is worth wiring up: until that code is submitted, the new project sits in a restricted state with a deletion clock running on it. An agent that can read its own mail clears the gate itself and finishes the run holding a verified Cosmic project, a bucket, and the read and write keys to start writing content to it.

This is for developers building an agent (Cursor, Claude, a backend service) that needs a real content backend and can be handed an email address. You need a domain you can receive mail on, and nothing else.

The flow below was run against the production APIs on September 22, 2026. Signup returned an unclaimed project, the claim code arrived in the AgentMail message preview, and verify returned auth_type: verified with the restricted limits lifted.

What you get at the end

An AgentMail inbox at my-agent@agentmail.to, plus an API key the agent uses to read it
A Cosmic project and bucket in auth_type: verified
Bucket read_key and write_key, ready to pass to the SDK
An agent_key (agk_...) for later status checks

Between signup and verify the bucket sits in an unclaimed state, which you pass straight through rather than stop in. While unclaimed it allows 50 objects and 5 MB of media, AI generation is off, and the project is hard-deleted after 14 days if nobody claims it. Verifying lifts all of that.

Reference docs: Cosmic agent signup and the AgentMail quickstart.

Two different email addresses

This is the part that trips people up, so settle it before touching any code. Two addresses are in play and they do different jobs.

1. The AgentMail owner address. A real mailbox on a normal domain, something like you@yourdomain.com. You pass it as human_email on POST /v0/agent/sign-up, once, the first time this human creates an AgentMail account. AgentMail sends its own 6-digit OTP there.

2. The agent inbox. Created by that signup, in the form username@agentmail.to. This is the address you hand to Cosmic as human_email. Cosmic's claim email lands here, and the agent reads it with the AgentMail API key.

Using one address for both jobs fails. AgentMail rejects @agentmail.to as an owner address, and pointing Cosmic at your personal mailbox puts the claim code somewhere the agent cannot reach.

Create the AgentMail inbox

curl -X POST https://api.agentmail.to/v0/agent/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "you@yourdomain.com",
    "username": "my-agent",
    "source": "cursor"
  }'

The response carries api_key, inbox_id, and organization_id. With username: "my-agent" the inbox is my-agent@agentmail.to, and inbox_id is that same email address. Store the API key somewhere durable, because it is not shown again.

AgentMail also emails a 6-digit OTP to you@yourdomain.com. Submit it to unlock full permissions on the key:

curl -X POST https://api.agentmail.to/v0/agent/verify \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "otp_code": "123456" }'

The field here is otp_code. Keep that in mind, because Cosmic's verify endpoint names the same concept differently in a later step.

One observation from the September 22 run: the key returned by signup was already able to list inbox messages before this OTP was submitted. Do not build on that. AgentMail documents the key as limited until verification, so treat verifying as part of setup.

Errors you will actually hit

@agentmail.to as the owner address returns 403 with code: "forbidden" and the message Domain is forbidden. The owner address has to be an ordinary mailbox.
Disposable inbox domains return the same 403 and forbidden code. Use a real domain you control.
An address that already has an AgentMail account returns 403 with code: "already_exists" and the message User already exists, and no new API key comes back. Plus-aliases count as the same user, so you+agent@yourdomain.com collides with you@yourdomain.com. When the human already has an account, skip signup entirely: use their existing API key and create the mailbox with POST /v0/inboxes.

Branch on the code field rather than the message text. AgentMail documents those codes as stable and the prose as subject to change.

Sign up for Cosmic with the agent inbox

curl -X POST https://dapi.cosmicjs.com/v3/agents/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "my-agent@agentmail.to",
    "project_name": "Recipe Blog",
    "agent_id": "cursor"
  }'

Here human_email has to be the AgentMail inbox. The owner's personal address belongs only to the AgentMail signup in the previous step.

The response contains agent_key (prefixed agk_), access_token, auth_type: "unclaimed", the project, bucket.slug, bucket.read_key, bucket.write_key, a claim_url, and the limits object. Persist the agent_key and the bucket keys. If your sample code writes state to disk, keep those values out of anything you log.

Cosmic then emails the agent inbox. The subject reads An AI agent created a Cosmic project for you: "Recipe Blog", and the plain-text body contains the line Your one-time claim code is 123456 (expires in 15 minutes).

Two behaviors worth coding for:

Calling signup again with the same human_email and agent_id is idempotent. You get the same project back and a fresh code, which is the correct recovery path for an expired code.
If that email already belongs to a human Cosmic account, the response is 409 with code: "user_already_exists" and a claim_existing_url. Stop there and surface the URL. Retrying with a different email is the wrong move and leaves stray projects behind.

Read the claim code from the inbox

curl "https://api.agentmail.to/v0/inboxes/my-agent@agentmail.to/messages?subject=Cosmic&limit=20" \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

The inbox_id path segment is the email address itself. The subject query parameter does a substring match server side, so the agent can ask for the Cosmic message directly instead of scanning everything that arrives. Drop the filter if you would rather poll the whole list and match client side.

Messages come back newest first, each with message_id, subject, and an optional preview. In the live run the 6-digit code was sitting in preview. When the preview is empty or cut short, fetch the single message at GET /v0/inboxes/{inbox_id}/messages/{message_id} and read its text body.

Match on the labeled code rather than the first six digits on the page, because a timestamp or an ID can beat the real code to the regex:

const match = text.match(/claim code is\s*(\d{6})/i)
const code = match?.[1]

The code expires after 15 minutes. If your poll loop runs past that, call Cosmic signup again with the same email and agent_id and read the fresh code.

Verify the Cosmic project

curl -X POST https://dapi.cosmicjs.com/v3/agents/verify \
  -H "Authorization: Bearer $COSMIC_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Cosmic names this field code. AgentMail named the equivalent field otp_code back in step one. Sending the wrong key is an easy mistake when both calls sit in the same script.

A successful call returns Verified. Restricted-mode limits lifted. along with auth_type: "verified". Confirm it independently:

curl https://dapi.cosmicjs.com/v3/agents/status \
  -H "Authorization: Bearer $COSMIC_AGENT_KEY"

auth_type reads verified and limits comes back null. The bucket is now on standard free-plan limits, AI generation included.

Use the bucket

From here it is an ordinary Cosmic bucket, with one step that trips people up. A bucket created by agent signup is empty. It has no Object types in it, and an Object cannot exist without a type to live in. So the agent models the content first, then writes to it.

Pass the slug, read_key, and write_key from the signup response to createBucketClient. The write key is what authorizes both calls below:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG,
  readKey: process.env.COSMIC_READ_KEY,
  writeKey: process.env.COSMIC_WRITE_KEY
})

Create the Object type. Only title is required, and the slug defaults to the title converted to a slug. Declare the fields the agent intends to write in metafields:

await cosmic.objectTypes.insertOne({
  title: 'Posts',
  singular: 'Post',
  slug: 'posts',
  emoji: '📝',
  metafields: [
    {
      title: 'Content',
      key: 'content',
      type: 'markdown',
      required: false
    }
  ]
})

Now the object write succeeds, because type: 'posts' resolves to the type that exists and the content key in metadata matches a metafield on it:

await cosmic.objects.insertOne({
  type: 'posts',
  title: 'Hello from an agent',
  metadata: { content: 'Written by an agent that signed itself up.' }
})

Two things to handle if this runs unattended. Object type slugs are unique per bucket, so an agent that might run more than once should call cosmic.objectTypes.find() first and create the type only when it is missing. And any key you set in metadata has to exist as a metafield on the type, so adding a field later means a cosmic.objectTypes.updateOne() call before the write rather than a new key in the object payload. The Object types reference covers the full set of parameters, and the Metafields reference lists every field type available.

The agent signup docs cover the rest of the surface: refreshing access_token, handing the claim_url to a human when one is available, and the 402 with agent_unclaimed_limit that you hit if verification gets skipped and the agent keeps writing.

The whole point of this setup is that the claim code never has to pass through a person. An agent that can receive email can provision its own content backend, verify it, and start writing, in one uninterrupted run.

Ready to try it? Start free or read the agent API docs. If you are wiring agents into a larger content operation, grab time with our CEO.

Originally published on the Cosmic blog.

Moving a 1,700-page site to the Next.js 16 App Router without a sitemap hole

Tony Spiro — Mon, 21 Sep 2026 17:13:22 +0000

Most "we upgraded to Next.js 16" posts are version bumps with a changelog attached. This is not that. This is what it actually took to move cosmicjs.com, a 1,696-URL marketing and docs site backed by Cosmic, from the Pages Router to the App Router, and the five problems that cost real time.

None of them were in the migration guide. All five are things you will hit if your site is large, CMS-driven, and deployed on Vercel.

The shape of the site

Worth setting the scale, because every problem below is a function of it.

1,696 URLs in the sitemap
686 blog posts and 243 daily Rundown issues, all Objects in Cosmic
Comparison pages, solutions pages, templates, marketplace listings, integrations, and partners, also all CMS-driven
MDX docs, and a next-seo setup with <NextSeo> calls scattered across a few hundred view components

The migration ran as a coexistence first. The App Router and Pages Router happily share a repo, so we moved routes in batches and kept pages/ around for the stragglers. That part was uneventful. Then we cut over the rest, and the build stopped finishing.

Problem 1: the build hit Vercel's 45-minute cap

The first full App Router production deploy ran for 46 minutes and then died. Not a crash, not a type error. It hit the ceiling.

The cause was generateStaticParams. Under the Pages Router, getStaticPaths with fallback: 'blocking' had been quietly doing the right thing for years. When we ported the route files, every dynamic segment got a generateStaticParams that returned the full slug list, so the build tried to prerender roughly 1,700 pages, each one making its own Cosmic request, inside a 45-minute budget.

The fix is an environment variable and a guard in every path loader:

export const loadPaths: GetStaticPaths = async () => {
  if (process.env.SKIP_BUILD_STATIC_GENERATION === 'true') {
    return { paths: [], fallback: 'blocking' };
  }
  // ...fetch every slug from Cosmic
};

With SKIP_BUILD_STATIC_GENERATION=true set on Vercel, the build prerenders none of the CMS slug pages. Each one is generated on its first request and then cached, with export const revalidate = 60 on the route keeping it fresh. Build time drops from "does not finish" to a handful of minutes. The first visitor to a cold slug triggers the render and every visitor after that gets a cached page. We measured what that trade actually costs, further down.

This is the right trade for a content site. It is the wrong trade if you have a hard requirement that every page is warm the instant a deploy finishes.

Problem 2: skipping the prerender quietly broke the sitemap

Here is the part that would have been an SEO incident if we had shipped it without checking.

We generate sitemap.xml with next-sitemap in postbuild. next-sitemap works from the Next.js route manifest. It lists what the build produced. So the moment we stopped prerendering the CMS pages, next-sitemap stopped listing them. The sitemap would have gone from 1,696 URLs to 433, on a site where the blog is the top of the funnel.

Nothing would have errored. The deploy would have looked perfect.

The fix is additionalPaths. Rather than relying on the route manifest, we query Cosmic directly at postbuild time and inject every published slug:

const [posts, categories, tags, authors, comparisons, solutions] =
  await Promise.all([
    fetchAllObjects(bucket, 'blog-posts', 'slug,modified_at,metadata.last_updated'),
    fetchAllObjects(bucket, 'categories', 'slug,id'),
    // ...
  ]);

for (const post of posts) {
  const path = isRundownSlug(post.slug)
    ? `/rundown/${post.slug}`
    : `/blog/${post.slug}`;
  extraPaths.add(path);
  dates[path] = post.metadata?.last_updated || post.modified_at;
}

next-sitemap merges additionalPaths by loc, so this is safe whether or not the prerender ran. Turn SKIP_BUILD_STATIC_GENERATION off for a full build and you get no duplicates.

Two details that are easy to miss:

Paginated listing routes disappear too. /blog/page/2 through /blog/page/76 are prerendered pages, not CMS Objects, so they vanish along with everything else. We recompute them from the post count and the page size rather than hardcoding a number.

Turn off autoLastmod. Stamping today's date on all 1,696 URLs on every deploy is a signal crawlers learn to discount. We set autoLastmod: false and pull a real per-post lastmod from the Cosmic Object's modified_at, which means the dates in the sitemap now mean something.

We also added a loud failure. If SKIP_BUILD_STATIC_GENERATION is on and the Cosmic fetch returns nothing, the build logs an error instead of silently producing a short sitemap:

if (process.env.SKIP_BUILD_STATIC_GENERATION === 'true' && extraPaths.size === 0) {
  console.error(
    '[sitemap] SKIP_BUILD_STATIC_GENERATION is on but no Cosmic CMS paths were fetched.'
  );
}

A dry run injected 1,261 paths. The live sitemap now carries 1,263 CMS-driven URLs out of 1,696 total, which is the number that would have quietly disappeared.

Problem 3: Turbopack compiled forever in production

With the prerender skipped, the build still hung. Different place this time: "Creating an optimized production build" with no output and no error, until the cap.

Turbopack is the default bundler for next build in Next.js 16 and it is genuinely faster in development. On this repo, in Vercel's production build environment, the compile step never finished. Locally it was fine, which is the worst kind of bug.

We did not root-cause it. We shipped:

"build": "yarn generate-search-index && yarn check-types && next build --webpack"

Webpack finished in minutes. next dev still uses Turbopack, so we keep the fast feedback loop and give up nothing except a slightly slower CI build. If your production build hangs at compile with no diagnostic output, try --webpack before you spend a day bisecting your own code.

Problem 4: `draftMode()` turned every blog post dynamic, then 500'd

Cosmic's live preview needs the page to fetch draft content instead of published content. Under the Pages Router this came through context.preview. The obvious App Router port is draftMode():

// This is the version that broke things
export async function pageLoaderArgs(params) {
  const draft = await draftMode();
  const preview = draft.isEnabled || Boolean((await cookies()).get(COSMIC_PREVIEW_COOKIE));
  return { params, preview, draftMode: preview /* ... */ };
}

Calling draftMode() or cookies() inside a route opts that route out of static rendering entirely. Every blog post became dynamic, ISR stopped applying, and several slugs started returning 500s in production because the loader was now running in a request context it did not expect.

The fix is to stop asking the canonical route whether it is in preview. Preview gets its own route:

// app/preview/[...path]/page.tsx
export const dynamic = 'force-dynamic';

That catch-all resolves blog, rundown, partners, customers, templates, and marketplace slugs to the same loaders and views the canonical routes use, but runs them with preview: true and returns robots: { index: false, follow: false }. The canonical /blog/[slug] route went back to a plain synchronous argument builder with no cookies() call anywhere in its tree, which made it statically renderable again.

The general rule: keep dynamic APIs out of the routes you want cached. If a feature needs per-request state, give it a separate route rather than making your entire content tree dynamic to serve a handful of editor sessions.

Problem 5: `next-seo` went silent and took 400 page titles with it

next-seo is built on next/head, which does nothing in the App Router. Not an error, not a warning. The component renders null and your <title> quietly becomes the layout default.

We had <NextSeo> calls in a few hundred view components. Deleting them all as step one of the migration would have meant a very large diff with no way to verify anything in between. Instead we aliased the package to a no-op shim:

// src/lib/next-seo-app.tsx
function noop(_props?: any) {
  return null;
}

export const NextSeo = noop;
export const ArticleJsonLd = noop;
// ...every other export

Aliased in both next.config.mjs (turbopack.resolveAlias and the webpack resolve.alias) and tsconfig.json paths. Everything compiled, nothing crashed, and every page shipped the default title.

Then we rebuilt metadata properly with generateMetadata. The pattern that scaled across 100-plus route files is a single helper that runs the page's existing data loader, picks the SEO fields out of the result, and falls back safely:

export async function metadataFromLoader(loadPage, ctx, pick = defaultSeoPick) {
  const params = flattenParams(ctx.params ? await ctx.params : {});
  const path = fillPath(ctx.path, params);
  try {
    const result = await loadPage(loaderArgs(params, ctx.preview));
    if (result?.notFound || result?.redirect) return {};
    const picked = pick(result?.props ?? {}, params);
    return pageMetadata({
      title: picked.title || titleFromPath(path),
      description: picked.description || LAYOUT_DEFAULT_DESCRIPTION,
      image: picked.image,
      path: picked.path || path,
    });
  } catch (error) {
    console.error(`generateMetadata failed for ${path}:`, error);
    return pageMetadata({ title: titleFromPath(path), description: LAYOUT_DEFAULT_DESCRIPTION, path });
  }
}

Route files become three lines, with a per-route pick function for the shapes that differ:

export async function generateMetadata({ params }) {
  return metadataFromLoader(loadPage, { params, path: '/blog/[slug]' }, articleSeoPick);
}

The try/catch matters more than it looks. A metadata function that throws takes the whole page down. Falling back to a title derived from the path means a bad CMS field costs you a weak title, not a 500.

JSON-LD needed the same treatment. next-seo's ArticleJsonLd was now a no-op, and a 'use client' component that injects a script tag is not reliably visible to crawlers. We render it from the server component instead:

<JsonLd id="ld-article" data={articleJsonLd(props, `/blog/${slug}`)} />

The thing that actually de-risked this

We wrote a script that crawls every URL in the sitemap and records status code, <title>, meta description, og:title, og:description, og:image, canonical, and JSON-LD block count. Then we ran it three times: against production before the merge, against the Vercel preview, and against production after the deploy.

Diffing those three files is what caught the compare pages falling back to a generic Compare | Cosmic title instead of Contentful vs Cosmic. It is what confirmed the four slugs that had been 500ing were fixed. It is what proved the sitemap still had all 1,696 URLs.

It is about 40 lines of curl and a parser. No Lighthouse run and no amount of clicking around the homepage would have found any of it, because every one of those problems lived on CMS slugs the homepage never links to.

What it actually bought us

Numbers, because "it feels faster" is not a result. These come from the Vercel API across every production deployment of this project.

Window	Successful builds	Median	Mean	Range
Pages Router, Jul 20 to Sep 18	85	6.4 min	6.0 min	2.2 to 11.7 min
App Router, Sep 19 onward	6	1.9 min	2.0 min	1.5 to 3.3 min

Roughly a 70% cut in median build time. The window between those two rows is its own data point: four consecutive production builds at 27.1, 41.3, 44.8, and 46.2 minutes, every one of them cancelled or errored.

Read that table carefully before quoting it. The Pages Router distribution is bimodal, clustering at 2 to 3 minutes and again at 6 to 8 minutes, which is almost certainly build cache hits against misses, so the median is the honest figure and the mean is not. The App Router sample is six builds over two days. And most of the gain comes from the ISR trade in Problem 1 rather than from the App Router itself. "Next.js 16 made our builds faster" would be the wrong conclusion to draw.

The sitemap held. 1,696 URLs live, 1,263 of them CMS-driven. That second number is what additionalPaths carries and what would otherwise have disappeared.

Runtime did not change, and we are not going to pretend it did. Vercel keeps old deployments reachable at their unique URLs, so we measured the last Pages Router production deploy against current production on the same four routes. TTFB came back at 78 to 116 ms on the new build and 72 to 260 ms on the old. That is noise. Both serve CDN-cached HTML, so there was never a mechanism for the App Router to make it faster. Anyone promising you a speed win from this migration is selling something.

The ISR trade turned out to be free. The stated risk in Problem 1 was that the first visitor to a cold slug pays for the render. We pulled two rarely-visited Rundown posts and got x-vercel-cache: HIT and STALE at 82 to 134 ms. Stale-while-revalidate serves the cached copy and regenerates behind it, so in practice nobody waits.

What we cannot show yet is the measurement that matters most: Search Console impressions, clicks, and coverage before against after. That needs a few weeks of post-deploy data. If the sitemap work did its job, the correct result there is that nothing happens at all.

What to take from this

If you are moving a large CMS-backed site to the App Router:

Budget your build. Count how many pages generateStaticParams will prerender and multiply by your CMS round-trip. If that number approaches your platform's build cap, skip the prerender and lean on ISR.
Your sitemap comes from the route manifest, not from reality. The moment you stop prerendering, check what next-sitemap actually emitted. Query your CMS for additionalPaths and fail the build loudly if it comes back empty.
If the production build hangs at compile, try --webpack. Keep Turbopack for next dev.
Keep cookies() and draftMode() out of cacheable routes. Preview belongs on its own force-dynamic route.
Assume next-seo is doing nothing. Alias it to a no-op so you can migrate incrementally, then verify with a crawl rather than a spot check.
Diff the crawl, not the vibes. Before, preview, after.

The site is live on Next.js 16 with the App Router, builds in minutes, and did not lose a URL. The content still lives in Cosmic, which is the part that made the sitemap fix possible: when your content model is queryable over an API, "list every URL this site should have" is a question you can answer at build time, independent of whatever your framework decided to prerender.

If you want to see the setup, the Cosmic Next.js docs cover the SDK patterns used here, and live preview is the feature behind the preview route.

Cosmic is an AI-powered headless CMS with a REST API, TypeScript SDK, and AI agents. Start free, no credit card required.

Automating Editorial Triage: Routing Drafts Across 13 Properties with Cosmic and TypeSafe

Tony Spiro — Mon, 21 Sep 2026 15:09:31 +0000

Draft-only publishing is the right default for any editorial team large enough that no single person sees everything. Nothing reaches the public until an editor approves it. The policy is easy to adopt, and it creates a new problem on day one: every draft now needs a person, and people read in the order things arrive rather than the order that matters.

Drafts can arrive from everywhere. Staff writers, section editors, freelancers filing against a brief, contributors who write for you twice a year, syndicated copy, and increasingly AI tools drafting alongside the team. The volume problem is the same whatever the source, and it shows up long before anyone adopts an agent.

For one team running multiple web properties, that queue stops being readable within a week. Our content governance at scale piece argued the policy. This one builds the mechanism that makes the policy survive volume.

The approach: Cosmic holds the content, the draft state and the roles. A classification model decides which drafts a human actually has to open, and in what order. Below is the architecture, working code against both TypeScript SDKs, and the accuracy we measured on a real corpus, including the parts that did not work.

What Jev does, and what it does not do

TypeSafe ships a model called Jev that answers typed questions about a block of text. You send content as state along with a map of questions, and you get structured answers back. There are three question types, documented on their API reference (read September 20, 2026):

Noul returns the probability that a yes/no question is yes, as a number from 0 to 1.
Choice picks one option from a set you define, and returns the full probability distribution plus a confidence value.
Score rates content against an ordered rubric you define, from two to ten levels, and also returns confidence.

Jev generates no prose and writes no code. It classifies and scores. That constraint is what makes it useful here, because editorial triage is mostly a classification job: decide what each draft is, then decide who needs to read it.

The architecture

A draft is created in Cosmic by a staff writer, a freelancer filing against a brief, an occasional contributor, a syndication feed, or an agent. The pipeline does not care which.
A webhook fires to your route handler.
The handler sends the draft body to Jev with every question attached to a single request.
Confidence decides what happens next: high-confidence answers write straight back to the object, low-confidence answers route to a human.
The editor opens a queue that is already sorted, categorised and flagged.

The draft never publishes itself. Everything below only decides who looks at it and when.

Step 1: write the questions, and take criteria seriously

This is the part that decides whether the whole thing works. Every question type accepts an optional or required criteria field, and the quality of your criteria matters more than the wording of your instructions.

Here is the question set we ran, targeting a fictional media group with thirteen consumer titles:

{
  "state": "<the draft body>",
  "model": "jev-latest",
  "questions": {
    "property": {
      "type": "choice",
      "instructions": "Which of our titles should publish this draft?",
      "criteria": {
        "switchback": "Cycling: road, gravel, commuting, bike gear and maintenance",
        "field_and_forge": "Outdoor gear: hiking, camping, trail running, packs and footwear",
        "the_marrow": "Food: recipes, technique, restaurants, ingredient deep dives",
        "marrow_dispatch": "The Marrow's newsletter: short, single-subject, first-person food writing",
        "ledger_lane": "Personal finance: saving, borrowing, tax, consumer money decisions"
      }
    },
    "voice_fit": {
      "type": "score",
      "instructions": "Rate how well this matches our editorial voice.",
      "criteria": [
        "Promotional or hyped. Superlatives without evidence, marketing register, reads like copy written to sell.",
        "Flat or generic. Accurate but characterless, could have come from any publication.",
        "Plain, specific and first-hand. Concrete detail, measured claims, an identifiable point of view."
      ]
    },
    "unverified_claim": {
      "type": "noul",
      "instructions": "Does this draft state a factual claim without attributing it to a source?",
      "criteria": {
        "true": "Contains a statistic, price, comparative claim or third-party assertion with no named source.",
        "false": "Every factual claim is attributed, or the piece is explicitly first-hand or opinion."
      }
    },
    "content_type": {
      "type": "choice",
      "instructions": "What kind of piece is this?",
      "criteria": {
        "news_report": "Reports something that happened, with dates, named sources or quotes.",
        "how_to_guide": "Instructional. Steps, technique or maintenance the reader is meant to follow.",
        "product_review": "Assesses named products against criteria and reaches a verdict.",
        "opinion_column": "Argues a position in an identifiable writer's voice.",
        "roundup": "A list of products, places or picks grouped by a theme."
      }
    },
    "undisclosed_promotion": {
      "type": "noul",
      "instructions": "Does this draft promote a product, brand or sponsor without disclosing the relationship?",
      "criteria": {
        "true": "Promotional intent with no visible disclosure of sponsorship, gifting or affiliate links.",
        "false": "Either no promotional intent, or the relationship is disclosed in the draft."
      }
    },
    "structural_completeness": {
      "type": "score",
      "instructions": "Rate how complete this draft is as a finished piece.",
      "criteria": [
        "Truncated or fragmentary. Ends mid-thought, or whole sections are missing.",
        "Drafted but unfinished. Complete thoughts, with visible gaps or placeholders.",
        "Complete. An opening, a body and an ending that lands."
      ]
    }
  }
}

Note the shape, because it is easy to get wrong. questions is a map keyed by ids you choose, and your answers come back under those same keys. Choice criteria is a map of option to rubric description. Score criteria is an ordered array of level descriptions.

The single most useful thing we learned: rubrics transformed the score question. Running voice fit with instructions alone, the model returned values of 1.64, 1.58 and 1.95 on a three-level scale, at confidence between 0.37 and 0.45. Those numbers are unusable, and we were ready to drop the question. Adding a described level for every step, exactly as written above, moved the same question to correct answers at confidence 0.94 and above. Same model, same task, same inputs.

If a question is behaving badly, write better criteria before you conclude the model cannot do the job.

Step 2: one call, every question

TypeSafe's speculative fan-out pattern documents that questions in a request are evaluated in parallel, so adding more of them does not typically add latency. Combined with output tokens being free on Jev, asking six questions about a draft costs close to what asking one costs.

That changes how you design the question set. Ask everything you might want, including questions that only matter sometimes, and ignore the irrelevant answers in code.

Here is the handler. Both SDKs are TypeScript, so this is one file:

import { createBucketClient } from '@cosmicjs/sdk';
import { QUESTIONS } from './questions'; // the question map from Step 1

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
  writeKey: process.env.COSMIC_WRITE_KEY!,
});

const TYPESAFE_URL = 'https://api.typesafe.ai/v1/systemone';

async function classify(state: string, questions: object) {
  const res = await fetch(TYPESAFE_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ state, model: 'jev-latest', questions }),
  });

  if (!res.ok) throw new Error(`TypeSafe ${res.status}`);
  return res.json();
}

export async function POST(request: Request) {
  const payload = await request.json();
  const objectId = payload.data?.id;

  const { object } = await cosmic.objects
    .findOne({ id: objectId })
    .props('id,title,slug,metadata');

  const result = await classify(buildState(object), QUESTIONS);
  return Response.json(await writeBack(object, result.answers));
}

// Jev accepts 64k tokens per request across state and all questions,
// and 32k for state plus the longest single question. Long-form bodies
// need trimming before they go in.
function buildState(object) {
  return [
    `TITLE: ${object.title}`,
    object.metadata.markdown_content.slice(0, 40000),
  ].join('\n\n');
}

A response comes back keyed by your question ids, with a usage object carrying input_tokens and output_tokens. TypeSafe also publishes client SDKs that handle retries automatically with their default retry policy. If you call the HTTP API with raw fetch as above, add your own backoff for the documented 429 rate limit responses.

Step 3: gate on confidence

This is where classification becomes a workflow. Choice and Score answers carry a confidence value derived from the probability distribution. Above your threshold, act automatically. Below it, hand the draft to a person.

const GATES = {
  property: 0.80,
  content_type: 0.60,
  unverified_claim: 0.80,
};

function route(answers) {
  const needsHuman: string[] = [];

  if (answers.property.confidence < GATES.property) {
    needsHuman.push(
      `Property unclear: ${Object.entries(answers.property.probabilities)
        .filter(([, p]) => p > 0.1)
        .map(([k, p]) => `${k} ${p}`)
        .join(', ')}`
    );
  }

  if (answers.content_type.confidence < GATES.content_type) {
    needsHuman.push(`Content type unclear: ${answers.content_type.choice}`);
  }

  if (answers.unverified_claim.noul >= GATES.unverified_claim) {
    needsHuman.push('Possible unsourced factual claim');
  }

  return { needsHuman, property: answers.property.choice };
}

The flagged reasons matter as much as the flag. An editor who sees "cycling 0.78, outdoor gear 0.21" knows exactly what decision is being asked of them, and can make it in two seconds.

Step 4: write the answer back

The result lands on the Cosmic object, so the queue an editor opens is already organised:

async function writeBack(object, answers) {
  const { needsHuman, property } = route(answers);

  await cosmic.objects.updateOne(object.id, {
    metadata: {
      property,
      voice_score: answers.voice_fit.score,
      triage_status: needsHuman.length ? 'needs_review' : 'auto_filed',
      triage_notes: needsHuman.join(' | '),
    },
  });

  return { needsHuman, property };
}

The object stays in draft. Nothing here publishes anything, and the human approval step is untouched.

What we measured

We built a corpus of 18 drafts across 13 fictional properties and five content types, with defects deliberately seeded on known labels so there was something real to score against. Two of the thirteen properties were newsletter microsites that overlap their parent titles, included specifically to make routing harder. Every draft went through one request carrying the full question set: 18 calls, 102 individual judgments, all HTTP 200.

Property routing: 18 of 18 correct. Twelve came back at confidence 0.95 or above, including both newsletter traps. The finance newsletter resolved to the newsletter over its parent title at 0.84 against 0.16. The food newsletter resolved at 0.98 against 0.02.

With the gate at 0.80, 16 of 18 auto-filed with zero incorrect auto-files, and 2 routed to a human. Both of those were genuinely ambiguous:

A fell-running shoe review: cycling title 0.78, outdoor title 0.21.
A festival food guide: events title 0.46, food title 0.39, food newsletter 0.15, confidence 0.41.

Those are exactly the two a human should see.

Voice fit: 18 of 18 correct, confidence 0.71 or above throughout. An affiliate-spam draft scored 0.00 at confidence 1.00. This is the question that was unusable before rubrics.

Content type: 13 of 18 correct, and every single disagreement arrived below 0.55 confidence. Set that gate at 0.60 and everything passing the gate was right. As a demonstration of confidence gating, this is cleaner than the routing result, because the model reliably flagged its own errors.

Undisclosed promotion: 12 of 12. A sponsored hotel review that discloses the sponsorship in its first line scored 0.05. An undisclosed affiliate roundup scored 0.94. We dropped this question from the last batch to keep payloads small, so the sample is 12 drafts rather than 18.

Where it was weak

Publishing only the wins would make this useless to you, so here are the three limitations we hit.

Confidence catches genre ambiguity and misses topical overlap. We built a batch specifically to break routing, using drafts that legitimately belong to two titles. It hedged on two and answered confidently on four where a second title had a real claim. An electric-vehicle charger payback analysis, which is half personal finance, returned its energy title at confidence 1.00 with the finance title at exactly 0. Do not use these probabilities to find cross-posting candidates. They answer "which one" and not "how many."

The unsourced-claim question tracks claim density more than sourcing. Across twelve clean drafts it ranged from 0.11 to 0.73. A pure-opinion column containing no factual claims at all scored 0.11, while a fully sourced council report scored 0.59. Separation still held: every seeded-defect draft landed between 0.88 and 0.99, every clean draft stayed at or below 0.73, and a 0.80 gate was correct on all 18. Gate on the separation you observe in your own corpus rather than trusting the absolute value.

Structural completeness was the least reliable. It caught a deliberately truncated guide at 0.03 with confidence 0.97, and it returned confidence 0.00 twice on drafts that are complete and simply end on a short line. Two zero-confidence outputs in 18 is worth knowing before you gate anything important on it.

TypeSafe publishes a jaggedness page for the model, which is an honest signal from a vendor and a reminder to measure on your own content before trusting any question in production.

What it costs

Jev is priced at $0.042 per million input tokens with output tokens free (TypeSafe models, read September 20, 2026). Our run consumed 22,416 input tokens across 18 calls and returned 4,656 output tokens that were not billed.

That is $0.00094 for the whole corpus, roughly $0.000052 per draft, or about 19,000 classified drafts per dollar. Cost is not the constraint on this design. Treat these figures as an illustration from one small run rather than a benchmark.

Running it without webhooks

Webhooks on Cosmic are a $99/month per-project add-on, or $199/month bundled with Localization, Revision History and Automatic Backups (Cosmic pricing, read September 20, 2026). You do not need them to try this.

Poll for untriaged drafts on a schedule instead:

const { objects } = await cosmic.objects
  .find({ type: 'articles', status: 'draft', 'metadata.triage_status': '' })
  .props('id,title,metadata')
  .limit(25);

for (const object of objects) {
  const result = await classify(buildState(object), QUESTIONS);
  await writeBack(object, result.answers);
}

Same classification, same write-back, no add-on required. Move to webhooks when the latency starts to bother you.

Where this leaves the review queue

The editor still approves everything. What changed is what they open: a queue where most drafts are already filed against the right property, scored for voice, and where the handful carrying a possible unsourced claim are at the top with the reason attached.

For a team running five to twenty properties, that difference decides whether draft-only publishing is a policy you can hold or one you quietly abandon.

Cosmic gives you the content model, the draft state, the roles and the API to build this. Start free, read the API and SDK docs, or book a walkthrough if you want to talk through the architecture for your own properties.

Teams running this across many properties at once are who the Cosmic Workspace plans are built for: several projects, one team, one bill.

If you are connecting AI tools to your content more broadly, the Cosmic MCP server is the other half of this story.

Originally published on the Cosmic blog.

Content Durability: How to Get Everything Out of Your CMS

Tony Spiro — Mon, 31 Aug 2026 15:09:38 +0000

Originally published on the Cosmic blog.

Every CMS decision is a bet on where your content will live for the next five years. The part teams skip when they make that bet is the exit: what happens if you need to move, and what shape the content arrives in when it gets there.

Content durability is the property that makes that question boring. Your content is durable when you can retrieve all of it, in a structured format, on demand, without filing a support ticket, and rebuild it somewhere else. Most teams assume they have this and find out they do not on the week they need it.

Backup, revision history, and export solve three different failures

These get conflated constantly, and the confusion is expensive because each one covers a failure the others do not.

Backup is a point-in-time restore back into the same system. It covers "we broke production at 3pm."
Revision history is a per-object change log inside the system. It covers "someone rewrote the pricing paragraph and we want the old one."
Export is a complete, structured copy that leaves the system. It covers "we are migrating," "legal needs an archive," and "the vendor changed terms."

A backup does not help you leave. An export does not help you recover a paragraph from yesterday. If you only have one of the three, you have a gap, and it is usually the export.

What "structured" actually has to mean

An export is only useful if the thing you get back can be rebuilt without a human reading it. Six properties matter:

JSON, not rendered pages. Page HTML is a lossy projection of your content. Field boundaries, types, and relationships are gone the moment it renders.
The schema, not just the values. Field keys, types, select options, required rules, and validation are what let you recreate the model somewhere else.
Stable IDs. If identifiers are regenerated on export, every relationship in your content becomes a guess.
Relationships as references. A post that points at an author and three tags should export those pointers, not flatten them into strings.
Media you can actually retrieve. File references are worthless without reachable originals.
Everything, not just what is live. Drafts, scheduled items, and locale variants are content too.

Path 1: the dashboard export

Every Cosmic Bucket can export its content as a JSON file from Bucket > Settings > Import / Export. The export includes Object types, Objects, Media, and folders, which covers the schema and the values in one file. It does not include team members, Object revisions, or backups. That scope is documented on the Buckets documentation page, and the same screen imports a JSON file back into a Bucket, which is how you clone an environment or seed a fresh one.

This is the fastest way to answer the durability question for yourself right now. Run the export, open the file, and check that the six properties above are present. That takes about five minutes and tells you more than any vendor claim.

Path 2: the API on a schedule

A manual export is a snapshot. A scheduled export is an insurance policy. The REST API and the TypeScript SDK let you write the same data to your own storage on a cron, so a current copy always lives somewhere you control.

import { createBucketClient } from '@cosmicjs/sdk';
import { writeFile } from 'node:fs/promises';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
});

async function exportType(type: string) {
  const all = [];
  const pageSize = 100;
  let skip = 0;

  while (true) {
    const { objects } = await cosmic.objects
      .find({ type })
      .props('id,slug,title,type,status,locale,metadata,created_at,modified_at')
      .status('any')
      .limit(pageSize)
      .skip(skip);

    if (!objects?.length) break;
    all.push(...objects);
    if (objects.length < pageSize) break;
    skip += pageSize;
  }

  await writeFile(`./export/${type}.json`, JSON.stringify(all, null, 2));
  return all.length;
}

const count = await exportType('blog-posts');
console.log(`Exported ${count} objects`);

Two details make the difference between a real export and a partial one. status('any') includes drafts, which a default read leaves out. Requesting metadata explicitly keeps every custom field rather than the summary props.

Commit the output to a private repository or push it to object storage, and you get version history on your content for free. Once your object counts run into the thousands, switch the loop to cursor pagination with after, which the API supports and which is more efficient than paging with large skip offsets.

A read key is enough for this job. An export process never needs write access, and keeping the two keys separate is the cheapest safety measure available.

Path 3: the CLI

For scripting against a terminal rather than an application, the Cosmic CLI reads objects, types, and media and can emit JSON for piping into other tools. It is the shortest route to a one-off dump inside a shell script or a CI job, without standing up a Node project first.

The part people forget: media

Content exports usually succeed. Media migrations are where projects stall, because a JSON file full of CDN URLs is not the same thing as owning the files.

Build the download step into your export job: walk the media references, fetch each original, and store it alongside the JSON. Do that once and your archive is genuinely self-contained.

Two behaviors are worth knowing while you plan this. Replacing a media file keeps the same URL and id, so every reference in your content stays valid after the swap. Deleting media purges it from the CDN and does not update the references pointing at it, so a delete can leave broken links behind in objects you have forgotten about. Audit media before a migration, not after.

If you are relying on transformations rather than storing multiple renditions, the derivative sizes are generated at request time from the original. Keeping the originals is what preserves your ability to regenerate everything later.

Backups and revisions, since export does not cover them

Because the JSON export explicitly excludes revisions and backups, treat those as separate controls, and budget for them. Automatic Backups and Revision History are both add-ons on Cosmic, $99/month each, or $199/month for the bundle that also covers Webhooks and Localization. With Automatic Backups enabled, a backup runs daily, and you can take a snapshot on demand, download it, or restore from it. Revision history is tracked per object.

The practical setup for most teams: backups on for recovery, revisions for editorial mistakes, and a scheduled JSON export for durability. Three controls, three failures, no overlap.

Run the drill once a quarter

An export you have never restored is a hypothesis. Turn it into a fact:

Run a full export, dashboard or API, whichever your process uses.
Download every referenced media original into the same archive.
Import the JSON into a clean Bucket, or stand up a local database from it.
Point a staging build at the restored data and load ten pages, including one with relationships and one with media.
Write down what broke and how long it took.

The acceptance test is simple: could a developer who has never seen your setup rebuild a working staging site from the archive alone, in a day, with no access to the original account? If the answer is no, you have found the gap while it is cheap to fix.

Seven questions to ask any CMS before you sign

Bring these to the evaluation call and write down the answers:

Can I export all content myself, without contacting support?
Is the export structured JSON, and does it include the schema as well as the values?
Are object IDs stable across export and import?
Do relationships export as references I can resolve?
Are drafts, scheduled content, and locale variants included?
Can I retrieve every media original programmatically?
Can the whole thing run on a schedule through the API?

A vendor that answers all seven cleanly is one you can leave, which is exactly why you probably will not need to.

Where Cosmic stands

Content in Cosmic is stored as structured Objects with a defined content model, reachable through the REST API and the TypeScript SDK, with a full JSON import and export in the dashboard and a CLI for scripting. Nothing about the format requires our software to read it. That is the standard worth holding every headless CMS to, including this one.

Start free with a Cosmic account, no credit card required.

When Agents Outnumber Editors

Tony Spiro — Mon, 24 Aug 2026 22:39:53 +0000

There is a ratio inside every content team that nobody tracks: how many things get written by people versus how many get written by software. For most teams that number was zero for a long time. Then it was a rounding error. Now, on a lot of teams, it has quietly crossed one to one.

Once agents outnumber editors, the shape of the job changes. Drafts become cheap and abundant. The scarce resource is the judgment required to decide what deserves to ship. If your workflow was built around the old bottleneck, it will break in a specific and predictable way: a queue of plausible-looking drafts nobody has time to verify.

The mechanics of what an agent is allowed to touch are a separate subject, and we covered those in AI Agent Write Access: The 4 Real Controls You Get With Your CMS, including the two controls we do not ship yet. This post is about what happens upstream of any of those settings: how the daily work of a content team reorganizes itself once the ratio flips, and which four operating habits have to change with it.

The ratio flips faster than the process does

A two-person content team with four agents running scheduled jobs can produce more drafts in a week than the two humans can carefully read. Reading a 1,500-word post closely, checking its claims against primary sources, and verifying its links takes real time. Generating it takes minutes.

So the throughput ceiling moves from writing to reviewing, and every process decision should follow that move. The goal is to make review fast and to make bad output structurally hard to publish.

Shift 1: scope becomes a commissioning decision

The most common mistake is giving one agent broad access to everything and hoping the prompt holds. Prompts drift. Keys do not.

When you spin up a new agent, treat its scope the way you would treat a job description rather than a configuration screen you fill in afterward:

Write down the object types each agent is expected to touch, and put that list in its instructions. A social copy agent has no reason to touch your pricing page object, and it should be told so explicitly.
Default every agent to draft output. Publishing should be a separate, deliberate action taken by someone accountable for it.
Separate read keys from write keys in your environment. An agent that only summarizes traffic never needs a write key at all.
Keep destructive operations off the table unless a human explicitly asks for them in that session.

Be clear with yourself about which of these are enforced and which are conventions. In Cosmic today, the enforced boundary is the key an agent holds: read-only or read-write across the bucket. There is no per-object-type permission setting, so "this agent only touches blog posts" is an instruction you give and a habit you audit, not a rule the platform enforces for you. That is exactly why the read-key/write-key split matters so much, and why draft-by-default carries real weight.

Shift 2: review becomes the throughput ceiling

Draft status is the cheapest safety mechanism you have. It costs nothing and it catches everything. The habit that has to change is calendar-level: review is now the work you schedule your week around, rather than a step you tack onto the end of someone else's.

That means the review queue has to be a real surface your team sees without remembering to check the dashboard. Pull it with the TypeScript SDK and render it wherever your team already works:

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
});

const recent = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props('id,title,slug,status,created_at,metadata.author')
  .status('any')
  .sort('-created_at')
  .limit(25);

const reviewQueue = recent.objects.filter((post) => post.status === 'draft');

Approval is then an explicit write, with a key that only your review surface holds:

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
  writeKey: process.env.COSMIC_WRITE_KEY!,
});

await cosmic.objects.updateOne(objectId, {
  status: 'published',
  metadata: { last_updated: new Date().toISOString().slice(0, 10) },
});

Two details matter more than they look. First, read the object back after a write and confirm the field actually stored the value you sent. A write that reports success while dropping a field is the kind of bug that ships a post with an empty meta description. Second, use explicit object IDs for relationship fields such as tags and category. Slugs can collide across object types and resolve to the wrong record.

Shift 3: attribution becomes a weekly number

When five agents and two humans all touch the same bucket, "who wrote this" turns into an operational question you have to answer quickly. You need it to debug a bad claim, to retire an underperforming agent, and to answer the inevitable question about how much of the site is machine-written.

Cosmic Insights attributes traffic by the actor who created the underlying object, splitting results across human users, agents, and automations. That answers a question most teams cannot answer at all: is the agent-authored content earning attention, or just filling the index?

Run that report before you scale an agent up, and put it on the same cadence as your traffic review. An agent producing thirty posts a month that collectively earn less traffic than three human posts is a cost, and the fix is usually narrower scope rather than more volume.

Shift 4: the content model does the editing you no longer have time for

The content model is the only guardrail that applies to every writer equally, human or machine. A required field is required for everyone. A select field with five options cannot be answered with a sixth. Every rule you move into the model is a review comment you never have to write again.

Things worth encoding in the model rather than in a prompt:

Required SEO fields. If seo_title and seo_description are required, no agent can ship a post without them.
Character limits. A maxlength on the meta description enforces the limit at write time.
Select options in place of free text. Category, content type, and funnel stage should be closed sets.
A verification field. For anything that cites a third party, a required last_verified date makes staleness visible.
Required relationships. An author reference on every post means attribution is always captured.

Every one of these turns a review comment you would otherwise write by hand into a validation error the agent has to resolve before the object saves. Given that write access is bucket-wide rather than scoped per type, the model is doing more enforcement work than most teams realize.

The failure modes to watch for

Four patterns show up repeatedly once agent volume rises:

Near-duplicate content. Two agents, or the same agent on two runs, produce posts that target the same query. They then compete with each other in search. Search your own bucket before commissioning anything new.
Confidently stale third-party claims. An agent reuses a competitor price or feature limit from an older draft. The rule that fixes this is simple: any claim about another product must be re-verified against that vendor's live page in the same run that writes the sentence.
Invented specificity. Round numbers, benchmark figures, and customer counts that no source supports. Require a link next to every number.
Drift from the house voice. Individually fine, collectively recognizable as machine output. Keep an explicit list of banned constructions and check drafts against it.

A fifth one is worth naming because it caught us while writing this post: an agent describing your own product's capabilities from memory instead of from current documentation. The first version of this article claimed Cosmic could scope an agent's write access to a single object type. It cannot. Apply the same verification rule to your own product that you apply to competitors.

Each of these is an argument for putting the gate before publication rather than after a correction.

What this does to headcount

The interesting outcome is that the team does not grow the way you would expect. Output rises while headcount stays flat, and the roles that remain shift toward editing, verification, and deciding what to commission.

Customers describe the same pattern when a CMS stops requiring a developer for routine changes. As Maximilian Wuhr, Co-Founder at FINN, put it: "Cosmic is: us never having to ask a developer to change anything on the backend of our website."

If you do add a reviewer, the cost is predictable. Cosmic plans include a set number of team members (Free includes 2, Builder 3, Team 5, Business 10), and additional users are $29 per user per month. Current plan details are on the pricing page.

Getting started

If you are heading toward this ratio, the sequence that works is: tighten the content model first, make draft the default second, build the review queue third, and add agents fourth.

Cosmic gives you the pieces for all four. The headless CMS provides the content model and validation, the REST API and TypeScript SDK provide the review surface, the MCP server connects Claude, Cursor, or any MCP client directly to your content, and Insights tells you whether any of it is working. If you want the specific permission controls behind all of this, we documented each one and how to verify it.

Start free with a Cosmic account, no credit card required.

Originally published at cosmicjs.com.

The Content Flywheel: How We Run AI Agents From Publish to Insights and Back

Tony Spiro — Fri, 21 Aug 2026 15:46:32 +0000

Most AI content tooling stops at the draft. You prompt a model, it produces something, a human edits it, and the loop ends there. Whatever happens to that content after publish never makes it back to the thing that wrote it.

At Cosmic, we've completed the loop. Our agents publish into Cosmic, Cosmic Insights measures what the content does, and the same agents read that data on a schedule and decide what to write, fix, or retire. That closed loop is what we call the content flywheel, and we run it on cosmicjs.com every day.

Here is how it actually works, with real numbers from the project that powers content on this website.

The four stages

A content flywheel needs four things wired together. Miss one and it stops being a loop.

A content model an agent can write to. Structured, queryable fields.
An agent with real capabilities. Read the CMS, write to the CMS, browse the web, post to Slack.
Measurement attached to the content. Traffic attributed back to the object itself.
A scheduled goal that closes the loop. Something that wakes up, reads the data, and acts.

Cosmic gives you all four in one place, which is the entire reason the loop is short enough to be useful.

Stage 1: The content model

Our blog post type has the fields you would expect, plus the ones that make measurement possible: seo_title, seo_description, teaser, published_date, last_updated, and relationship fields for author, category, and tags.

That structure matters more than it sounds. Because last_updated is a real date field and tags is a real relationship, an agent can ask questions like "which posts tagged AI Agents have not been touched in 90 days" and get an answer it can act on. A single freeform body field leaves that question unanswerable.

Agents read and write this model through the same REST API and TypeScript SDK your app uses:

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
});

// Find posts in a topic cluster that are going stale.
// Query relationship fields by object ID, not slug: slugs can
// collide across object types and resolve to the wrong object.
const { objects } = await cosmic.objects
  .find({
    type: 'blog-posts',
    'metadata.tags': '6a21aa1ed66dd9646b9e028a', // "AI Agents" tag object ID
    'metadata.last_updated': { $lt: '2026-05-20' },
  })
  .props('id,title,slug,metadata.last_updated')
  .limit(25);

The agent uses the same query. There is no separate agent API to learn and no second copy of your content to keep in sync.

Stage 2: The agents

An agent in Cosmic is a team member you configure. You grant capabilities: read content, write content, browse the web, call external APIs, send messages to Slack or Telegram, read analytics, work on a connected repository. What the agent does is decided by the capabilities you give it.

Ours are split by job, the same way a content team is:

A content lead agent that researches, writes, and publishes into the bucket.
A social coordinator agent that pulls the day's published posts and writes platform-specific copy.
A growth agent that reads Insights and reports to the team in Slack.

They hand work to each other. The social agent asks the content agent what shipped in the last 24 hours, gets back titles, slugs, and categories, and writes from that instead of guessing.

Stage 3: Measurement that points back at the content

This is the stage most teams skip, and it is the one that makes the loop real.

Cosmic Insights tracks pageviews, visitors, sessions, bounce rate, custom events, and revenue. The part that matters for a flywheel is object attribution. Add one meta tag to your page and traffic rolls up by Cosmic object alongside the URL path:

<meta name="cosmic-context" content='{"object_id":"6a873688f234aa885b778173","object_type":"blog-posts"}'>

Now the agent that wrote the post can ask how that exact object performed. Custom events fill in the rest:

window.cosmicInsights('signup_cta_click', {
  object_id: '6a873688f234aa885b778173',
  object_type: 'blog-posts',
});

On cosmicjs.com, here is what our event data looked like over the 30 days ending August 20, 2026:

Event	Events	Visitors
signup_started	751	645
signup_completed	350	335
cta_click	314	247
signup_cta_click	265	223
lesson_view	243	97

A 46.6% completion rate from signup start to finish is a number we can hold a strategy against. Google organic sent 19,664 events from 16,838 visitors in that same window, which tells us which half of the funnel deserves attention. These are rolling-window figures, so they move; the point is that an agent can pull them on demand rather than guess.

Stage 4: The scheduled goal that closes it

A capability without a cadence is still a manual process. In Cosmic you give an agent a goal with a cron schedule, and it works through that goal in a bounded loop until it decides it is done.

Our loop-closing goals look roughly like this:

Weekly, Tuesday morning: read the last seven days of Insights by path and by custom event, compare against the prior seven, and post the deltas to Slack with content recommendations.
Weekly: scan competitor blogs and pricing pages, cite every claim with the URL fetched in that same run, and recommend counter-content.
Daily: report which posts published in the last 24 hours so downstream agents can act on them.

The rule we enforce on every one of these: every number in the output has to come from a tool call made in that same run. No remembered figures, no plausible-looking estimates. An agent that fabricates a metric poisons the flywheel faster than a slow one starves it.

The week the flywheel caught something we missed

Here is the concrete example, and it is not a flattering one.

Our highest-traffic blog cluster is a set of AI coding tool comparisons. They pull thousands of Google visitors a month. When we pulled signup_cta_click broken down by page, none of those posts appeared in the list. Zero measured CTA clicks against our best organic traffic.

The obvious conclusion was that the posts had no calls to action. So we read the objects back out of the CMS and checked. Every post had a mid-article signup block and a bottom CTA block, both rendering correctly on the live page.

The actual problem was in the shared CTA blocks. Cosmic lets you define reusable rich-text blocks and reference them from any post with a token like {{bottom-cta}}. Ours pointed at a bare signup URL with no UTM parameters and no click event bound to it. The clicks were happening. Nothing was recording them.

One edit to two shared blocks instrumented every blog post in the bucket at once, because the blocks are referenced by every post that uses them. The blog channel now shows up in source attribution.

The most valuable output here was diagnostic. The flywheel told us that a question we thought we had answered had never actually been measured.

What we got wrong the first time

Three honest lessons from running this for a while:

Attribution gaps look like content failures. Our first read of the data said the comparison posts were bad at converting. The real answer was that we could not see the conversions. Verify instrumentation before you rewrite content.

Read the object back after every write. We have had writes report success while silently dropping a field, usually on repeaters and relationship fields. Our agents now re-read every object after writing it and confirm the field actually stored. Use explicit object IDs for relationship fields, since slugs can collide across object types.

Bounce rate is a weak signal on its own. A developer who lands from Google, reads a comparison post, and leaves satisfied counts as a bounce. Pair it with custom events before you conclude anything.

Building your own

The shortest path to a working loop:

Model your content with real fields, especially dates and relationships. Agents can only act on structure they can query.
Add the Insights script and a cosmic-context meta tag to your content templates so traffic rolls up by object.
Fire one custom event on your primary conversion action.
Create an agent with content read and write capability, plus analytics access.
Give it one scheduled goal that reads last week's data and reports what changed.

Start with step five as a report-only goal. Let it tell you what it sees for a few weeks before you let it publish anything. Trust in the loop should be earned with evidence, and the loop is very good at producing evidence.

You can read more about how agents are configured on the Cosmic AI agents page, or connect your own AI tools directly to your content model through the Cosmic MCP server.

Give your AI agents a content backend they can write to. Structured, versioned content objects, a REST API and TypeScript SDK, and an MCP server your coding agent connects to directly. The Free plan includes 1 Bucket, 1,000 Objects, and 1 agent. No credit card required.

Start for free or see Cosmic for AI teams.

How to Migrate from Payload CMS to Cosmic

Tony Spiro — Sat, 15 Aug 2026 19:34:05 +0000

Last verified: August 14, 2026. Every claim about Payload on this page was checked against Payload's own live pages on that date: Payload Cloud pricing and status, What is Payload, and the Local API docs. Cosmic pricing was checked against cosmicjs.com/pricing. Note that payloadcms.com/pricing returned a 404 on this date; Cloud plan details now live on the /cloud-pricing page.

What actually changed at Payload

Payload has joined Figma. The announcement is on the Figma blog, and it is linked from the top of every page on payloadcms.com.

Two things follow from that, both stated by Payload directly on its Cloud page:

New Payload Cloud deployments are paused. In Payload's words: "Although deployment of new projects is currently paused, existing Cloud projects will continue running as normal."
Existing Cloud projects will eventually move. From the same page's FAQ, answering "Will I need to migrate my project?": "Yes, eventually. There is no rush, but we are planning to build something better that you will be able to migrate to once it's available."

Here is what has not changed. Payload the framework is still open source, still actively developed, and still self-hostable. Payload's own docs state that Payload remains a self-hosted solution, and that anywhere you can run a Next.js app, you can run Payload. If you self-host Payload today, nothing above forces your hand.

The teams with a real decision to make are the ones who picked Payload Cloud because they wanted someone else to run the database, the file storage, and the deploys.

Should you migrate at all?

Three honest options. Pick based on your team, not on vendor news.

Stay on Payload and self-host it. The right call if your content model leans on Payload's code-first strengths: custom access control, hooks, field-level permissions, or an admin panel you have meaningfully customized in React. You will need to own a database, object storage, and a deploy target. Payload is a Next.js application, so this is familiar work for a Next.js team.

Wait for whatever Figma ships. Payload says there is no rush and that a migration path to something new is planned. If your project is stable and you have infrastructure people, waiting costs you little.

Move to a managed API-first CMS. The right call if the reason you chose Payload Cloud was that you did not want to run infrastructure, and you would rather not go back to running it. That is the path this guide covers.

What you give up moving to Cosmic

Stating this plainly, because a migration guide that pretends there are no tradeoffs is not worth reading.

The Local API goes away. Payload's biggest technical advantage is that it runs in the same Node process as your app, so you can query the database directly from a React Server Component with no network hop. Cosmic is an HTTP API. For most content sites the difference disappears behind caching and static generation, but it is a genuine architectural change and you should know it going in.
No GraphQL. Payload exposes REST and GraphQL. Cosmic offers a REST API and a TypeScript SDK, and does not offer GraphQL. If your frontend is built on Payload's GraphQL endpoint, that query layer gets rewritten.
Code-first config becomes dashboard-first modeling. In Payload your collections live in version-controlled TypeScript. In Cosmic you define Object Types in the dashboard or over the API. Some teams consider that a downgrade in reviewability, and others consider it the point.
Custom admin components. React components you injected into the Payload admin panel do not carry over.
Auth and access control. Payload ships user auth and granular access control as first-class features. If you used Payload as your application's auth layer and not only as a CMS, that responsibility moves elsewhere.

If several of those matter a lot to you, self-hosting Payload is probably the better answer, and you should stop reading here. No hard feelings.

Mapping Payload concepts to Cosmic

Payload	Cosmic
Collection	Object Type
Document	Object
Global	Single Object (a type with one Object)
Field	Metafield
`slug`	Object slug
Upload collection	Media library
Relationship field	Object metafield (`object` / `objects`)
Array field	Repeater metafield
Blocks field	Repeater, or rich text with Content Blocks
Group field	Parent metafield group
Draft / published	Object status (`draft` / `published`)
Localization	Locale variants on an Object Type

The shapes line up closely enough that most migrations are a data-transform problem rather than a redesign.

Step 1: inventory what you actually have

Before writing any script, list every collection and global, the document count in each, and which fields are genuinely used. Migrations balloon because teams port fields nobody has filled in for two years.

Payload's Local API gives you counts quickly:

import { getPayload } from 'payload'
import config from '@payload-config'

const payload = await getPayload({ config })

for (const collection of payload.config.collections) {
  const { totalDocs } = await payload.count({ collection: collection.slug })
  console.log(`${collection.slug}: ${totalDocs}`)
}

Write the output down. It is your migration checklist and your verification target at cutover.

Step 2: export from Payload

Run this inside your Payload project so @payload-config resolves. Two details matter: pagination: false returns every document instead of the first page, and depth: 0 keeps relationships as raw IDs instead of expanding them into nested objects. You want raw IDs, because you are going to remap them yourself.

import { getPayload } from 'payload'
import config from '@payload-config'
import fs from 'node:fs/promises'
import path from 'node:path'

const payload = await getPayload({ config })
const outDir = path.resolve('./payload-export')
await fs.mkdir(outDir, { recursive: true })

// Collections
for (const collection of payload.config.collections) {
  const { docs } = await payload.find({
    collection: collection.slug,
    pagination: false,
    depth: 0,
    overrideAccess: true,
  })

  await fs.writeFile(
    path.join(outDir, `${collection.slug}.json`),
    JSON.stringify(docs, null, 2),
  )

  console.log(`exported ${docs.length} from ${collection.slug}`)
}

// Globals
for (const global of payload.config.globals) {
  const doc = await payload.findGlobal({ slug: global.slug, depth: 0 })

  await fs.writeFile(
    path.join(outDir, `global-${global.slug}.json`),
    JSON.stringify(doc, null, 2),
  )
}

Commit that folder somewhere safe. Everything after this point is reversible as long as the export exists.

Step 3: model your content in Cosmic

Create one Object Type per Payload collection. You can do it in the dashboard, or script it so the whole migration is repeatable:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
  writeKey: process.env.COSMIC_WRITE_KEY!,
})

await cosmic.objectTypes.insertOne({
  title: 'Posts',
  singular: 'Post',
  slug: 'posts',
  metafields: [
    { key: 'excerpt', title: 'Excerpt', type: 'textarea' },
    { key: 'content', title: 'Content', type: 'markdown' },
    { key: 'hero', title: 'Hero Image', type: 'file' },
    {
      key: 'author',
      title: 'Author',
      type: 'object',
      object_type: 'authors',
    },
  ],
})

Migrate types with no relationships first (authors, categories, tags), then the types that point at them. That ordering saves you a second reconciliation pass.

Step 4: move the media

Payload upload documents store a filename and a URL. Pull each file and push it into the Cosmic media library, keeping a map from the old Payload ID to the new Cosmic media name so you can rewrite references later.

const idMap = new Map<string, string>()

for (const doc of uploadDocs) {
  const res = await fetch(doc.url)
  const buffer = Buffer.from(await res.arrayBuffer())

  const { media } = await cosmic.media.insertOne({
    media: { originalname: doc.filename, buffer },
    folder: 'payload-import',
    alt_text: doc.alt ?? '',
  })

  idMap.set(doc.id, media.name)
}

If you set alt text in Payload, carry it across now. Alt text lives on the Cosmic media record itself, so every Object referencing that image inherits it, which is one less accessibility cleanup later.

Step 5: convert rich text

This is the step that surprises people, so budget real time for it.

Payload stores rich text as a structured JSON tree, not as markdown or HTML. You cannot drop that JSON into a markdown metafield and expect it to render. You need a serializer that walks the tree and emits markdown or HTML.

Payload's rich text documentation covers converting its editor state to other formats, and that is the tool to reach for. Two things to watch:

Uploads embedded in rich text become nodes referencing an upload ID. Rewrite those to the Cosmic media URLs from your idMap in Step 4.
Blocks embedded in rich text need a destination. Either flatten them into markdown, or create a reusable Cosmic Content Block and reference it with a {{block-name /}} token in a rich text metafield.

Convert one document, eyeball the output, then convert the rest. Do not batch-convert 2,000 documents on faith.

Step 6: import into Cosmic

With media mapped and rich text serialized, the import itself is short. Keep a Payload-ID to Cosmic-ID map as you go so relationship fields can be resolved on a second pass.

import { createBucketClient } from '@cosmicjs/sdk'
import posts from './payload-export/posts.json'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
  writeKey: process.env.COSMIC_WRITE_KEY!,
})

for (const doc of posts) {
  await cosmic.objects.insertOne({
    type: 'posts',
    title: doc.title,
    slug: doc.slug,
    status: doc._status === 'published' ? 'published' : 'draft',
    metadata: {
      excerpt: doc.excerpt ?? '',
      content: await toMarkdown(doc.content),
      hero: doc.hero ? idMap.get(doc.hero) : null,
      author: authorIdMap.get(doc.author),
    },
  })
}

Preserve the original slug values. That single decision is what keeps your URLs, your rankings, and your inbound links intact.

Step 7: rewire the frontend

If your app is Next.js, this is the most mechanical part of the whole project. Payload Local API calls become Cosmic SDK calls.

Before:

const payload = await getPayload({ config })
const { docs } = await payload.find({
  collection: 'posts',
  limit: 10,
  sort: '-publishedDate',
})

After:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!,
})

const { objects } = await cosmic.objects
  .find({ type: 'posts' })
  .props(['title', 'slug', 'metadata'])
  .depth(1)
  .limit(10)
  .sort('-created_at')

Use .props() to request only the fields the page renders. Payload's Local API had no network cost, so over-fetching was cheap. Over an HTTP API it is not, and trimming the payload is the single easiest performance win in the port.

Step 8: verify, then cut over

Work through this before you flip DNS:

Counts match. Compare every Object Type count against the inventory from Step 1.
Spot-check the ugly documents. Not the simple ones. The post with nested blocks, four images, and a relationship array.
Every relationship resolves. Query with .depth(1) and confirm nothing comes back null.
Slugs are identical to production Payload for every public URL.
Media loads on a real page render, not only in the dashboard.
Redirects staged for any URL that genuinely had to change.
Keep Payload running in parallel until the checks pass. There is no prize for deleting it early.

What this costs on Cosmic

Verified against cosmicjs.com/pricing on August 14, 2026:

Plan	Price	Buckets	Team members	Objects
Free	$0/mo	1	2	1,000
Builder	$49/mo	2	3	5,000
Team	$299/mo	3	5	20,000
Business	$499/mo	5	10	50,000
Enterprise	Custom	Custom	Custom	Custom

Additional team members beyond a plan's included seats are $29/user/month.

The practical move is to run the whole migration on the Free plan first. One Bucket and 1,000 Objects is enough to prove the export, the transform, and the import against real content before anyone approves a budget line.

FAQ

Is Payload CMS being shut down?
No, and nothing on this page should be read that way. Payload is open source and self-hostable, and Payload states that existing Cloud projects continue running as normal. What changed is that new Payload Cloud deployments are paused, and Payload says existing Cloud projects will eventually need to migrate to a future replacement.

Can I keep my URLs?
Yes, as long as you carry the slug field across unchanged. Cosmic Objects have a slug you control, so a one-to-one mapping is normal.

Does Cosmic support GraphQL?
No. Cosmic provides a REST API and a TypeScript SDK. Payload does expose GraphQL, so if your frontend depends on it, plan on rewriting that data layer.

How long does a migration take?
It depends almost entirely on rich text and blocks. A handful of collections with plain fields is an afternoon. A heavily block-driven site with thousands of documents is a multi-week project, and the serializer is where the time goes.

Can I run both during the transition?
Yes, and you should. Import into Cosmic, point a staging branch at it, verify against the Step 8 checklist, and only then cut over.

Next steps

If you were on Payload Cloud for the managed hosting and you want to stay out of the infrastructure business, the cheapest way to evaluate Cosmic is to migrate one collection and look at the result.

Create a free Bucket and run the export script above against your smallest collection. If you would rather walk through your content model with someone first, book time with our CEO Tony Spiro.

DEV Community: Tony Spiro

Best Headless CMS for Astro in 2026: 4 Options Compared

What Astro actually needs from a CMS

Cosmic

Sanity

Storyblok

Strapi

How to choose

Build it

Best Headless CMS for Nuxt in 2026: 7 Options Compared

Quick comparison

1. Cosmic

Reading Cosmic content in Nuxt

2. Nuxt Content

3. Storyblok

4. Sanity

5. Strapi

6. Prismic

7. Directus

How to choose

Frequently asked questions

Start building

Best Sanity Alternatives in 2026: 5 Compared

Sanity's pricing, for reference

Quick comparison

What to check before switching

The alternatives

Cosmic

Hygraph

Prismic

Storyblok

Strapi

How to choose

Moving from Sanity to Cosmic

Best Headless CMS to Replace WordPress in 2026

Quick comparison

What a WordPress migration involves

The options

Cosmic

Payload

Prismic

Sanity

Storyblok

Strapi

How to choose

Connect a Cosmic Agent to Google Sheets

What you will have at the end

Step 1: Set up the Google side

Step 2: Set up the Cosmic side

Step 3: Create the file through the Drive API

Step 4: Write multiple tabs, then read the edits back

Three things this makes possible

1. A draft handoff a human can actually edit

2. Structured exports that are not one flat table

3. One credential across many properties

Troubleshooting

Give your agent an inbox, then sign it up for Cosmic

What you get at the end

Two different email addresses

Create the AgentMail inbox

Errors you will actually hit

Sign up for Cosmic with the agent inbox

Read the claim code from the inbox

Verify the Cosmic project

Use the bucket

Moving a 1,700-page site to the Next.js 16 App Router without a sitemap hole

The shape of the site

Problem 1: the build hit Vercel's 45-minute cap

Problem 2: skipping the prerender quietly broke the sitemap

Problem 3: Turbopack compiled forever in production

Problem 4: draftMode() turned every blog post dynamic, then 500'd

Problem 5: next-seo went silent and took 400 page titles with it

The thing that actually de-risked this

What it actually bought us

What to take from this

Automating Editorial Triage: Routing Drafts Across 13 Properties with Cosmic and TypeSafe

What Jev does, and what it does not do

The architecture

Step 1: write the questions, and take criteria seriously

Step 2: one call, every question

Problem 4: `draftMode()` turned every blog post dynamic, then 500'd

Problem 5: `next-seo` went silent and took 400 page titles with it