Git-Backed or API-Backed: Where Should Your Content Actually Live?

Two teams pick a headless CMS in the same month. One stores every article as a file in the site’s own repository. The other stores it in a hosted database and fetches it over an API at build time. Twelve months later, one of them can answer "who changed this sentence, and why" in about four seconds. The other is emailing support.

That is the whole argument in one paragraph, and it is why the storage question deserves more attention than the feature matrix that usually decides these things. Editors do not care whether content sits in Git or in Postgres. But every consequence they do care about (speed, safety, review, rollback, and the cost of leaving) falls out of that one choice.

Neither model is better. They fail differently, and the right answer depends on facts about your team you already know. This piece is about getting from those facts to a decision without a six-week evaluation. It sits underneath the more familiar argument about headless versus traditional, which is a different question wearing similar clothes.

The question underneath the question

When someone asks which CMS to use, they are usually asking four things at once: what can editors do without help, what can break, how do we get the content out again, and how much of this becomes an engineering ticket. A feature list answers none of them.

So start somewhere more useful: where the words physically sit when nobody is looking at them. Everything else is a layer over that: the editing interface, the preview, the approval step. Layers are replaceable. Storage is not.

What Git-backed actually means

In a Git-backed system, an article is a file (Markdown, MDX, JSON, YAML, occasionally TypeScript) committed to the same repository as the code that renders it. Publishing is a commit. Deployment is whatever that repository already triggers. The Git history is the content history, because there is only one history.

What you get

• One audit trail. Every word change carries an author, a timestamp, a diff and usually a reason. Nobody has to build reporting for this; it is the storage format.
• Review that already exists. A pull request is an approval gate your engineers already understand, and it can genuinely refuse to publish something.
• Rollback in one command. Reverting a bad publish is reverting a commit. There is no restore-from-backup conversation.
• No runtime dependency. If the vendor disappears on a Tuesday, the site still builds. The content was never anywhere else.
• An exit that costs nothing. The export is a clone. You already have it on three laptops.

What you give up

Publishing is coupled to a build. That is fine at a hundred pages and irritating at fifty thousand, where a full rebuild stops being something you do casually. Scheduled publishing needs a mechanism of its own, whether a cron job, a scheduled workflow or a timed deploy, because a file does not become live by sitting there with a future date on it.

And the raw experience is hostile to non-technical editors. Nobody outside engineering should resolve a merge conflict to fix a typo. This is exactly the gap a content workspace fills: a tool like Acrosite gives editors a structured interface, then generates the files, commits them to GitHub and triggers the configured deployment, so storage stays Git while the editing experience stops looking like it.

What API-backed actually means

In an API-backed system, content lives in the vendor’s database. Your site asks for it over HTTP, at build time or at request time or both. The CMS owns the schema, the editing interface, the media library, the roles, and the record of who changed what.

What you get

Editors get a real application on day one: live collaboration, structured fields, localisation, scheduled publishing, asset handling, granular roles. Content updates without a deploy, which matters enormously if you publish many times a day or run a large e-commerce catalogue where a rebuild per price change is absurd. The same content also serves an app, a kiosk and a partner feed without anyone inventing a second pipeline.

What you give up

You take on a runtime dependency and a bill that scales with traffic or seats. Your content history is whatever the vendor decided to keep, in whatever interface they decided to build, for as long as you keep paying. Local development needs either network access or a mocking layer somebody has to maintain.

The one to look at hardest is the exit. Ask, before signing, exactly what a full export produces: which fields, which relationships, which media, in which format, and whether the answer changes on a cheaper plan. A system with no clean export is a system you have quietly agreed never to leave. We have written separately about what happens to your content when you leave a CMS, because it is the question that gets asked last and should be asked first.

The comparison that matters

Vendor tables compare features. The differences that actually show up in the second year are these.

Five questions that settle it

Answer these honestly, in order. Most teams know before question four.

1. Who publishes, and can they use Git? Not "could they learn" — will they, on a Friday, under deadline? If the honest answer is no, you need an API-backed CMS or a workspace layer over Git. Not raw Git.
2. How often does content change? A few times a week suits a build. Continuously, from many people, does not.
3. How many pages, realistically, in three years? Full-rebuild times grow with the page count. Incremental builds help, but the ceiling is real and it arrives without warning.
4. Does anything else consume this content? One website is a weak argument for an API. A website plus an app plus a partner feed is a strong one.
5. What does leaving cost? Price it now, while nobody is annoyed and you still have room to negotiate. This question has ended more evaluations than any other.

Choose the storage model for the constraint you cannot design around. Everything above it is a layer, and layers get replaced.

The hybrid almost nobody names

Most real sites are already hybrids and have not admitted it. Marketing pages sit in the repository because they change monthly and want review. Product data comes from an API because it changes hourly and nobody wants a deploy for a stock level. Support articles live somewhere else entirely.

That is a legitimate architecture, provided it is deliberate. The rule we apply: split by change frequency and ownership, never by page type. Content that changes on the same rhythm, edited by the same people, belongs in the same system. Splitting one editorial team across two tools to satisfy a diagram is how you end up with two half-maintained content models and a migration in eighteen months.

The connected question, whether you are choosing a system or a workflow, is one our parent company has written about directly in where drafts live and what stops them, and the storage argument itself in Git-based CMS or API-based CMS.

What the choice changes downstream

This decision propagates further than teams expect. It sets whether technical SEO fixes ship in an afternoon or wait for a sprint. It decides whether a typo on a legal page is a two-minute edit or a release. It decides whether staging can hold realistic content, and whether a designer sees real words before launch.

It also decides what a redesign costs. Content stored as typed fields can be re-rendered into a new design; content stored as a wall of pasted HTML can only be reformatted by hand, page by page, forever. That is a modelling distinction rather than a storage one, but Git-backed systems tend to force the modelling conversation early, and hosted editors with one big rich-text field tend to let teams avoid it until it is expensive.

What this looks like on a real migration

Take the most common case we see: a marketing site on a mature platform, four hundred pages, three editors, a developer available two days a week. The team is unhappy for reasons that have nothing to do with storage. Publishing is slow because every change goes through one person. Nobody trusts staging. Two of the four hundred pages are legally sensitive and nobody can say who approved the current wording. The proposed fix is a new CMS.

A new CMS fixes at most one of those. The bottleneck is an approval habit, the staging problem is an environment problem, and the legal-page question is an audit-trail problem. Only the third is answered by the storage model, and it is answered completely: in a repository, "who approved this wording" is a two-command question with a name and a date attached. That is why the storage decision belongs in the conversation, and also why it should not be asked to carry the whole conversation.

The sequence we would run: fix the approval gates first, because that is free and it changes daily life immediately. Then model the content, because that decides how much of the migration is mechanical. Only then pick a system. Teams that do it in the other order pay for the same migration twice, and the second one is worse because it carries the first one’s compromises.

One more thing worth saying plainly: the platform you are leaving is rarely the villain. A well-run site on an unfashionable stack beats a badly-run site on a fashionable one every day of the week, and the difference is almost always whether somebody owns publishing rather than what the publishing runs on.

Where we would start

For a marketing site under a few thousand pages, edited by a small team, with review that matters and a long life ahead of it: Git-backed, with a workspace layer so editors never see a terminal. The audit trail and the zero-cost exit are worth more than the conveniences you trade away, and both compound.

For a large catalogue, continuous publishing, several consuming surfaces, or a team already productive inside a hosted editor: API-backed, with the export tested (actually run, not merely promised) before you commit.

And if you are somewhere between, choose the model that makes your worst month survivable rather than your best month elegant. Systems get judged on the day something goes wrong, not the day the demo goes well. If you want a second opinion on a specific stack, tell us what you are running and what keeps breaking.