What a Headless CMS with an API and CLI Actually Looks Like (with a Working Example)

Most explanations of headless CMS stay abstract: content and presentation are decoupled, you fetch data over an API, you render it wherever you want. That's true, but it doesn't tell you what you're actually going to get back when you call the endpoint. This post shows the real shape of the data: a JSON response for a blog post, a JSON response for a custom collection entry, and where the API, SDK and CLI each fit around that data.

What a headless blog is, and what it isn't

A headless blog is a blog where the content lives behind an API instead of inside a fixed template. You write a post once, and it comes back as structured data (JSON, in almost every modern implementation) that you can render on a website, pull into a mobile app, or feed into another system entirely.

It isn't a CMS without a UI. Floggy still gives you a real editor for writing and publishing. "Headless" describes the delivery layer, not the authoring experience. The distinction that matters: a traditional CMS ties your content to its own rendering, so the content and the page are the same object. A headless CMS separates them, so the content is a record you can query, and the page is whatever you build to display it.

That separation is also what makes a headless blog usable by something other than a human clicking through a dashboard. If a post is a JSON object with a stable schema, an AI agent can write it, an API can serve it, and a script can generate ten thousand variations of it. None of that works if the content only exists baked into rendered HTML.

API, SDK and CLI: what each one lets you do that a dashboard doesn't

The API is the raw interface: HTTP endpoints that return JSON for posts, collections, and entries. Anything with the ability to make an HTTP request can read from or write to your blog. This is the layer everything else is built on, and it's the one you'd use if you're integrating Floggy content into a system that isn't JavaScript, or one you haven't built yet.

The SDK wraps that API in functions for a specific language, so instead of constructing requests and parsing responses by hand, you call something like floggy.posts.create({...}) and get a typed object back. It exists to remove boilerplate, not to add capability the API doesn't have. If you're writing a Node script or a Next.js site, the SDK is almost always the faster path.

The CLI is the API from a terminal. You publish a post, list your collections, or trigger a rebuild with a single command, without writing any code at all. This matters for two groups specifically: developers who want to script publishing into an existing workflow (a git push hook, a cron job, a CI pipeline), and AI agents that operate through shell commands rather than a browser. An agent that can run floggy publish ./post.md can run a blog on a schedule without anyone opening the dashboard.

A dashboard is built for one person clicking buttons one post at a time. The API, SDK and CLI are built for automation: many posts, on a schedule, driven by code or by an agent instead of a hand on a mouse.

A JSON example: what the API response looks like for a post and a custom collection

Here's what a real API response looks like for a blog post. Field names below are illustrative, meant to show the shape of the data, not a guaranteed schema:

{
  "id": "post_8f2a1c",
  "slug": "why-static-sites-still-win",
  "title": "Why Static Sites Still Win",
  "body": "## Speed is the feature\n\nStatic sites load fast because...",
  "excerpt": "A short case for keeping your rendering simple.",
  "status": "published",
  "published_at": "2026-07-22T09:15:00Z",
  "updated_at": "2026-07-22T09:15:00Z",
  "author": {
    "id": "user_44",
    "name": "Jordan Lee"
  },
  "tags": ["static-sites", "performance"],
  "seo": {
    "meta_title": "Why Static Sites Still Win",
    "meta_description": "A short case for static rendering in 2026."
  }
}

A blog post is one kind of record. A custom collection lets you define a different shape entirely and get the same treatment: an API endpoint, SDK methods, and CLI commands, all generated from your schema instead of hardcoded for "post." Here's an illustrative entry from a custom "product_review" collection:

{
  "id": "review_2c9d0e",
  "collection": "product_review",
  "fields": {
    "product_name": "Mechanical Keyboard X1",
    "rating": 4,
    "pros": ["Quiet switches", "Good build quality"],
    "cons": ["No hot-swap sockets"],
    "price_checked_at": "2026-08-01",
    "verdict": "Solid daily driver for the price range."
  },
  "status": "published",
  "published_at": "2026-08-01T14:00:00Z"
}

Notice the second object doesn't have a title or body at the top level. It has whatever fields you defined for that collection, nested under fields. That's the core mechanic behind custom collections: you're not stretching the blog post schema to fit data that isn't a blog post, you're defining a schema that fits.

Open source vs. hosted headless CMS: what changes for a solo developer

The practical difference for a solo developer is who runs the server and who patches it. An open source headless CMS gives you the code to self-host: you provision a database, deploy the application, manage upgrades, and handle uptime yourself. That buys you full control over the data and the infrastructure, at the cost of time spent on ops work that has nothing to do with writing content.

A hosted headless CMS, Floggy included, runs that infrastructure for you. You get the API, SDK and CLI without standing up a server, migrating a database, or handling your own backups. For someone whose priority is publishing content and building on top of the API, not running a CMS as an infrastructure project, that tradeoff usually favors hosted.

The headless CMS space includes both models, from fully open source projects to hosted platforms with varying degrees of openness, and the right choice depends on how much infrastructure work you actually want to own. There's no single "leading" answer that holds for every use case: a team that needs to self-host for compliance reasons has different requirements than a solo developer who wants to npm install an SDK and start publishing the same afternoon.

Custom collections: going beyond blog posts to structured, programmatic content

A custom collection is a schema you define yourself, so your CMS can hold any kind of structured record, not just blog posts. Think of it as a table: you specify the fields (text, numbers, dates, lists, references to other entries), and every entry in that collection follows the same shape, exactly like the product_review example above.

This is what makes programmatic SEO practical on top of a CMS built for blogging. If you're generating a hundred city landing pages, a directory of tools, or a set of comparison pages, each of those is a natural fit for a custom collection: define the fields once, then create entries in bulk through the API, the SDK, or a script driven by an AI agent. The CMS handles storage and delivery; your code or your agent handles populating the entries and deciding what goes in each field.

The same API and CLI you use to publish a blog post apply here. You're not learning a second system for structured content. You're pointing the same tools at a different schema, which is the actual advantage of a headless CMS with custom collections: one publishing pipeline that scales from a personal blog to a few thousand programmatically generated pages, without switching platforms in between.