Working Example
Authentication
The client requires the host address of your Ghost API and a Content API key in order to authenticate. The version string is optional, and indicates the minimum version of Ghost your integration can work with. The Content API URL and key can be obtained by creating a newCustom Integration
under the Integrations screen in Ghost Admin.

url
- API domain, must not end in a trailing slash.key
- hex string copied from the “Integrations” screen in Ghost Adminversion
- should be set to ‘v6.0’
Endpoints
All endpoints & parameters provided by the Content API are supported.browse()
method will return an array of objects, and the read()
method will return a single object. The settings.browse()
endpoint always returns a single object with all the available key-value pairs.
See the documentation on Content API resources for a full description of the response for each resource.
Installation
yarn add @tryghost/content-api
npm install @tryghost/content-api
You can also use the standalone UMD build:
https://unpkg.com/@tryghost/content-api@{version}/umd/content-api.min.js
Usage
ES modules:Filtering
Ghost provides thefilter
parameter to fetch your content with endless possibilities! Especially useful for retrieving posts according to their tags, authors or other properties.
Ghost uses the NQL query language to create filters in a simple yet powerful string format. See the NQL Syntax Reference for full details.
Filters are provided to client libraries via the filter
property of any browse
method.
Working Example
Common Filters
featured:true
- all resources with a fieldfeatured
that is set totrue
.featured:true+feature_image:null
- looks for featured posts which don’t have a feature image set by using+
(and).tag:hash-noimg
-tag
is an alias fortags.slug
andhash-noimg
would be the slug for an internal tag called#NoImg
. This filter would allow us to find any post that has this internal tag.tags:[photo, video, audio]
- filters posts which have any one of the listed tags,[]
(grouping) is more efficient than using or when querying the same field.primary_author:my-author
-primary_author
is an alias for the first author, allowing for filtering based on the first author.published_at:>'2017-06-03 23:43:12'
- looks for posts published after a date, using a date string wrapped in single quotes and the>
operator
JavaScript SDK
A collection of packages for common API usecasesHelpers
- Package:
@tryghost/helpers
- Builds: CJS, ES, UMD
Tags
Filters and outputs tags. By default, the helper will output a comma separated list of tag names, excluding any internal tags.tags
array.
Options
The tag helper supports multiple options so that you can control exactly what is output, without having to write any logic.
limit
{integer} - limits the number of tags to be returnedfrom
{integer, default:1} - index of the tag to start iterating fromto
{integer} - index of the last tag to iterate overseparator
{string, default:”,”} - string used between each tagprefix
{string} - string to output before each tagsuffix
{string} - string to output after each tagvisibility
{string, default:“public”} - change to “all” to include internal tagsfallback
{object} - a fallback tag to output if there are nonefn
{function} - function to call on each tag, default returns tag.name
Reading Time
Calculates the estimated reading time based on the HTML for a post & available images.html
string. If a feature_image
is present, this is taken into account.
Options
The output of the reading time helper can be customised through format strings.
minute
{string, default:“1 min read”} - format for reading times <= 1 minuteminutes
{string, default:”% min read”} - format for reading times > 1 minute
Installation
yarn add @tryghost/helpers
npm install @tryghost/helpers
You can also use the standalone UMD build:
https://unpkg.com/@tryghost/helpers@{version}/umd/helpers.min.js
Usage
ES modules:
String
- Package:
@tryghost/string
- Builds: CJS
Slugify
The function Ghost uses to turn a post title or tag name into a slug for use in URLs.requiredChangesOnly
{boolean, default:false} - don’t perform optional cleanup, e.g. removing extra dashes
Installation
yarn add @tryghost/string
npm install @tryghost/string
Usage
Node.js: