Parameters - Ghost Developer Docs

https://docs.ghost.org/content-api/parameters • 284 KB fetched
Open original page

Parameters - Ghost Developer Docs
Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.

Skip to main content
Ghost Developer Docs home page

Search...

⌘ K

* Sign in

* Get Started

* Get Started

Search...

Navigation
Content API
Parameters

Home
Documentation
Migration Guides

*
Tutorials

*
Developer Forum
Getting Started

* Introduction

* Installation

* Hosting Guide

* Updates & Versions

Core Concepts

* Overview

* Architecture

* Configuration

* Staff Users

* Publishing

* Memberships

* Recommendations

* Newsletters

* Security

Themes

* Overview

* Structure

* Contexts

* Assets

* Helpers

* Content

* Search

* Share

* Members

* Routing

* Custom Settings

* GScan

Advanced Tools

* Ghost CLI

* Content API

* Overview

* Posts

* Pages

* Tags

* Authors

* Settings

* Tiers

* Parameters

* Filtering

* Pagination

* Errors

* Versioning

* JavaScript Client

* Admin API

* JAMstack

* Webhooks

Resources

* FAQ

* Breaking Changes

* Contributing

* LLM

* License

* Logos

* Trademark

On this page

* Include

* Fields

* Formats

* Filter

* Limit

* Page

* Order

Advanced Tools
Content API

Parameters

Query parameters provide fine-grained control over responses. All endpoints accept include and fields . Browse endpoints additionally accept filter , limit , page and order .
The values provided as query parameters MUST be url encoded when used directly. The client libraries will handle this for you.
​

Include

Tells the API to return additional data related to the resource you have requested. The following includes are available:

* Posts & Pages: authors , tags

* Authors: count.posts

* Tags: count.posts

* Tiers: monthly_price , yearly_price , benefits

Includes can be combined with a comma, e.g., &include=authors,tags .
For posts and pages:

* &include=authors will add "authors": [{...},] and "primary_author": {...}

* &include=tags will add "tags": [{...},] and "primary_tag": {...}

For authors and tags:

* &include=count.posts will add "count": {"posts": 7} to the response.

For tiers:

* &include=monthly_price,yearly_price,benefits will add monthly price, yearly price, and benefits data.

​

Fields

Limit the fields returned in the response object. Useful for optimizing queries, but does not play well with include.
E.g. for posts &fields=title,url would return:

{
"posts" : [
{
"id" : "5b7ada404f87d200b5b1f9c8" ,
"title" : "Welcome to Ghost" ,
"url" : "https://demo.ghost.io/welcome/"
}
]
}

​

Formats

(Posts and Pages only)
By default, only html is returned, however each post and page in Ghost has 2 available formats: html and plaintext .

* &formats=html,plaintext will additionally return the plaintext format.

​

Filter

(Browse requests only)
Apply fine-grained filters to target specific data.

* &filter=featured:true on posts returns only those marked featured.

* &filter=tag:getting-started on posts returns those with the tag slug that matches getting-started .

* &filter=visibility:public on tiers returns only those marked as publicly visible.

The possibilities are extensive! Query strings are explained in detail in the filtering section.
​

Limit

(Browse requests only)
By default, only 15 records are returned at once.

* &limit=5 would return only 5 records

* &limit=100 will return 100 records (max)

​

Page

(Browse requests only)
By default, the first 15 records are returned.

* &page=2 will return the second set of 15 records.

​

Order

(Browse requests only)
Different resources have a different default sort order:

* Posts: published_at DESC (newest post first)

* Pages: title ASC (alphabetically by title)

* Tags: name ASC (alphabetically by name)

* Authors: name ASC (alphabetically by name)

* Tiers: monthly_price ASC (from lowest to highest monthly price)

The syntax for modifying this follows SQL order by syntax:

* &order=published_at%20asc would return posts with the newest post last

Suggest edits Raise issue

Tiers
Filtering

github twitter bluesky reddit
Powered by This documentation is built and hosted on Mintlify, a developer documentation platform

Links found on this page

1. /llms.txt [direct]
2. Skip to main content [direct]
3. Ghost Developer Docs home page [direct]
4. Sign in [direct]
5. Get Started [direct]
6. Home [direct]
7. Documentation [direct]
8. Migration Guides [direct]
9. Tutorials [direct]
10. Developer Forum [direct]
11. Installation [direct]
12. Hosting Guide [direct]
13. Updates & Versions [direct]
14. Overview [direct]
15. Architecture [direct]
16. Configuration [direct]
17. Staff Users [direct]
18. Publishing [direct]
19. Memberships [direct]
20. Recommendations [direct]
21. Newsletters [direct]
22. Security [direct]
23. Overview [direct]
24. Structure [direct]
25. Assets [direct]
26. Content [direct]
27. Search [direct]
28. Share [direct]
29. Members [direct]
30. Routing [direct]
31. Custom Settings [direct]
32. GScan [direct]
33. Ghost CLI [direct]
34. Overview [direct]
35. Posts [direct]
36. Pages [direct]
37. Tags [direct]
38. Authors [direct]
39. Settings [direct]
40. Tiers [direct]
41. Filtering [direct]
42. Pagination [direct]
43. Errors [direct]
44. Versioning [direct]
45. JavaScript Client [direct]
46. Webhooks [direct]
47. FAQ [direct]
48. Breaking Changes [direct]
49. Contributing [direct]
50. LLM [direct]
51. License [direct]
52. Logos [direct]
53. Trademark [direct]
54. Suggest edits [direct]
55. Raise issue [direct]
56. github [direct]
57. twitter [direct]
58. bluesky [direct]
59. reddit [direct]
60. Powered by This documentation is built and hosted on Mintlify, a developer documentation platform [direct]