Building a Headless WordPress CMS with Claude Code APIs

I've been building headless WordPress setups for clients in Vancouver for the past two years, and the workflow has changed dramatically since I started using Claude Code to generate custom REST APIs. What used to take three weeks of back-and-forth development now takes about four days — and the result is faster, cleaner, and easier to maintain.

If you're not familiar with the term, headless WordPress means you use WordPress as a content management system but deliver the front-end through a separate framework — usually Next.js, Nuxt, or Astro. Your marketing team keeps using the WordPress editor they know, but the public site is built with modern tooling that loads faster and gives you more design flexibility.

The challenge has always been the API layer. WordPress ships with a REST API, but it's generic and not optimized for custom use cases. Most real projects need custom endpoints, authentication logic, caching strategies, and field serialization. That's where Claude Code comes in.

Why I Use Headless WordPress for Client Sites

The traditional WordPress architecture — where PHP generates HTML on every page load — is slow. Even with a good caching plugin, you're still dealing with database queries, theme files, and plugin overhead on every request. For marketing sites that need to load in under a second, that's a problem.

Headless WordPress solves this by separating concerns. WordPress handles content authoring and storage. A static site generator or JavaScript framework handles the presentation layer. The front-end fetches content from WordPress via API, pre-renders as much as possible, and serves static files from a CDN. The result is page speeds in the 200–400ms range instead of 2–4 seconds.

The other advantage is flexibility. With a traditional WordPress theme, you're constrained by the theme's structure and the limitations of PHP templating. With a headless setup, you can build the front-end in React, Vue, or Svelte — whatever gives you the interactions and performance you need. You're not locked into WordPress conventions.

One Vancouver SaaS client I work with saw their homepage load time drop from 3.2 seconds to 480ms after we moved to headless. Same content, same CMS on the back end — just a faster delivery mechanism on the front.

The API Problem Claude Code Solves

WordPress ships with a REST API at /wp-json/wp/v2/. It works, but it's not optimized for production use. The default endpoints return too much data — every post request includes author details, featured images in multiple sizes, and metadata you probably don't need. For a blog index with 20 posts, that's a lot of wasted bytes.

The other issue is custom fields. If you're using Advanced Custom Fields or similar plugins, those fields aren't included in the default API response. You need to register custom endpoints or modify the existing ones. Doing that manually in PHP is tedious and error-prone.

This is where Claude Code becomes useful. I can describe the exact data structure I need — "give me post title, excerpt, featured image URL at 800px width, publication date, and the three ACF fields: client_name, project_type, and case_study_url" — and Claude Code writes the PHP function that registers the custom endpoint.

Here's a simplified example of what the prompt looks like:

Write a WordPress REST API endpoint at /wp-json/custom/v1/projects
that returns an array of posts from the 'project' custom post type.
Include: ID, title, excerpt, featured image URL (medium size),
publish date, and ACF fields: client_name, project_type, case_study_url.
Add pagination support with per_page and offset parameters.
Return JSON with proper headers and error handling.

Claude Code generates the functions.php code in about 10 seconds. I paste it into the theme, test it, and it works. What would have taken me 45 minutes to write and debug manually is done in two minutes.

The Typical Headless WordPress Stack I Use

For most client projects, the architecture looks like this:

• Back-end: WordPress hosted on a subdomain (usually cms.clientdomain.com) with ACF Pro for custom fields and a minimal theme
• Front-end: Next.js or Astro, depending on whether the site needs dynamic features or can be fully static
• Deployment: Vercel for the front-end, with incremental static regeneration triggered by WordPress webhooks when content changes
• API layer: Custom REST endpoints built with Claude Code, plus caching via Vercel's edge network

The content team logs into cms.clientdomain.com, edits posts and pages in the WordPress admin, and hits publish. A webhook fires to Vercel, which rebuilds the affected pages in the background. The public site at clientdomain.com updates within 30–60 seconds. No manual deploy, no FTP, no caching plugin conflicts.

Building Custom Endpoints with Claude Code

The most common endpoints I build with Claude Code are:

• Filtered post lists — return posts by category, tag, or custom taxonomy with specific field subsets
• Single post retrieval — fetch one post by slug with all custom fields and related posts
• Search — keyword search across titles and content with relevance scoring
• Navigation menus — return the site's nav structure as JSON instead of querying it on every page load
• Form submissions — accept contact form data, validate it, store it in WordPress, and send email notifications

Each of these follows a similar pattern. I define the input parameters, the data structure I want returned, and any validation or authentication requirements. Claude Code writes the PHP, I review it for security issues (always check user input sanitization and nonce validation), and then deploy.

The time savings are significant. A typical project might need 8–10 custom endpoints. At 40 minutes per endpoint manually, that's six hours of developer time. With Claude Code, it's closer to 90 minutes total — most of which is testing and refinement, not writing boilerplate.

Authentication and Security Considerations

One thing I'm careful about: not every endpoint should be publicly accessible. If you're building admin dashboards or allowing authenticated content creation, you need proper authentication.

WordPress supports several authentication methods for REST API requests: cookie authentication (for logged-in users), application passwords (for external apps), and OAuth (for third-party integrations). Which one you use depends on the use case.

For most headless setups where the front-end is public and the admin is private, I use JWT (JSON Web Tokens) with the JWT Authentication plugin. Claude Code can generate the token validation logic for custom endpoints in about 30 seconds.

The other critical security step: always sanitize and validate input on custom endpoints that accept POST data. Claude Code is good at including basic sanitization, but you should manually review every $_POST and $_GET reference to make sure sanitize_text_field() or wp_kses_post() is applied appropriately.

Real Performance Gains from Going Headless

I track Core Web Vitals for every client project. The difference between a traditional WordPress site and a well-built headless setup is stark:

• Largest Contentful Paint (LCP): Traditional WP averages 2.8–4.2s. Headless averages 0.6–1.1s.
• First Input Delay (FID): Both are usually fine, but headless has less JavaScript blocking the main thread.
• Cumulative Layout Shift (CLS): Headless is more predictable because fonts and images are pre-optimized at build time.

For a Vancouver e-commerce client, we saw a 34% increase in mobile conversion rate after migrating their marketing pages to headless. The product catalog stayed in WooCommerce, but the landing pages, blog, and about section moved to Next.js. Page speed went from a D to an A in Google PageSpeed Insights, and bounce rate dropped by 18%.

When Headless WordPress Doesn't Make Sense

I don't recommend headless for every project. If your site is mostly static and rarely updated, a traditional WordPress setup with good caching is fine. If your team isn't comfortable with the idea of a separate front-end deployment process, the added complexity isn't worth it.

Headless also doesn't work well if you rely heavily on WordPress plugins that inject front-end code — things like page builders, form plugins with conditional logic, or membership systems. Those plugins expect to control the HTML output, which you lose in a headless setup.

The sweet spot is content-heavy marketing sites: agency portfolios, SaaS blogs, news sites, membership communities where the content structure is custom but the editing workflow needs to stay familiar.

How to Get Started

If you want to try this approach on your next project, here's the path I'd recommend:

1. Set up a fresh WordPress install on a subdomain with ACF Pro and your custom post types
2. Use Claude Code to build one simple custom endpoint — maybe a post list for your blog
3. Set up a basic Next.js or Astro project that fetches from that endpoint and renders a static page
4. Deploy the front-end to Vercel and confirm the build pipeline works
5. Expand from there — add more endpoints, optimize caching, set up webhooks for auto-rebuilds

The whole setup can be done in a weekend if you're comfortable with JavaScript and have used WordPress before. If you want a faster start, I've written a guide to WordPress automation with Claude Code that covers the basics.

And if you'd rather hire someone to build it, that's what I do. Most headless WordPress builds for Vancouver clients take 2–3 weeks and cost between $8K and $18K depending on complexity. If you want to discuss a specific project, the FAQ has details on how I work.

The tooling is here. The question is whether your current WordPress site is holding you back on speed, and whether moving to a headless architecture would be worth the migration effort. For the right projects, it absolutely is.