Using Ghost as a Headless CMS

Ghost Beyond Themes

Ghost is typically used as a full publishing platform — content management, rendering, newsletters, and memberships all in one. But Ghost also works as a headless CMS, delivering content through APIs while you build a custom frontend in any framework.

This approach gives you Ghost’s editor, content organization, and member management with complete control over the presentation layer.

Ghost’s APIs

Ghost provides two APIs:

Content API (Read-Only)

The Content API delivers published content as JSON. It is available on all Ghost plans, including Starter.

Base URL: https://yourdomain.com/ghost/api/content/

Authentication: Content API key (found in Ghost Admin → Integrations → Add custom integration)

Available endpoints:

Filtering and pagination:

GET /ghost/api/content/posts/?key=YOUR_KEY&limit=10&page=1
GET /ghost/api/content/posts/?key=YOUR_KEY&filter=tag:tutorials
GET /ghost/api/content/posts/?key=YOUR_KEY&include=tags,authors
GET /ghost/api/content/posts/?key=YOUR_KEY&fields=title,slug,excerpt

The Content API supports filtering by tag, author, visibility, and custom fields. Pagination follows standard cursor-based patterns.

Admin API (Read-Write)

The Admin API allows creating, editing, and deleting content programmatically. It requires Ghost(Pro) Publisher or higher.

Authentication: Admin API key (JWT-based authentication)

Capabilities:

• Create and update posts and pages
• Manage tags and authors
• Upload images
• Manage members (read member data, add labels)
• Access webhooks and integrations

The Admin API enables workflows like:

• Automated content publishing from external sources
• Member data synchronization with CRMs
• Content migration scripts
• Automated social media posting triggered by new posts

Building a Headless Frontend

Why Go Headless?

Reasons to use Ghost as a headless CMS instead of using Ghost themes:

• Custom frontend framework: You want to build with React, Vue, Svelte, or another framework
• Static site generation: Pre-render pages for maximum performance using Next.js, Nuxt, or Astro
• Multi-channel publishing: Same content delivered to web, mobile app, and other platforms
• Complex layouts: Your design requirements exceed what Handlebars templates can achieve
• Existing infrastructure: Ghost fits into an existing tech stack as the content layer

Why Stay With Themes

Reasons to use Ghost’s built-in theme system instead:

• Faster setup: Install a theme and start publishing immediately
• Newsletter integration: Themes render consistently in both web and email
• Membership pages: Themes include pre-built sign-up, sign-in, and account pages
• SEO defaults: Ghost’s rendering engine handles structured data, sitemaps, and meta tags automatically
• Lower maintenance: No separate frontend to build, deploy, and maintain

If your primary goal is publishing content with newsletters and memberships, the theme approach is simpler and more feature-complete. Headless is for projects that need custom frontend architecture.

Next.js Example

Ghost provides an official JavaScript SDK (@tryghost/content-api) for the Content API:

import GhostContentAPI from '@tryghost/content-api';

const api = new GhostContentAPI({
  url: 'https://yourdomain.com',
  key: 'your_content_api_key',
  version: 'v5.0'
});

// Fetch all posts
const posts = await api.posts.browse({
  limit: 'all',
  include: 'tags,authors'
});

// Fetch a single post by slug
const post = await api.posts.read({
  slug: 'my-post-slug'
}, {
  include: 'tags,authors'
});

In a Next.js app with static site generation:

export async function getStaticPaths() {
  const posts = await api.posts.browse({ limit: 'all', fields: 'slug' });
  return {
    paths: posts.map(post => ({ params: { slug: post.slug } })),
    fallback: false
  };
}

export async function getStaticProps({ params }) {
  const post = await api.posts.read({ slug: params.slug }, { include: 'tags,authors' });
  return { props: { post } };
}

Astro Example

Astro’s static-first approach pairs well with Ghost as a headless CMS:

---
import GhostContentAPI from '@tryghost/content-api';

const api = new GhostContentAPI({
  url: import.meta.env.GHOST_URL,
  key: import.meta.env.GHOST_KEY,
  version: 'v5.0'
});

export async function getStaticPaths() {
  const posts = await api.posts.browse({ limit: 'all', fields: 'slug' });
  return posts.map(post => ({ params: { slug: post.slug } }));
}

const { slug } = Astro.params;
const post = await api.posts.read({ slug }, { include: 'tags,authors' });
---

<article>
  <h1>{post.title}</h1>
  <div set:html={post.html} />
</article>

Nuxt, Gatsby, and Others

The @tryghost/content-api SDK works in any JavaScript environment. For non-JavaScript frameworks (Ruby, Python, Go), use the REST API directly — it returns standard JSON.

Headless Considerations

SEO Responsibility

When using Ghost headlessly, you are responsible for:

• Generating XML sitemaps
• Adding structured data (JSON-LD) to pages
• Setting canonical URLs
• Configuring Open Graph and Twitter Card tags
• Creating robots.txt

Ghost’s built-in rendering handles all of this automatically. Going headless means reimplementing these features in your frontend.

Membership and Newsletters

Ghost’s membership portal and newsletter sending still work in headless mode — they are server-side features that do not depend on the frontend theme. However:

• You need to integrate Ghost’s Portal widget into your custom frontend for member signup/login
• Newsletter emails are sent by Ghost regardless of how the frontend is built
• Content gating (showing/hiding content based on membership) must be handled in your frontend code

Webhooks for Real-Time Updates

Ghost supports webhooks that fire when content changes:

• Post published, updated, or deleted
• Page published, updated, or deleted
• Member added, updated, or deleted
• Tag created, updated, or deleted

Use webhooks to trigger static site rebuilds, cache invalidation, or external service updates when content changes in Ghost.

Content Delivery

For static sites, content is fetched at build time and pre-rendered. For dynamic sites, content is fetched on each request (or with caching). Consider:

• Build time: Static generation with incremental rebuilds (ISR in Next.js)
• CDN caching: Cache API responses at the CDN level for dynamic sites
• Rate limits: Ghost(Pro) has API rate limits — batch requests during builds

Ghost vs Dedicated Headless CMS

How Ghost compares to purpose-built headless CMS platforms:

Ghost’s content model is fixed — posts, pages, tags, and authors. Dedicated headless CMS platforms allow fully custom content models (define your own content types, fields, and relationships). If you need custom content types beyond articles, a dedicated headless CMS may be more appropriate.

Ghost’s advantage: it includes newsletters and memberships that no dedicated headless CMS provides natively.

When to Go Headless

Go headless when:

• You have a development team that can build and maintain a custom frontend
• Your project needs custom content types or complex data relationships
• You are building a multi-platform experience (web + mobile app)
• Your frontend requirements exceed what Handlebars themes can provide

Stay with Ghost themes when:

• Publishing is your primary activity (not frontend development)
• You want newsletters, memberships, and SEO handled automatically
• You need to be publishing within days, not weeks
• Maintenance simplicity is a priority

Theme-Based Publishing

For publishers who want Ghost’s full feature set without building a custom frontend, a premium theme provides the design flexibility you need.

Our themes are built specifically for Ghost’s native rendering, starting at $69.

Browse Ghost themes →