TL;DR
The standard API-first project changes the delivery format and leaves the unit of publication alone. That is why so many of them produce no measurable gain: page-shaped content moved into a system that serves page-shaped JSON.
A document answers the questions its author thought of. An interface answers questions the caller composes — and most of the questions retrieving you in 2026 were never typed by anyone.
Server-rendered HTML is your primary machine interface. Vercel and MERJ found no major AI crawler executes JavaScript, so a decoupled front end can make you less readable, not more.
Every field you publish as data is a promise. Publish the fewest fields you are willing to keep true, and write the deprecation policy the day you publish them.
The link-building payoff is not agent traffic. It is that data reused under an attribution licence produces a citation that renews on every refresh.
The advice that skips the expensive half
The 2026 advice to site owners is compact and close to unanimous. Go API-first — store your content as structured records and deliver it through an interface rather than baking it into pages — so that humans and AI agents can be served from one source. Expose a content API. Ship an MCP server (Model Context Protocol, a standard way for assistants to call external tools). Publish feeds. The promise is a single source of truth feeding every surface at once, and it is repeated in almost every modern content strategy playbook written since the answer engines arrived.
Two findings should stop that project as it is usually scoped. Postman’s 2025 State of the API report, a survey of more than 5,700 developers, architects and executives, found 24.3% of developers already designing APIs with AI agents in mind — and 60% still designing primarily for humans only, with 16% who had not considered agents as consumers at all. The interface half of the promise is early, thinly populated and largely uncalled.
The second finding is worse. Vercel and MERJ, analysing more than 500 million GPTBot fetches across Vercel’s network, found no evidence of JavaScript execution by any major AI crawler. GPTBot downloaded JavaScript files in roughly 11.5% of its requests and ClaudeBot in roughly 23.84% — and neither ran them. Googlebot renders, which is why Gemini can read a client-side application and the others cannot. If you rebuilt your front end as a JavaScript app during the same project, you did not improve your crawlability; you removed it.
Put those together and the standard implementation has a recognisable shape: a new machine surface almost nobody calls, sitting behind a rebuilt human surface that several important machines can no longer read. Both halves fail for the same reason. The project was scoped as plumbing.
API-first is not a decision about delivery format. It is a decision about the unit of publication — and the format is the cheap half. The one thing an interface can do that a document cannot is let somebody else choose the unit. Almost every implementation skips exactly that.
What is API-first publishing?
Storing content as structured records in a system whose primary output is data, then rendering pages, feeds and applications from those records. The distinction that matters is not JSON versus HTML. It is whether the smallest thing you can publish is smaller than a page.
The unit of publication
Your unit of publication is the smallest thing you can change on its own, and the smallest thing somebody else can ask for. On most sites both answers are the same: a page. That was a perfectly good arrangement while the retrieval unit was also a page and the query was a string a person typed. Neither condition holds now.
The questions arriving are not questions you can write pages for
Query fan-out — the expansion of one prompt into many parallel searches — has been measured repeatedly and the numbers agree on the shape. Seer Interactive ran 501 tracked prompts through the Gemini 3 API in 2026 and recorded an average of 10.7 fan-out queries per prompt; 95% of the sub-queries Gemini generated had zero global search volume. Nectiv Digital’s analysis of more than 60,000 Google fan-out queries found 59% of prompts triggered between five and eleven searches and 24% triggered twelve to nineteen, with software prompts averaging 11.7 and local prompts a shallower 3.79. Ahrefs reports AI Mode typically firing five to eleven sub-queries, and separately watched ChatGPT Deep Research run 420 searches to answer a single shopping question.
The finding that matters most for architecture is Surfer SEO’s December 2025 study: only 27% of fan-out sub-queries stayed stable across repeated runs of the same term. The other 73% came back worded differently. So the questions that retrieve you are mostly questions nobody typed, that keyword tools cannot show you, and that change between runs. A page-per-question strategy is not expensive. It is undefined — there is no stable list to write against, which is a large part of why the old ranking audit stopped predicting anything useful.
The same pressure arrives from the other direction inside a conversation. A session that opens with a broad question and narrows across four turns poses a different retrieval problem at every turn, and the page that satisfies the first is rarely the one that satisfies the fourth. That is why the shape of a multi-turn session now predicts citation better than the head term does — and why the clicks stay flat even in the months when citations rise.
What survives that volatility is not a page. It is a fact stored in a form that can be assembled into an answer regardless of how the question was phrased on the day.
Instrument 1 — the recomposition test
1. Take an actual fan-out run against a prompt you care about — from a fan-out tool or by inspecting the sub-queries in an AI Mode session — and write down ten sub-queries. Not keyword-tool output. Real decomposition.
2. Pick three you have never written a page for.
3. Answer each one from what you already store, without writing new prose.
4. Grade the outcome. NARRATED — the fact exists only inside sentences on a page. PAGE-SHAPED — it is stored, but only retrievable as a whole document. RECOMPOSABLE — it is stored as a value that can be selected, compared and re-emitted in a shape nobody planned.
The rule: if answering required writing, the fact was never stored. It was narrated.
Most sites grade NARRATED on nearly everything, and it is worth being precise about what that means, because it is not a content-quality problem. The prose is usually good. The prose is simply where the facts are imprisoned. For example, a UK commercial insurance broker keeps its answers to “do you cover this trade” inside six long guides. A sub-query asking about one specific trade has no page to match and no field to read. The same answers held as a coverage record — trade, covered or not, conditions, effective date — satisfy dozens of sub-queries nobody anticipated, and still render the same six guides.
Key takeaway
You cannot write a page per sub-query, and chasing individual strings wastes the budget. You can store facts at a unit small enough that pages, feeds and answers are all compositions of the same records.
What “create once” actually meant
None of this is new thinking. NPR launched its content API in 2008, and Daniel Jacobson published the reasoning in 2009 under the name COPE — Create Once, Publish Everywhere. Jacobson went on to run the Netflix API and wrote O’Reilly’s APIs: A Strategy Guide. The architecture being sold as an answer-engine strategy in 2026 is seventeen years old, and its author’s warnings are the part that gets left out.
NPR’s stated principles included “Don’t attempt to build the ‘One System’” and a hard distinction between a content management system and a web publishing tool — a tool that stores pages rather than content. The lessons Jacobson listed afterwards were about flexible content structures, worked examples rather than documentation, and keeping the editorial and technical teams aligned. Not one of them is about delivery.
The industry heard “publish everywhere” and built more output channels. The leverage was always in “create once”, which is a claim about the unit, not about the number of destinations. A system that stores pages can be given as many outputs as you like, and it will emit pages in different envelopes.
The money has since caught up with the idea. Salesforce agreed on 1 June 2026 to acquire Contentful, a composable content platform used by more than 4,800 enterprise brands; Mordor Intelligence sizes the headless CMS market at $1.82 billion in 2026, rising to $4.42 billion by 2031. A purchase order, though, is not an architecture. Buying a system whose primary output is data does not by itself make your content data.
Why do most API-first rebuilds produce no visible gain?
Because they move page-shaped content into a system that serves page-shaped JSON. The delivery format changed and the smallest publishable thing did not, so nothing downstream can ask a question it could not ask before.
The mirror problem
If your content API returns one record per page, with a title, a slug, a date and a body of HTML, you have not built an interface. You have built a mirror — a photocopier with a URL. It is genuinely useful for rebuilding your own website and it adds no answerable question to the world.
The diagnostic is to list every surface that consumes your content and write down the unit each one actually takes. The failure signature is visible in seconds.
| Surface | Unit it takes today | Unit it should take | Failure signature |
| Guide or article page | Document | Document composed of records | Key figures retyped into prose and stored nowhere else |
| Product or service page | Document | One record per attribute | A spec change means editing page copy |
| On-page module (price, hours, spec box) | Document | Fields | The same value sits on 40 pages with 40 owners |
| Site search and internal retrieval | Document | Passages plus fields | Search returns pages, never answers |
| Public feed or endpoint | Document | Records | The endpoint returns whole articles |
| Partner embed or syndication | Document | Records plus licence terms | The partner pastes once, then drifts out of date |
Read the second column downwards. If it says “Document” all the way down, you have one output rendered several ways, which is what you had before the rebuild. This is also the cheapest technical audit in the discipline: it takes an afternoon and it tells you whether the next six months of engineering will change anything.
The second column has a cost attached that rarely appears in the business case. A trade distributor auditing its own site found a single certification number printed on 40 pages, held in a sales spreadsheet, embedded in three PDF datasheets and stored in the ERP. The version on the website had been wrong for five months. Nobody had edited it incorrectly. There was simply no place where it was edited — the number existed in six copies and belonged to none of them. Stale facts of exactly this kind are what feed the misinformation you later have to correct, at far greater expense than the extraction would have cost.
Server-rendered HTML is your primary machine interface
There is an irony at the centre of the decoupled architecture. Separating the content store from the front end puts a renderer between your facts and your readers. If that renderer runs in the visitor’s browser, it runs for humans and for Googlebot, and it stops there.
The traffic on the other side of that line is not marginal. In the month Vercel studied, GPTBot generated 569 million requests across its network and Anthropic’s crawler 370 million — together about 20% of Googlebot’s 4.5 billion over the same period. Those requests read the raw HTML response and move on. Server-side rendering, which means building the HTML before it leaves your server, is not a performance optimisation in this context. It is the difference between having a machine interface and not having one.
The useful corollary is that anything present in the initial HTML response is readable — including data embedded as inline JSON alongside the visible copy. Your page is already a data interface, whether or not you ever build an endpoint, and it is the one with the largest verified consumer base and the best-documented fetch behaviour. It is also the surface agentic browsers land on when a user sends one to check something on your site.
That reorders the build. The first customer of your content API is your own website. If the records cannot assemble your existing pages, they cannot assemble anything else either, and a public endpoint built before that point is a guess dressed as infrastructure. It also sets the standard for how each composed section should read: self-contained, answerable on its own, in the extractable form that retrieval systems can lift without the surrounding page.
Key takeaway
The page is not the legacy surface you are migrating away from. It is the machine-readable surface with the largest measured audience — and a decoupled front end can quietly take it away from you while the project is described as making you more machine-readable.
An interface is a promise: the contract ratchet
Prose can be vague. A field cannot. “Most orders ship within a week” is a sentence you can revise on a slow Tuesday. dispatch_days: 5 is a claim that other people will build on, and once they have, the sentence and the field behave completely differently under change.
This is the asymmetry the enthusiasm skips. Publishing a page creates no obligation to anyone. Publishing a field creates obligations to every party that consumes it — parties you never contracted with, whose systems break when you remove the field and break silently when you rename it. You acquired counterparties by shipping a schema.
The industry manages that badly. Postman’s 2025 survey found 60% of teams version their APIs while only 26% use semantic versioning: most teams track that something changed without communicating what the change costs the people downstream. There is a standard for the communicating part, and it is close to unused among publishers.
The same survey found 93% of API teams reporting collaboration problems, 55% naming documentation gaps and 35% naming duplicated effort. That is worth sitting with, because a single source of truth is precisely what the architecture was sold as delivering. Consolidating storage does not consolidate knowledge: if nobody can establish what a field means without asking the person who built it, the ambiguity has been moved rather than removed.
RFC 9745, the Deprecation HTTP response header field (Standards Track, March 2025, from Sanjay Dalal and Erik Wilde), signals that a resource has been or will be deprecated. It changes no behaviour — the specification is explicit that it is a hint, and consumers can keep using the resource exactly as before. RFC 8594’s Sunset header, published in May 2019, states when the resource will stop responding, and RFC 9745 requires the sunset timestamp to be no earlier than the deprecation one. A registered deprecation link relation points at the human-readable notice explaining what to do instead. Two headers and a link: the entire cost of not breaking your consumers by surprise.
Instrument 2 — the contract ratchet
1. Additive by default. New fields are free. Removed and renamed fields are not. Anything you cannot add without breaking a consumer belongs in a new version rather than in the current one.
2. No field without an owner. Every published field names a person, a check frequency and a correction deadline. A field nobody owns eventually becomes a wrong answer with your name attached to it.
3. The fewest fields you are willing to keep true. Publish the smallest set you can defend indefinitely, not the set your CMS happens to hold. Every extra field is a standing liability, not an asset.
4. Write the retirement before the launch. Deprecation and Sunset headers plus a dated notice page, decided on the day the field ships — not during the incident when you remove it.
What does it cost to publish a field?
One correction cycle per change, indefinitely, plus the deprecation notice you owe consumers when you retire it. That is the price to weigh before exposing sixty fields because the content model already contains them.
The failure mode is quieter than an outage. A recruitment site exposed salary_max in a public feed and later changed its meaning from an annual figure to a daily rate for contract roles, without a version bump — the field name never changed, so nothing broke. Three aggregators went on publishing numbers roughly 250 times too large, each of them correctly attributed to the source. No error was ever returned. The monitoring stack most teams run would not have caught it, because nothing was down.
Build order: inside out
The common sequencing error is building the external interface first, because that is the part that looks like the future. Run it in the other direction and every stage pays for itself before the next one starts.
- Extract. Move facts out of prose into records. Nothing about the site changes. Exit condition: a single-change count of one — the number of places you must edit to change one fact — across your ten most-referenced fact classes.
- Compose. Generate the existing pages from those records, server-side. Nothing new ships and no URL changes. Exit condition: a change to a record is live everywhere it appears within one build.
- Feed. Expose a read-only feed covering the fact classes a named third party has actually asked for. Exit condition: at least one external consumer in production.
- Protocol. An MCP server, an agent manifest, whatever the protocol layer looks like when you arrive. Exit condition: demand you can name and a consumer you can email.
Stage four sits last for a reason that deserves honest numbers rather than dismissal. A pull from the official MCP registry API on 24 May 2026 returned 9,652 latest server records and 28,959 server-and-version records; Anthropic’s December 2025 ecosystem update cited more than 10,000 active public servers; independent censuses range from roughly 9,600 to 17,500 depending on what counts as a server, and at least one research team revised its own published adoption figures downwards on review. Stacklok’s 2026 software report puts 41% of surveyed software organisations at limited or broad production use of MCP servers. The ecosystem is real, it is growing quickly, and a registry entry is a statement of intent rather than evidence that anything called your server. Those are different claims and they are constantly conflated in adoption statistics.
Stage three is where the shape of the feed matters more than the technology behind it. A read-only endpoint returning dated records with stable identifiers, a documented refresh interval and an explicit licence is worth more than a sophisticated one that returns prose, because a feed a machine can rely on is judged on predictability rather than expressiveness. Publish the update cadence and then meet it. A feed that silently goes stale is worse than no feed at all, because consumers carry on serving the old values under your name.
The stop rule is the useful part: do not advance a stage until the previous stage has a consumer. Stage two has one by definition — your own website. Stages three and four have to earn theirs, and a colleague’s enthusiasm is not a consumer.
Worked example: Calderbeck Building Products
Calderbeck is a Leeds distributor of fire-rated panels and cladding: 340 products, about 2,100 pages, two marketing staff and a developer on retainer. The figures below are a composite of a familiar failure pattern, not a client file, but every number is the kind you can measure on your own site this week.
Week 0: the audit
- Certificate numbers and reaction-to-fire ratings lived in six places: page body copy, a sales spreadsheet, 340 PDF datasheets, a printed catalogue, the ERP and a partner price list. Single-change count: six systems, and up to 40 pages for the most-referenced products.
- Mean lag from a certification body updating its register to the website reflecting it: five weeks.
- Eleven of 340 certificate numbers on the site did not match the certifier’s public register. The oldest mismatch was fourteen months old.
- The specification tables were loaded by JavaScript after the page rendered, so the raw HTML for every product page contained no specifications at all.
Weeks 1–16: the rebuild
Weeks one to four extracted nine fact classes into records: certificate number, issuing body, expiry date, reaction-to-fire class, thickness, core material, U-value, lead time and unit of sale. Weeks five to ten composed all 340 product pages from those records, server-side, with no URL changes — single-change count fell from six to one, and the eleven stale certificates went to zero, with an overnight re-check against the register that now flags a mismatch within 24 hours.
Weeks eleven to fourteen exposed a feed containing exactly two fields, certificate number and expiry date, because a merchant partner had asked for those two. Six other fields the system could have emitted were held back: nobody had requested them and nobody wanted to own them. Weeks fifteen and sixteen assigned an owner and a correction deadline to each published field and wrote the deprecation policy.
Week 28: what actually moved
On a fixed 30-prompt panel run monthly, answers naming the brand on product-level questions went from four to nine across twelve weeks. That is real and it is small, and the same period included the server-rendering fix, so the two cannot be cleanly separated. Anyone reporting that number as a citation win from API-first publishing would be overclaiming.
The attributable result was different in kind. Three merchant partners took the certificate feed. Each now publishes a compliance page carrying the agreed attribution string and a link back, rebuilt nightly from the feed. Those pages did not exist before, they are not one-off placements, and they do not decay — which makes them behave nothing like the placement-by-placement acquisition the rest of the budget was funding. The unforecast benefit was internal: sales stopped maintaining the spreadsheet that had been generating the wrong numbers in the first place.
Attribution is a citation that renews
Most earned-link assets are one-shot. A study earns coverage in a window and decays; a calculator or interactive tool keeps earning for longer but still depends on somebody deciding to write about it again. Reusable data behaves differently, because with data the credit is a condition of use rather than a favour.
The licence you choose decides whether that condition exists at all. Open Data Commons’ ODC-BY permits copying, use and modification on condition the source is credited; ODbL adds a share-alike requirement that commercial reusers tend to refuse; CC0 and PDDL waive rights entirely and impose no attribution at all. In the UK, the Open Government Licence is an attribution licence covering both copyright and database right, which is why public-sector data reuse so reliably carries a named credit. The Open Data Institute’s reuser guidance is specific about the shape of that credit: give the publisher’s name and a link, and where practical carry the attribution on every page or screen where the data is used.
Follow that through. A licensed feed produces a credit that is rebuilt each time the partner refreshes, on every new surface they build with it. It is the closest thing in the discipline to a citation with a renewal clause, and it changes the shape of your acquisition curve from a series of spikes into something closer to a subscription.
How to run it as an outreach programme
- Choose the licence deliberately. CC0 maximises reuse and buys you nothing back; if the point is attribution, use an attribution licence and say so in the same sentence as the download link.
- Write the attribution string and the exact target URL into the licence text. Do not leave the anchor to the reuser’s imagination — a credit pointing at your home page is worth considerably less than one pointing at the dataset.
- Pitch the feed to the people already retyping your numbers. Anyone citing you without a link is the warmest list you have, and the offer — stop retyping, take the feed, keep the credit — is easier to accept than a guest post.
- Treat trade bodies, merchants and comparison sites as feed consumers rather than link targets. That reframing is what turns an ordinary partner relationship into a standing citation.
Two honest caveats. An attribution licence binds licensees, not scrapers, and enforcement against a non-compliant reuser is a nuisance rather than a remedy — the value is that well-behaved reusers now have a written instruction telling them what to publish. And a feed is not a licensing strategy for AI training corpora, which is a separate negotiation with a separate set of terms and a different counterparty entirely.
Where this argument breaks
The strongest objection is not that interfaces are unnecessary. It is that the sequencing is conservatism wearing architecture’s clothes: protocol adoption is discontinuous, so by the time demand is nameable the integration slots are filled — and the research evidence points the other way. Carnegie Mellon researchers Yueqi Song, Frank Xu, Shuyan Zhou and Graham Neubig tested API-based web agents against browsing agents on WebArena and found the API-based agents outperformed browsing, with hybrid agents beating both by more than 24 percentage points in absolute terms over browsing alone, reaching a 38.9% success rate — the best result then recorded for task-agnostic agents. If agents demonstrably do better with an interface, build the interface.
That evidence should be taken at face value, and the concession is real. But read which arm won. The hybrid agents — using the interface and the page together — beat both pure approaches. That is a complements result, not a substitutes result, and it is precisely the reading being defended here: the page and the records are two views of one store, and a team that has done the extraction can serve both. The argument was never that interfaces do not work. It is about order and about scope.
The timing objection also carries a genuine carve-out. If your facts are transactional — price, stock, availability, appointment slots — the demand is already observable, agentic commerce is already reading those fields, and the interface belongs in stage two rather than stage three. Data that changes hourly and is meant to be transacted against will never be well served by a page.
What holds for everyone else is the asymmetry in what gets wasted. Decomposition is protocol-agnostic: records survive whichever envelope wins, and they pay for themselves in correction cost before any agent arrives. An interface is protocol-specific and its shape is still moving — keep it thin enough to re-emit. And the sequencing does not delay the interface so much as change what building it costs. A team that has finished stage one can ship a protocol surface in a fortnight. A team that has not will spend those two weeks writing extraction code and calling it an AI visibility strategy.
The Monday checklist
- Run a fan-out against your three most valuable prompts and write down ten sub-queries you have never published a page for.
- Apply the recomposition test to three of them and record the grade: narrated, page-shaped or recomposable. Expect narrated.
- Count the single-change number for your five most-referenced facts — the number of places you must edit to change one of them. Anything above one is a future wrong answer.
- View source on your five highest-value pages and search for a sentence of the main content. If it is not there, fix that before anything else on this list; nothing downstream matters while the raw HTML is empty.
- Pick the nine fact classes that carry the most weight, extract them into records, and compose the existing pages from them. Ship no new pages during this stage.
- Before exposing any field publicly, name its owner, its check frequency and its correction deadline — then write the deprecation policy, with RFC 9745 and RFC 8594 headers, on the day it launches.
- Ask the three organisations already reusing your numbers which two fields they want, and licence those under attribution with the credit string and target URL specified.
Failure threshold
If after two quarters your records exist, your pages compose from them and no external party has asked for a feed, the constraint is demand rather than architecture. Stop at stage two — you have already banked the correction cost and the rendering fix — and move the remaining budget to earned coverage. The fundamentals of link acquisition outperform an unused endpoint every time, and the records will still be there when demand shows up.
The version of this project that fails is the one measured by what it ships: an endpoint, a manifest, a migration announcement. The version that works is measured by what it makes possible — a question you can now answer that you never wrote down, a number that can only be wrong in one place, a partner who cannot use your data without naming you. Decide which of those you are building before the first sprint, because the two look identical in the planning document and nothing alike eighteen months later.
