DEV Community: Tony Spiro

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.

Claude Marks Its AI-Generated Content Now: What That Means for Your CMS

Tony Spiro — Tue, 11 Aug 2026 22:03:00 +0000

Anthropic published a support article on how Claude marks AI-generated content, and it spent this morning on the Hacker News front page. The document itself is short and mostly technical. The discussion was neither, because it lands on a question most content teams using AI have been quietly deferring: when a model touches your content, is there a record, and whose job is it to keep one?

Here is what actually shipped, what it can and cannot prove, and the part that falls to you.

What Anthropic shipped

Anthropic signed the EU AI Act's Article 50(2) Code of Practice on Transparency of AI-Generated Content. Claude models launched in the EU on or after August 2, 2026 support machine-readable marking at launch, and Anthropic says it is working to add marking support to models released before that date.

There are two mechanisms.

Imperceptible watermarks in text. Claude weaves a mark directly into the text it generates. A reader cannot see it, and Anthropic states it does not change the meaning, quality, or readability of the output. Because the watermark is part of the text, it travels with the text when it is copied and pasted, and it may persist through some editing.

C2PA signed provenance metadata on files. When Claude generates a supported file type, including .svg, .png, and .jpg, it attaches signed provenance metadata following the Coalition for Content Provenance and Authenticity open standard. A signed label signals the file was processed by Claude and lets you detect whether it has been tampered with.

Marking is applied at the model level, so it follows the models across the surfaces they run on: Claude Platform (API), Claude, Claude Code, Claude Cowork, and Claude Tag. Embedded watermarks also apply when supported models are accessed through AWS, Google Cloud, or Microsoft Foundry. Anthropic is explicit that coverage is not uniform, and that signed file metadata in particular may not be supported on every platform. Marking applies worldwide, not only to users in the EU. Detection documentation is described as forthcoming.

If you build products on Claude, Anthropic's own guidance is that you should independently assess what Article 50 requires of you. Signing the code of practice covers Anthropic's models. It does not discharge your obligations for the thing you shipped.

What a detected mark tells you, and what it does not

The limitations section is the most useful part of that document for anyone running a publishing pipeline, and Anthropic is unusually direct about it.

A mark means Claude processed the text. It does not establish that Claude wrote it. Anthropic gives the examples itself: people use Claude to proofread, translate, summarize, and convert files, and the output can carry a mark even when the underlying ideas, text, or data came from somewhere else. Any policy that treats a detected mark as proof of machine authorship will produce false accusations against your own writers.

Absence of a mark proves nothing. Anthropic lists the cases: content from a model released before marking was supported, text that has been heavily edited or paraphrased or translated, passages too short to carry a reliable signal, and files whose metadata was stripped.

File metadata is fragile in completely ordinary ways. Anthropic names format conversion, re-saving, and screenshots as things that strip C2PA metadata. If you have ever run images through an optimization or resizing pipeline, you have probably stripped provenance metadata already without noticing. Verify what actually survives your own media pipeline before you rely on it.

So the honest summary: watermarking is a meaningful transparency measure for the open internet and a weak internal record for your team. Detection answers "did a model touch this" with a qualified maybe. It does not answer the questions your team will actually be asked.

The questions you will actually be asked

When a claim in a published post turns out to be wrong, or a customer asks how your documentation is produced, or legal asks what your AI disclosure covers, the questions are specific:

Which model produced this draft, at what version?
Was it a person using an assistant, or an agent running unattended?
Which human reviewed it before it went live, and on what date?
Were the product facts, pricing, and customer references checked against a source of truth?
How many published pages are fully machine-generated and have never been read by anyone on the team?

None of those are recoverable from an invisible watermark, even a perfectly detected one. All of them are trivially recoverable from your CMS, if you decided in advance to store them.

Store provenance as typed fields

Provenance that lives in a Slack thread, a spreadsheet, or someone's memory is not provenance. Add it to the content model so it is queryable, reportable, and impossible to skip.

A minimal set of fields that covers the questions above:

Field	Type	Purpose
`ai_assisted`	Switch	Was a model involved at all
`ai_role`	Select	`drafted`, `edited`, `translated`, `researched`
`ai_model`	Text	Model and version, e.g. `claude-sonnet-5`
`human_reviewer`	Object	Relationship to your authors type
`review_date`	Date	When a person actually signed off
`facts_verified`	Switch	Product facts and pricing checked against source

The ai_role distinction is the one that matters most, because it is exactly the distinction watermark detection cannot make. A post Claude drafted end to end and a post Claude proofread can carry the same mark. Your own record separates them.

Writing that record with the Cosmic TypeScript SDK:

npm install @cosmicjs/sdk

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

const cosmic = createBucketClient({
  bucketSlug: 'your-bucket-slug',
  readKey: 'your-read-key',
  writeKey: 'your-write-key',
});

await cosmic.objects.updateOne('OBJECT_ID', {
  metadata: {
    ai_assisted: true,
    ai_role: 'drafted',
    ai_model: 'claude-sonnet-5',
    human_reviewer: 'jane-doe',
    review_date: '2026-08-11',
    facts_verified: true,
  },
});

The payoff is the query. Finding every AI-drafted post that no human has signed off on becomes one request instead of an audit:

const { objects: unreviewed } = await cosmic.objects
  .find({
    type: 'blog-posts',
    'metadata.ai_assisted': true,
    'metadata.facts_verified': false,
  })
  .props('slug,title,metadata.ai_model,metadata.review_date')
  .limit(100);

Run that on a schedule and the answer to "how much unreviewed machine-generated content is live on our site" stops being a guess. Because the fields are typed and served over the REST API, you can surface the same record on the page itself if your disclosure policy calls for it, without maintaining a second system to track it.

One note on the practical side: adding a field to a content model and backfilling it is a content-team task in a headless CMS, not an engineering ticket. Maximilian Wuhr, Co-Founder at FINN, described the value of that arrangement plainly:

"Cosmic is: us never having to ask a developer to change anything on the backend of our website."

Reporting on it

Provenance fields tell you how a piece was made. The next question is whether it performs, and whether machine-drafted work holds up against human-drafted work on your own site.

Cosmic Insights rolls traffic up by the actor who created the underlying content, splitting it across human users, agents, and automations. That turns a philosophical argument into a measurable one. If agent-drafted pages bounce harder or convert worse than human-drafted pages, you will see it in the numbers rather than debating it in a meeting. If they perform the same, that is worth knowing too.

What to do this quarter

Six things, none of which require a replatform.

Add provenance fields to your content models. Start with the six above. Ship them before you need them, because retrofitting provenance onto two years of archives is guesswork.
Backfill the last 90 days only. Recent content is what people are reading and what will get questioned. Older archives can be marked unknown, honestly.
Test what your media pipeline does to C2PA metadata. Upload a Claude-generated image, run it through your normal transform and optimization path, and check whether the Content Credentials survive. Assume they do not until you have verified it.
Write down your disclosure policy in one paragraph. What level of model involvement triggers a public disclosure on the page? "Claude drafted this" and "Claude proofread this" are different, and your policy should say so before a reader asks.
Keep detection out of your enforcement policy. If you are checking freelancer or agency submissions, treat a watermark hit as a reason to open a conversation. Anthropic's own documentation states that a detected mark is not fully conclusive, so it cannot carry a policy violation on its own.
Scope the keys your agents hold. If an agent can write to production, the provenance record it leaves is the only trail you have. Cosmic issues separate read and write keys, so a client connected with a read-only key gets the read tools while every write tool and all four AI generation tools are blocked with a clear error message. Details are on the MCP server page and in Connect Claude to Your CMS.

The through line

Model-level watermarking is a good development, and it solves a problem at the wrong altitude for your purposes. It helps the broader internet identify synthetic content at scale. It does very little for the team that has to explain how a specific paragraph on a specific page came to exist.

That record is yours to keep, and the only place it can reliably live is next to the content itself, as structured fields you can query. Teams that add those fields now will answer provenance questions in one API call. Teams that wait will reconstruct them from memory, which is another way of saying they will not answer them at all.

If you are already running AI in your publishing workflow, this is a one-afternoon change with a long tail of value. You can model provenance fields on the Cosmic free plan and query them over the REST API today.

Start free or book 15 minutes with our CEO to talk through how your content model should record agent work.

Sources

Anthropic, How Claude marks AI-generated content, Claude Help Center
C2PA, Coalition for Content Provenance and Authenticity

Originally published on the Cosmic blog.

Connect Claude to Your CMS: A 5-Minute Guide to the Cosmic MCP Server

Tony Spiro — Mon, 10 Aug 2026 22:03:30 +0000

If you already run Claude every day, the next obvious question is whether it can touch your content. Not summarize it. Not draft copy in a chat window you then paste somewhere. Actually read your content model, query it, and write back to it.

Cosmic answers that with an MCP server. This guide gets you connected in about five minutes, then covers the part most people skip: what Claude is allowed to do once it is connected.

What MCP actually gives you

Model Context Protocol is a standard way for an AI client to discover and call tools. Instead of you describing your CMS to Claude in prose, Claude asks the server what tools exist and calls them directly.

The Cosmic MCP server exposes 18 bucket-scoped tools. They cover objects, object types, media, and AI generation. Bucket-scoped is the important word: the server operates against one Bucket, using the keys you give it, and it cannot reach across your other Buckets.

The five-minute setup

1. Get your Bucket keys

In your Cosmic dashboard, open your Bucket, then Settings > API Access. Copy three things: your Bucket slug, your read key, and your write key. The keys are separate on purpose, and that separation is the single most useful control in this whole setup. More on that below.

2. Add the server to your MCP client config

The hosted endpoint is the fastest path and needs no install. Point your client at https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug} and authenticate with your keys in the Authorization header.

For Claude Desktop, edit your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cosmic": {
      "url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
      "headers": {
        "Authorization": "Bearer your-read-key:your-write-key"
      }
    }
  }
}

Cursor takes the same shape in .cursor/mcp.json for a single project, or ~/.cursor/mcp.json globally.

Read the bearer token carefully: read key, colon, write key. Drop the :your-write-key suffix and the connection becomes read-only. Hold onto that detail, because it is the control worth understanding before you point any of this at production.

If you would rather run the MCP process inside your own dev environment, the @cosmicjs/mcp package ships a stdio binary that reads credentials from environment variables:

{
  "mcpServers": {
    "cosmic": {
      "command": "npx",
      "args": ["@cosmicjs/mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key"
      }
    }
  }
}

Save the file and restart the client. The Cosmic tools show up in the tool list.

3. Verify the connection

Ask Claude something read-only first:

"List the object types in this Bucket and tell me how many objects are in each."

If you get back your real content model, you are connected. If you get nothing, the key or the Bucket slug is wrong, and the error message will say which.

4. Try a real task

Once reads work, the useful prompts look like this:

"Find every published blog post missing an SEO description and list the slugs."

"Create a draft post from this outline, set the author to Tony Spiro, and leave status as draft."

"Add alt text to every image in the media library that does not have any."

That last one is the kind of chore that never gets done manually and takes an agent about a minute.

The control that matters: read keys and write keys

Here is the part worth understanding before you hand an agent your production Bucket.

Cosmic issues separate read and write keys. Give an MCP client a read-only key and it gets the read tools only. Every write tool returns a clear blocked error. Nothing is guessed, nothing is inferred from a system prompt, and no amount of clever prompting talks its way past it.

You can verify this yourself in under a minute:

Set the Authorization header to Bearer your-read-key with no write key and no colon
Ask Claude to create a new object
Read the blocked error it returns

That is a checkable guardrail, not a policy document. It is also the honest starting posture for anyone connecting an agent to real content: read-only first, then widen scope deliberately once you trust the workflow.

When you are ready for writes, the safe pattern is a write-enabled key pointed at a staging Bucket, with the production Bucket still read-only. Cosmic plans include multiple Buckets from Builder up, so a dedicated staging Bucket for agent work is a reasonable setup rather than an exotic one.

Writing content through the API instead

If you would rather script the workflow than chat it, the TypeScript SDK covers the same ground:

npm install @cosmicjs/sdk

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!,
});

// Read: find drafts with no SEO description
const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts', status: 'draft' })
  .props('id,title,slug,metadata.seo_description');

const missing = posts.filter((p) => !p.metadata?.seo_description);

// Write: patch one of them
await cosmic.objects.updateOne(missing[0].id, {
  metadata: {
    seo_description: 'A short, specific summary under 155 characters.',
  },
});

Note that writeKey is a separate argument from readKey. Omit it and every write call fails, which is the same guardrail the MCP server relies on.

What this is good for, and what it is not

Good fits today:

Content audits: missing metadata, broken internal links, stale dates, orphaned objects
Bulk mechanical edits: alt text, SEO descriptions, tag normalization, category cleanup
Draft generation against your real content model, so the shape is correct on the first pass
Answering questions about your own content library without opening the dashboard

Not a good fit yet:

Unsupervised publishing to production. Keep a human on the publish step.
Anything where a wrong write is expensive and hard to reverse.

The practical rule: let the agent do the reading and the drafting, and keep the irreversible actions behind a person.

Frequently asked questions

Do I need a paid plan to use the MCP server?
You can start on the Free plan, which includes 1 Bucket, 2 team members, and 1,000 Objects. If you want a separate staging Bucket for agent writes, that starts at the Builder plan ($49/month, 2 Buckets, 3 team members, 5,000 Objects).

Does Cosmic offer a GraphQL endpoint for this?
No. Cosmic offers a REST API and the JavaScript/TypeScript SDK. The MCP server sits on top of the same REST API.

Can I limit which object types an agent can touch?
The key-level control is read versus write. For tighter scoping, point the agent at a Bucket that only contains the content you want it to work on.

Does this work with clients other than Claude?
MCP is a client-agnostic standard, so any MCP-compatible client can connect to the same server with the same 18 tools. Cursor is covered above, and the hosted endpoint speaks the streamable-HTTP transport that other clients use.

Try it on a real Bucket

The fastest way to understand what an agent can do with a proper content model behind it is to connect one and ask it a question about your own content.

Create a free Cosmic account. No credit card required.
Read the MCP server docs for the exact client configuration
Want a walkthrough of the agent workflows other teams are running? Book 30 minutes with Tony

Cosmic is a YC W19 company building the content layer for teams that want their AI tools to work against real, structured content instead of copy pasted into a chat box.

Medusa.js + Next.js: How to Add a Content Layer to Your Storefront

Tony Spiro — Fri, 07 Aug 2026 19:28:03 +0000

Medusa is a strong commerce engine. It owns products, variants, pricing, inventory, carts, orders, and fulfillment, and it exposes all of it through a clean Store API. Once you have the Next.js Starter Storefront running, the commerce half of your site is basically solved.

Then marketing asks for a buying guide on every category page, a founder story block on the product detail page, a seasonal landing page that goes live Friday at 9am, and an FAQ section that changes weekly. None of that belongs in your commerce database, and none of it should require a deploy.

This post walks through the pattern we see working best: keep Medusa as the source of truth for commerce, add a headless CMS as the source of truth for editorial content, and join them in the Next.js layer on a shared key.

The problem with putting content in Medusa

Medusa lets you attach arbitrary metadata to products. It is tempting to stuff your marketing copy in there and call it done. That falls apart quickly for three reasons.

No editing experience. metadata is a key-value bag. Your content team gets a JSON blob, no rich text, no image handling, no preview, no revision history.
No content modeling. A buying guide has a title, hero image, intro, sections, related products, and an author. Flattening that into string keys means every consumer has to re-parse it.
Content that is not product-shaped has nowhere to live. A holiday gift guide, a shipping policy page, a comparison table, a homepage hero: none of these map to a product record at all.

The fix is a second system with its own model and its own editor, joined at read time.

Draw the ownership line first

Before you write any code, write down who owns what. This one decision prevents most of the sync bugs teams hit later.

Data	Owner	Why
Product handle, title, variants	Medusa	Commerce truth, drives cart and checkout
Price, inventory, availability	Medusa	Must be real time, never cached in a CMS
Cart, orders, customers, fulfillment	Medusa	Transactional
PDP long-form story, lifestyle imagery	CMS	Editorial, changes without a deploy
Buying guides, blog posts, landing pages	CMS	No product record exists
FAQs, size guides, care instructions	CMS	Reusable across many products
Navigation, promo banners, homepage blocks	CMS	Merchandising, changes weekly

The rule to enforce in code review: price and inventory never come from the CMS. Duplicating those into a content system creates a window where your site shows a price that checkout will reject. Read them from Medusa on every request.

Step 1: Get the Medusa storefront running

Start from the official Next.js Starter Storefront so you inherit the cart, checkout, and account flows.

npx create-medusa-app@latest my-store

That scaffolds a Medusa server and a Next.js storefront. Your storefront needs two environment values to talk to the backend:

# .env.local
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...

The publishable key is created in the Medusa Admin under Settings, and it scopes requests to a sales channel. Requests to the Store API without it will be rejected.

Set up the Medusa JS SDK once and export a single client:

// src/lib/medusa.ts
import Medusa from '@medusajs/js-sdk';

export const medusa = new Medusa({
  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY!,
});

Fetching a product by its handle looks like this:

const { products } = await medusa.store.product.list({
  handle: 'classic-tee',
  fields: '*variants.calculated_price',
});

const product = products[0];

Step 2: Model the content side

Now add the content layer. In Cosmic, create an Object Type called Product Content with a metafield for every editorial element your PDP needs.

A model that has held up well in production:

Metafield key	Type	Purpose
`handle`	Text (unique)	The join key. Must match the Medusa product handle exactly.
`story`	Markdown	Long-form product narrative below the buy box
`lifestyle_images`	Files	Editorial photography separate from catalog shots
`care_guide`	Markdown	Reusable care or sizing content
`faqs`	Repeater	Question and answer pairs rendered as an accordion
`related_reading`	Objects	Links to blog posts or buying guides

The handle field is the whole design. Make it unique so two content entries can never claim the same product, and tell your editors it has to match Medusa character for character. Everything else in the model is free to change without touching commerce.

Install the Cosmic SDK and create the client:

npm install @cosmicjs/sdk

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

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

Then a small helper that fetches content for a handle and returns null instead of throwing when nothing exists yet:

// src/lib/product-content.ts
import { cosmic } from './cosmic';

export async function getProductContent(handle: string) {
  try {
    const { object } = await cosmic.objects
      .findOne({ type: 'product-content', 'metadata.handle': handle })
      .props('title,slug,metadata')
      .depth(1);

    return object;
  } catch (error: any) {
    if (error.status === 404) return null;
    throw error;
  }
}

That null return matters. It is what lets you launch a product before marketing has written anything for it.

Step 3: Join them in a server component

With both clients in place, the product page fetches from each system in parallel and renders one page.

// src/app/products/[handle]/page.tsx
import { medusa } from '@/lib/medusa';
import { getProductContent } from '@/lib/product-content';
import { notFound } from 'next/navigation';

export default async function ProductPage({
  params,
}: {
  params: Promise<{ handle: string }>;
}) {
  const { handle } = await params;

  const [{ products }, content] = await Promise.all([
    medusa.store.product.list({
      handle,
      fields: '*variants.calculated_price',
    }),
    getProductContent(handle),
  ]);

  const product = products[0];
  if (!product) notFound();

  return (
    <main>
      {/* Commerce: always from Medusa */}
      <h1>{product.title}</h1>
      <BuyBox product={product} />

      {/* Editorial: from the CMS, optional by design */}
      {content?.metadata.story && (
        <section className="product-story">
          <Markdown>{content.metadata.story}</Markdown>
        </section>
      )}

      {content?.metadata.faqs?.length > 0 && (
        <FaqAccordion items={content.metadata.faqs} />
      )}
    </main>
  );
}

Three things worth calling out.

Medusa decides whether the page exists. If there is no product, you 404. A content entry with no matching product should never render a page, because there would be nothing to add to a cart.

Every content block is conditional. The page has to render correctly with zero CMS content. Test that path deliberately by pointing a local build at a handle that has no entry.

Fetch in parallel. Promise.all keeps the two round trips from stacking. On a PDP that difference is visible in your LCP.

Step 4: Keep pages fresh without redeploying

Static rendering is what makes this pattern fast. Cache invalidation is what makes it usable for a content team.

Tag your content fetches, then invalidate the tag from a webhook.

// src/app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-webhook-secret');

  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const payload = await request.json();
  const handle = payload?.data?.metadata?.handle;

  if (handle) {
    revalidateTag(`product-content-${handle}`);
  }

  return NextResponse.json({ revalidated: true });
}

Point a Cosmic webhook at that route for the Object Edited and Object Published events. An editor publishes a change, the webhook fires, that single product page rebuilds. No deploy, no full site rebuild, no Slack message to a developer.

Do the same in reverse for Medusa: subscribe to product update events and revalidate the matching path when a title or description changes.

One exception to keep in mind. Price and inventory should not rely on webhook timing. Render those parts dynamically or fetch them client side so a customer never sees a cached price that checkout will reject.

Step 5: Everything that is not a product page

The PDP join is the interesting technical part. The larger traffic win is usually the pages that have no product record at all.

With a content layer already wired in, these become straightforward:

Buying guides and comparison pages. These are the pages that rank for research-stage queries. Model them as a guides type with a related_products field holding a list of handles, then hydrate live prices from Medusa at render time.
Category landing pages. Medusa gives you the collection and its products. The CMS gives you the hero, the intro copy, and the merchandising blocks above the grid.
Campaign pages. Marketing builds and schedules them without a developer. Cosmic supports scheduled publishing, so a Friday 9am launch is a field, not a deploy window.
Policy and support pages. Shipping, returns, sizing. Low glamour, high support-ticket deflection.

Same pattern each time: content from the CMS, live commerce data from Medusa, joined on the handle.

Four mistakes to avoid

Copying prices into the CMS. It will drift. When it drifts, customers see one number and get charged another. Always read price from Medusa.

Using the product ID as the join key. IDs change when you reseed a database or migrate environments. Handles are stable, human readable, and already unique in Medusa.

Making content required. If a missing CMS entry breaks the page, you have coupled your product launches to your content calendar. Optional by default.

Two sources of truth for the product title. Pick one, and it should be Medusa, since that is what appears on the order. If marketing needs a different display headline, add a separate display_headline field so the intent is explicit.

Why Cosmic fits this stack

A few specifics that matter when you are pairing a CMS with Medusa:

REST API and a TypeScript SDK. @cosmicjs/sdk is typed and works in Next.js server components without adapters or codegen steps.
Fully managed. You are already running a Medusa server and a database. Adding a second self-hosted service to patch and scale is real operational cost. Cosmic is hosted, so the content layer is one API call, not another deployment.
AI-assisted authoring. Editors can draft product stories, FAQs, and guide content directly in the dashboard, which is where the volume problem usually lives for catalogs with thousands of SKUs.
Scheduled publishing and webhooks. Both are built in, which is what makes the revalidation flow above work end to end.

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."

Get started

The whole integration is about 60 lines of glue code: one Medusa client, one Cosmic client, one join key, one webhook route.

Start free with Cosmic and model your first Product Content type in a few minutes. The Cosmic docs cover the SDK and webhook setup, and the Medusa docs cover the Store API side.

If you are planning a larger migration or running a catalog with thousands of SKUs, book time with Tony, our CEO, and he will walk through the content model with you.

FAQ

Can I use Cosmic to manage products instead of Medusa?
You can model product content in Cosmic, but you should not replace Medusa's product records. Carts, pricing rules, inventory, and orders depend on them. Use Cosmic for the editorial layer around the catalog.

Does this work with the Medusa Next.js Starter Storefront?
Yes. The pattern above drops into the starter's existing product route. You are adding a second data fetch alongside the Medusa one, and leaving the cart and checkout flows untouched.

How do I handle products with no content entry yet?
Return null from your content helper on a 404 and render every content block conditionally, as shown in Step 2 and Step 3. The product page stays fully functional.

What about multi-region or multi-language storefronts?
Medusa handles regional pricing and currency. Cosmic supports locales on objects, so you can request content in the visitor's locale using the same handle-based lookup.

Originally published on the Cosmic blog.

Sanity vs Strapi: Which Headless CMS Should You Choose in 2026?

Tony Spiro — Thu, 06 Aug 2026 22:03:25 +0000

Sanity and Strapi both call themselves headless, both let you define schemas in code, and both have large developer followings. They answer a different question underneath.

Sanity gives you a hosted content database, the Content Lake, with an open source editing environment on top. Strapi gives you a Node.js application under the MIT license that you run yourself, or pay Strapi Cloud to run for you.

That one architectural fork decides your query language, your upgrade path, your compliance story, your AI options, and your bill. This comparison walks through each of those with numbers verified against both vendors' live pricing pages on August 5, 2026.

TL;DR

	Sanity	Strapi
Model	Hosted content platform (Content Lake)	Open source Node.js app, MIT licensed
Who operates it	Sanity	You, or Strapi Cloud
Query API	GROQ and GraphQL over HTTP, JS client	REST and GraphQL from your own instance
Database	Managed, no direct access	Postgres, MySQL, or MariaDB that you own
Editing UI	Sanity Studio, an open source React app you deploy	Bundled admin panel
Entry price	Free plan, up to 20 seats, 10k documents	Community edition, free forever, unlimited entries
Seat cost	$15/seat/month on Growth	$15/seat/month on Growth, 3 seats included
Hosting cost	Included	Yours to pay, or $35 to $450 per project per month on Cloud
Governance extras	Comments, tasks, scheduled publishing on Growth; audit trail and SSO on Enterprise	Content History and Releases on Growth; Review Workflows and Audit Logs on Enterprise
Best fit	Teams that want structured content as a service with many editors	Teams that need to own the runtime and the data layer

Architecture: hosted content lake vs. an app you run

Sanity stores every document in the Content Lake, a hosted, schemaless JSON store with a real-time layer. You never provision a database or patch a server. You do give up direct database access, which matters if your security review requires the data to sit inside your own VPC.

Strapi is a Node.js application. You choose Postgres, MySQL, or MariaDB, you deploy it, and you own the runtime. That means full control over network boundaries, extensions, and custom middleware. It also means you own Node version upgrades, dependency patches, major-version migrations, backups, and on-call.

Strapi Cloud removes most of that operational load, and the pricing page shows the trade in plain terms. Starter projects at $35 per project per month sleep when idle. Always-on runtime begins with Pro at $90 per project per month. A 99.9% uptime SLA arrives at Business, $450 per project per month.

A useful way to decide: if your team can name the person who will handle a CVE in a transitive dependency on a Friday afternoon, self-hosted Strapi is a reasonable choice. If nobody's name comes to mind, a managed platform is cheaper than it looks.

Content modeling

Both tools model content in code, which keeps schema changes in version control and in code review.

Sanity schemas are JavaScript objects registered in your Studio. Portable Text handles rich text as structured data instead of an HTML blob, which pays off when the same content renders to web, native mobile, and voice. References are first class and resolve inside queries.

Strapi models are defined through the Content-Type Builder in the admin panel, which writes JSON schema files into your repository. Dynamic Zones let editors assemble a page from a library of components, which is the closest thing either product has to visual page building out of the box. Components, relations, and custom fields cover most modeling needs, and the Blocks editor handles structured rich text.

Strapi's advantage here is that the modeling UI ships with the product. Sanity's advantage is that Portable Text and the reference system are more rigorous once your content graph gets complicated.

APIs and developer experience

Sanity queries use GROQ, a projection language built for the Content Lake:

import { createClient } from '@sanity/client';

const client = createClient({
  projectId: 'your-project-id',
  dataset: 'production',
  apiVersion: '2026-01-01',
  useCdn: true,
});

const posts = await client.fetch(
  `*[_type == "post" && defined(slug.current)]{ title, "slug": slug.current, publishedAt }`
);

GROQ is genuinely powerful. It also has a learning curve, and every new engineer on your team pays it once.

Strapi exposes REST endpoints from your own instance, with GraphQL available as a plugin:

const res = await fetch(
  'https://your-app.example.com/api/articles?populate=cover&sort=publishedAt:desc',
  { headers: { Authorization: `Bearer ${process.env.STRAPI_TOKEN}` } }
);

const { data } = await res.json();

Strapi's API is conventional and quick to pick up. The cost shows up in performance work: response times depend on the instance you are running, the database you provisioned, and any caching you added yourself. Sanity's CDN handles that layer for you.

AI capabilities in 2026

This is where the two products have moved fastest, and where the fine print matters.

Sanity ships AI credits with every plan, 1,000 per month on Free and Growth, with overage billed at $0.05 per credit. Its AI features cover generation and transformation inside the editing workflow, plus embeddings and semantic search over the Content Lake.

Strapi introduced Strapi AI on the self-hosted Growth plan, also 1,000 credits per month, with additional credits at $1.50 per 100. Worth reading carefully before you commit: Strapi's own CMS pricing table lists Strapi AI as "Not yet available" in the Enterprise column at the time of writing. If AI in the editor is a requirement and you are heading toward an Enterprise contract, confirm availability with their sales team rather than assuming feature parity with Growth.

Both vendors now ship an MCP server, which lets AI coding agents read and write content through a standard protocol. Strapi announced general availability of theirs recently. We wrote about how the two approaches differ in Cosmic MCP Server vs Strapi MCP.

Pricing at realistic team sizes

Both vendors publish clear pricing, which is refreshing. The lists are not directly comparable, because Sanity's price includes hosting and Strapi's does not.

Sanity, verified August 5, 2026

Free: $0, up to 20 seats, 2 public datasets, 10,000 documents, 250,000 API requests per month, 100 GB assets
Growth: $15 per seat per month, up to 50 seats, private datasets, 25,000 documents, comments, tasks, scheduled publishing
Enterprise: custom, adds SSO with SAML, custom roles, audit trail, uptime SLA
Add-ons and overages: increased quota at $299 per month, dedicated support at $799 per month, extra datasets at $999 per dataset per month, additional API requests at $1 per 25,000, assets at $0.50 per GB

Strapi, verified August 5, 2026

Community: free forever, MIT license, unlimited entries and API calls, community support
Growth: $45 per month including 3 seats, additional seats $15 each, adds Strapi AI, Live Preview, Releases, and 30 days of Content History
SSO: a $150 per month add-on, plus $50 per month per seat
Enterprise: custom, adds Review Workflows, Audit Logs, and a SOC 2 report
Strapi Cloud hosting, priced per project: Starter $35, Pro $90, Business $450 per month, with additional environments at $60 or $300 per month depending on tier

A five-editor team, one production project

	Monthly	What is included
Sanity Growth	$75 (5 x $15)	Hosting, CDN, private dataset, 25k documents
Strapi Growth, self-hosted	$75 license (3 seats + 2 x $15)	License and features only. Your infrastructure, database, backups, and upgrade labor sit on top
Strapi Growth on Cloud Pro	$75 license + $90 hosting	Always-on runtime, weekly backups, multi-environment
Cosmic Team	$299	3 Buckets, 5 team members, 20,000 objects, fully managed

At five seats, Sanity Growth carries the lowest sticker price of the group, and we are not going to pretend otherwise. The number to watch on Sanity is per-seat scaling: twenty editors on Growth is $300 per month, and quota add-ons are priced in the hundreds. The number to watch on Strapi is the engineering time that never appears on the invoice, plus per-project hosting if you run more than one property.

Governance and compliance

Sanity puts collaboration features on Growth: comments, tasks, scheduled publishing, and 90 days of change review. SSO, custom roles, and audit trail are Enterprise.

Strapi gives Community users Role-Based Access Control for free, which is unusually generous. Content History with 30 days of retention and Releases arrive on Growth. Review Workflows and Audit Logs are Enterprise, and SSO is a paid add-on with its own per-seat charge.

If approval chains and audit trails are non-negotiable for you, price the Enterprise tier on both sides early. That is the point where headless CMS quotes stop being self-serve on either platform.

When to choose Sanity

You want structured content as a service and no infrastructure to run
You have many editors and want a low per-seat entry point
Your content graph is complex and Portable Text plus references earn their keep
Real-time collaborative editing matters to your workflow
Your team is willing to learn GROQ

When to choose Strapi

Data residency, VPC isolation, or air-gapped deployment is a hard requirement
You want an MIT-licensed codebase you can fork and extend without vendor permission
Your plugin and customization needs go beyond configuration
You have real DevOps capacity, or you are happy to pay Strapi Cloud for it
Unlimited entries and API calls at zero license cost fits your scale

Where Cosmic fits

Cosmic sits in the managed camp with Sanity, with a deliberately smaller surface area. You get a REST API and a TypeScript SDK, AI built into the editing workflow, and a dashboard that non-technical teammates can use on day one without a Studio deployment.

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

const cosmic = createBucketClient({
  bucketSlug: 'your-bucket-slug',
  readKey: 'your-read-key',
});

const { objects: posts } = await cosmic.objects
  .find({ type: 'posts' })
  .props('title,slug,metadata')
  .depth(1);

No local server, no database to provision, no GROQ to learn. Vuetify, the Vue component library with more than four million monthly npm downloads, cut server response times from 300-400 ms to about 50 ms after moving to Cosmic, with a team small enough that nobody has time to babysit a CMS.

The editorial side is the other half of it. 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.

Cosmic is a Y Combinator W19 company, and pricing is public: Free at $0 with 1 Bucket, 2 team members, and 1,000 objects; Builder at $49 per month; Team at $299 per month; Business at $499 per month; Enterprise custom. Additional users are $29 per user per month. Full details are on the pricing page.

FAQ

Is Strapi actually free?

The Community edition is free under the MIT license, with unlimited entries and API calls. Hosting, database, backups, monitoring, and upgrades are yours to fund. Growth features like Live Preview, Releases, Content History, and Strapi AI start at $45 per month with 3 seats included.

Does Sanity charge per seat?

Yes. Growth is $15 per seat per month for up to 50 seats. The Free plan allows up to 20 seats with 2 public datasets and 10,000 documents.

Does Cosmic charge per seat?

Yes. Each plan includes a set number of team members, 2 on Free, 3 on Builder, 5 on Team, 10 on Business, and additional users are $29 per user per month.

Does Cosmic support GraphQL?

No. Cosmic offers a REST API and a JavaScript/TypeScript SDK. Sanity and Strapi both offer GraphQL, so if GraphQL is a hard requirement, that is a real point in their favor.

Can I migrate off Strapi without rebuilding my front end?

Usually yes, if your front end talks to a content API through a thin data layer. We documented the process in Migrate from Strapi to Cosmic.

What if I am comparing against Contentful too?

We have those head to head as well: Sanity vs Contentful, Strapi vs Contentful, and the full field in our 2026 headless CMS comparison.

The honest summary

Pick Strapi if owning the runtime is worth the operational bill, and be realistic about who on your team pays that bill. Pick Sanity if you want a hosted content platform with a strong modeling story and a cheap seat, and budget for per-seat growth and quota add-ons. Pick Cosmic if you want managed infrastructure, a REST API with a TypeScript SDK, and AI in the editing workflow without a Studio to deploy or a Node app to patch.

You can test the third option in about ten minutes. Start building on Cosmic for free, no credit card required. If you are mid-evaluation and want a second opinion on your specific stack, book 20 minutes with our CEO.

Pricing and feature details for Sanity and Strapi were verified against their public pricing pages on August 5, 2026. Vendor pricing changes often, so confirm current terms before signing anything.

DEV Community: Tony Spiro

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

Step 3: gate on confidence

Step 4: write the answer back

What we measured

Where it was weak

What it costs

Running it without webhooks

Where this leaves the review queue

Content Durability: How to Get Everything Out of Your CMS

Backup, revision history, and export solve three different failures

What "structured" actually has to mean

Path 1: the dashboard export

Path 2: the API on a schedule

Path 3: the CLI

The part people forget: media

Backups and revisions, since export does not cover them

Run the drill once a quarter

Seven questions to ask any CMS before you sign

Where Cosmic stands

When Agents Outnumber Editors

The ratio flips faster than the process does

Shift 1: scope becomes a commissioning decision

Shift 2: review becomes the throughput ceiling

Shift 3: attribution becomes a weekly number

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

The failure modes to watch for

What this does to headcount

Getting started

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

The four stages

Stage 1: The content model

Stage 2: The agents

Stage 3: Measurement that points back at the content

Stage 4: The scheduled goal that closes it

The week the flywheel caught something we missed

What we got wrong the first time

Building your own

How to Migrate from Payload CMS to Cosmic

What actually changed at Payload

Should you migrate at all?

What you give up moving to Cosmic

Mapping Payload concepts to Cosmic

Step 1: inventory what you actually have

Step 2: export from Payload

Step 3: model your content in Cosmic

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

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