Fetching Published Ghost Posts Headlessly With the Content API Key

Problem: Developers building a headless Ghost setup often can't tell which API key to use, how to paginate through posts, or how to apply filters without breaking the request. The Content API key is public and read-only, but it's easy to confuse with the Admin API key or misuse it in client code. Takeaway: You can fetch published Ghost posts reliably in a headless frontend by calling the Content API with a simple query parameter, handling pagination via limit and page, and filtering with Ghost's filter syntax all while keeping the key exposed but safe in the browser.

Content API vs Admin API: what's the difference?

The Ghost system exposes two distinct APIs. The Content API is read-only and authenticated via a Content API key passed as a query parameter. The Admin API is write-protected and requires a JWT-signed request. For fetching published posts in a headless context, the Content API is the correct choice.

To retrieve posts from a Ghost site, run a fetch request against the Content API endpoint. The request runs in any environment that can make HTTP calls - browser JavaScript, Node.js, a server-side function, or a static site build step. The Content API key is passed as the key query parameter; it is not a secret and should not be used for write operations.

fetch(https://my-ghost-site.ghost.io/ghost/api/v3/content/posts/?key=YOUR_CONTENT_API_KEY)
The Content API returns a fixed number of posts per request, controlled by the limit parameter. The default is usually 20, and the maximum depends on your Ghost version. Use page to navigate pages. The response meta includes page, limit, pages, total, next, and prev to help you paginate.
fetch(https://my-ghost-site.ghost.io/ghost/api/v3/content/posts/?key=YOUR_CONTENT_API_KEY&limit=10&page=2)
Filter by tag: Append filter=tag:news to fetch only posts tagged news. Include authors or tags: Use include=authors or include=tags to expand relation data in the same request.
Common mistakes and limits
Confusing the Content API key with the Admin API key. The Admin API key is sensitive, JWT-signed, and must never appear in client-side code.
Assuming pagination behavior is identical across all Ghost installations. Rate limits and exact limit/page semantics can vary; check your site s admin panel under Integrations.
Using filter syntax that's not supported by your Ghost version. The filter language (e.g., filter=author:slug) is version-sensitive; consult the Ghost docs for the exact version you're running.
Attempting write operations with the Content API key. It will return 403 or 401; use the Admin API with JWT for any creation or update.
Treating the Content API key as site-agnostic. It is tied to the specific Ghost site where it was generated.
How to verify your setup
Open your Ghost admin panel Integrations Content API and copy the Content API key.
Run the minimal fetch example with your key. Confirm the response includes a posts array and meta.pagination.
Test a filtered request, e.g., ?filter=tag:news, and verify only tagged posts appear.
Attempt a write-style payload (e.g., POST to the Admin API endpoint with the Content key) and expect a 403/401, confirming read-only status.
Check response headers for ratelimit-limit and ratelimit-remaining if your host provides them.
By following these steps, you can safely integrate Ghost's Content API into any headless frontend, keep your Admin key secure, and avoid the most common integration pitfalls.