Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Explainers · Explainer

What Is Headless WordPress? A Plain Explanation

What Is Headless WordPress? A Plain Explanation

Short answer

Headless WordPress is WordPress used only as the content back end, while a separate front end fetches that content through an API and renders the pages. Editors keep working in wp-admin, while visitors see pages built by an app such as Next.js or Astro. The built-in REST API and the WPGraphQL plugin provide the two main ways to fetch the content.

Key takeaways

  • Headless WordPress keeps WordPress as the content back end and moves the front end to a separate app.
  • The built-in REST API sends and receives content as JSON and is the foundation of the block editor.
  • WPGraphQL adds a GraphQL API, so a front end can ask for exactly the fields it needs in one query.
  • Public content is public through the API too; private content needs authentication, just as in WordPress itself.
  • Headless fits sites that feed several front ends from one back end, not small sites where a theme already works.

What is headless WordPress?

Headless WordPress is WordPress used only as the content back end, while a separate front end fetches that content through an API and renders the pages.

In a normal WordPress site, WordPress stores the content and also builds the HTML pages that visitors see.

In a headless setup, WordPress still stores the content and still provides the admin screens, but the theme layer is gone. A separate app, often built with a JavaScript framework, asks WordPress for content and draws the pages itself.

The name comes from the split. The “head” is the front end that visitors see, and removing it leaves the “body”, which is WordPress as a content store. Editors keep using wp-admin, while visitors never touch a WordPress theme.

The REST API Handbook on developer.wordpress.org states that the WordPress REST API provides an interface for applications to interact with your WordPress site by sending and receiving data as JSON objects. That interface is what makes the headless setup possible.

How does headless WordPress work?

Headless WordPress works in three steps: editors publish in wp-admin, the front end asks the API for that content, and the front end renders the page.

WordPress stores posts, pages, media, users, and taxonomies as usual. The front end then sends HTTP requests to the API and gets JSON back. The REST API Handbook states that the API provides REST endpoints, which are URLs representing the posts, pages, taxonomies, and other built-in WordPress data types.

The front end can live on a different server or even a different host.

It can be a Next.js app, an Astro site, a SvelteKit app, or a mobile app. The WPGraphQL plugin page on WordPress.org states that WPGraphQL works with any client that can make HTTP requests to the GraphQL endpoint, and that it integrates with frameworks like Next.js, Gatsby, and Astro.

Caching sits between the two parts. The front end usually caches API responses, so a popular page does not ask WordPress for the same content on every visit. When an editor publishes a change, the front end clears the cached copy and fetches the new version.

What is the REST API?

The REST API is the built-in WordPress interface that lets outside apps read and write your site's content as JSON.

The REST API Handbook states that the API is the foundation of the WordPress Block Editor, and that it can enable your theme, plugin, or custom application to present new interfaces for managing and publishing your site content.

The block editor itself uses the API to save posts, which shows that the API is part of normal WordPress, not an add-on.

REST stands for Representational State Transfer. The handbook states that REST is a set of concepts for modeling and accessing your application's data as interrelated objects and collections. In practice, that means each kind of content has its own URL, and your app sends and receives JSON at those URLs.

You do not need to install anything to use it.

The API ships with WordPress, and the handbook states that you can build a brand new interactive front-end experience, or bring your WordPress content into completely separate applications. Our guide on how to create a custom REST API endpoint in WordPress shows how to add your own routes.

What is WPGraphQL?

WPGraphQL is a free plugin that adds a GraphQL API to WordPress, so a front end can ask for exactly the fields it needs in one query.

The WPGraphQL plugin page on WordPress.org states that WPGraphQL is a free, open-source WordPress plugin that provides an extendable GraphQL schema and API for any WordPress site.

The same page lists its key features: a flexible API to query posts, pages, custom post types, taxonomies, users, and more, plus an extendable schema.

GraphQL differs from REST in how you ask. With REST, each kind of content has a fixed endpoint, and you may need several requests to gather a page.

With GraphQL, you write one query that names the fields you want, and the server returns only those fields. The plugin page states that WPGraphQL lets you fetch exactly the data you need in a single query.

WPGraphQL is moving toward a formal role in WordPress. The plugin page states that WPGraphQL is becoming a Canonical Plugin on WordPress.org, ensuring long-term support and a growing community of users and contributors. It also states that the plugin is supported by contributors, backers, and sponsors, including Automattic.

REST API or WPGraphQL: which should you use?

Use the REST API for simple content sites and WPGraphQL when pages combine many related pieces of content.

The REST API is the safer default.

It ships with WordPress, so there is no extra plugin to install, update, or keep secure. The REST API Handbook states that any programming language which can make HTTP requests and interpret JSON can use the REST API, from PHP, Node.js, Go, and Java, to Swift, Kotlin, and beyond.

WPGraphQL fits pages that pull together many related types at once, such as a post with its author, categories, related posts, and featured image.

One GraphQL query can fetch all of those, while REST may need several requests or extra parameters. The plugin page states that WPGraphQL works with Next.js, Astro, and SvelteKit, among other frameworks.

ChoiceWhat you getBest fit
REST APIBuilt into WordPress, fixed endpoints, JSONSimple sites, apps, and integrations
WPGraphQLOne query for exactly the fields you needPages that combine many related types
REST APINo extra plugin to maintainTeams that want the smallest setup
WPGraphQLTyped schema that documents the dataTeams already using GraphQL tools

The plugin page lists the latest WPGraphQL version as 2.29.0 as of November 2026. If you choose WPGraphQL, install it with wp plugin install wp-graphql --activate, as the plugin page instructs, and keep it updated like any other plugin.

When does headless WordPress make sense?

Headless WordPress makes sense when you need the same content on several front ends, or when your team already builds front ends with a JavaScript framework.

A common case is one WordPress back end feeding a website, a mobile app, and a second site at the same time.

Each front end asks the same API for the same posts, so editors publish once and all three show the change. The REST API Handbook states that the API can bring your WordPress content into completely separate applications.

Another case is a team that wants full control over the front end. A JavaScript framework gives developers control over routing, caching, and rendering that a WordPress theme does not offer in the same way. Our guide on headless WordPress vs traditional WordPress compares the two setups in detail.

Headless also fits sites that need content in many places. A store could show the same product posts on its site, in its app, and in a partner's widget, all from one WordPress install.

When should you stay with traditional WordPress?

Stay with traditional WordPress when your site is a blog, a business site, or a small store, and a theme already does what you need.

Traditional WordPress is simpler to run. One install holds the content, the theme, and the pages, and plugins handle caching, forms, and SEO in the same dashboard. A headless setup adds a second app to build, host, secure, and keep in sync with WordPress.

Headless also drops some WordPress features. Live preview, many plugins that print HTML into pages, and theme-based tools expect a WordPress front end, so they may not work, or may need extra code. Our guide on how to build a headless WordPress site walks through the setup before you commit.

Cost is a second reason to stay traditional. A headless site needs hosting for WordPress and hosting for the front end, plus developer time for both. A small site rarely gains enough from that split to pay for it.

Is headless WordPress secure?

Headless WordPress follows the same access rules as normal WordPress, but the API becomes a new surface to protect.

The REST API Handbook states that the API implements the same authentication restrictions as WordPress itself.

Content that is public on your site is generally publicly accessible via the REST API, while private content, password-protected content, internal users, custom post types, and metadata are only available with authentication or if you specifically set it to be so.

That rule cuts both ways. A public post is public through the API too, so hiding a post means changing its status in WordPress, not hiding the theme. A private post stays private only if the front end sends valid credentials when it asks for it.

Keep the back end locked down.

Put wp-admin behind strong passwords and two-factor login, keep WordPress and its plugins updated, and give the front end only the access it needs. Our guide on static sites vs WordPress covers the related case of a site with no WordPress front end at all.

How do you check if a site is headless?

Check whether the site's pages come from WordPress themes or from an API-driven front end.

Open the site and view its page source. A traditional WordPress site usually shows WordPress markers, such as wp-content paths for its theme and plugin files. A headless site usually shows no wp-content paths, because the front end serves its own files.

You can also ask the API directly. The REST API handbook describes endpoints as URLs for posts, pages, and taxonomies, and the standard base for those endpoints sits under /wp-json/.

If that path returns JSON post data for a site, WordPress is serving content through the API, though that alone does not prove the public site is headless.

A third check is the admin area. If the site has a wp-admin login and its editors publish there, WordPress is the back end, even when the public pages look nothing like a WordPress theme.

W3Techs reported on November 21, 2026 that WordPress is used by 57.4% of all the websites whose content management system it knows, which is 38.5% of all websites.

Frequently asked questions

Does headless WordPress mean you stop using WordPress?

No. WordPress still stores all the content and still provides wp-admin for editors. Only the theme layer is gone, replaced by a separate front end that asks the API for content.

Should I use the REST API or WPGraphQL?

The REST API ships with WordPress and needs no extra plugin, so it is the safer default for simple sites. WPGraphQL fits pages that combine many related pieces of content in one query.

Do WordPress plugins still work on a headless site?

Yes, but they may need extra work. Live preview and plugins that print HTML into pages expect a WordPress front end, so check each plugin you rely on before you switch.

Is headless WordPress faster than traditional WordPress?

It depends on the site. A headless setup adds a second app to build, host, and secure, so a small blog or business site rarely gains enough to pay for it. It fits teams that already build front ends with JavaScript frameworks.

Can I run a headless WordPress site without a developer?

You need a developer, or a team, to build and maintain the front end. Editors can still publish in wp-admin, but the front end itself is code, not a theme you can edit in the dashboard.

Sources

  1. REST API Handbook WordPress Developer Resources
  2. WPGraphQL WordPress.org
  3. Quick Start WPGraphQL
  4. Block Editor Handbook WordPress Developer Resources
  5. Usage Statistics and Market Share of WordPress, November 2026 W3Techs

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.