ghost-content-api

Ghost Content API

Overview

The Content API is a public, read-only API. It requires only an API key as a query parameter — no JWT generation needed. Use it to build front-ends, integrate with other tools, or display Ghost content anywhere.

Base URL: https://{ghost_url}/ghost/api/content/

Authentication: ?key={content_api_key} — browser-safe, read-only.

Announce at start: "I'm using the ghost-content-api skill."

---

Get Your Content API Key

In Ghost Admin: Settings → Advanced → Integrations → Add custom integration (or use an existing one).

Copy the Content API Key (not the Admin API Key).

GHOST_URL=https://example.com
GHOST_CONTENT_API_KEY=abc123def456

---

Endpoints

Resource	Browse	By ID	By Slug
/posts/	GET /posts/	GET /posts/{id}/	GET /posts/slug/{slug}/
/pages/	GET /pages/	GET /pages/{id}/	GET /pages/slug/{slug}/
/authors/	GET /authors/	GET /authors/{id}/	GET /authors/slug/{slug}/
/tags/	GET /tags/	GET /tags/{id}/	GET /tags/slug/{slug}/
/tiers/	GET /tiers/	—	—
/settings/	—	GET /settings/	—

---

Basic Requests

# Browse posts (latest 15 by default)
curl "$GHOST_URL/ghost/api/content/posts/?key=$GHOST_CONTENT_API_KEY&Accept-Version=v5.0"

# Single post by slug
curl "$GHOST_URL/ghost/api/content/posts/slug/my-post-slug/?key=$GHOST_CONTENT_API_KEY"

# Single post by ID, include tags and authors
curl "$GHOST_URL/ghost/api/content/posts/{id}/?key=$GHOST_CONTENT_API_KEY&include=tags,authors"

# Site settings
curl "$GHOST_URL/ghost/api/content/settings/?key=$GHOST_CONTENT_API_KEY"

---

Query Parameters

include — Related data

?include=authors,tags          # Posts/pages
?include=count.posts           # Authors or tags — adds post count
?include=monthly_price,yearly_price,benefits  # Tiers

fields — Restrict returned fields

?fields=id,title,slug,published_at,feature_image

Cannot be combined with include.

formats — Content format

?formats=html              # HTML (default)
?formats=plaintext         # Stripped plaintext
?formats=html,plaintext    # Both

limit and page — Pagination

?limit=20&page=1
?limit=100&page=2      # Max 100 per page (Ghost 6 — ?limit=all is gone)

Ghost 6 removed ?limit=all. Always paginate:

# Fetch all posts by looping pages
page=1
while true; do
  result=$(curl -s "$GHOST_URL/ghost/api/content/posts/?key=$KEY&limit=100&page=$page")
  # Check meta.pagination.next — if null, you're done
  next=$(echo $result | jq '.meta.pagination.next')
  [ "$next" = "null" ] && break
  page=$((page + 1))
done

order — Sorting

?order=published_at%20asc       # Oldest first
?order=title%20asc              # Alphabetical
?order=updated_at%20desc        # Recently updated

filter — NQL queries (see below)

---

NQL Filtering

Ghost uses NQL (NotionQL-inspired) for filtering. All filter expressions go in ?filter=.

Operators

Operator	Meaning	Example
:	equals	featured:true
- prefix	not equals	-status:draft
>, >=, <, <=	comparison	published_at:>2024-01-01
~	contains	title~Ghost
~^	starts with	slug~^getting
~$	ends with	slug~$guide
[a,b,c]	in list	tag:[tech,news]
-[a,b,c]	not in list	-visibility:[members,paid]

Logical operators

	Symbol	Example
AND	+	featured:true+visibility:public
OR	,	tag:tech,tag:science
Grouping	()	(tag:tech,tag:science)+featured:true

Relative dates

published_at:>now-30d     # Last 30 days
published_at:>now-1w      # Last week
created_at:<now-1y        # Older than 1 year

Intervals: d (day), w (week), M (month), y (year), h (hour), m (minute), s (second).

Nested fields

authors.slug:jane-smith
tags.slug:featured
posts.count:>5            # Authors/tags with more than 5 posts

Common filter examples

# Only public featured posts
?filter=featured:true+visibility:public

# Posts with a specific tag
?filter=tag:getting-started

# Posts published in the last 30 days
?filter=published_at:>now-30d

# Posts with at least one author named Jane
?filter=authors.slug:jane-smith

# Posts that are NOT members-only
?filter=-visibility:[members,paid]

---

Pagination Response Shape

{
  "posts": [...],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 15,
      "pages": 4,
      "total": 52,
      "next": 2,
      "prev": null
    }
  }
}

Loop until meta.pagination.next is null.

---

JavaScript SDK

npm install @tryghost/content-api

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

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

// Browse posts with tags and authors
const posts = await api.posts.browse({
  include: ['tags', 'authors'],
  filter: 'featured:true',
  limit: 10,
});

// Single post by slug
const post = await api.posts.read({ slug: 'my-post-slug' }, { formats: ['html'] });

// All tags with post counts
const tags = await api.tags.browse({ include: 'count.posts', limit: 'all' });

The SDK handles pagination, auth, and serialisation automatically.

---

Settings Object

curl "$GHOST_URL/ghost/api/content/settings/?key=$KEY"

Returns site-wide settings:

{
  "settings": {
    "title": "My Publication",
    "description": "Tagline here",
    "logo": "https://example.com/content/images/logo.png",
    "icon": "https://example.com/content/images/favicon.ico",
    "accent_color": "#15171a",
    "cover_image": "...",
    "facebook": "username",
    "twitter": "@handle",
    "lang": "en",
    "timezone": "Etc/UTC",
    "url": "https://example.com"
  }
}

---

Checklist

• Content API Key set in GHOST_CONTENT_API_KEY
• Accept-Version: v5.0 header included (or version in SDK config)
• Pagination loop implemented — ?limit=all is not available in Ghost 6
• include and fields not used together on the same request
• NQL filter URL-encoded in curl requests