Output modifiers

Output modifiers are available for the read and browse methods. They let you change the output of the result to have only your selected fields, include some additionnal data that the Ghost API doesn't give you by default or get the content in different formats.

The result type from the subsequent fetch will be modified to match your selection giving you full type-safety.

// Example with read...
let result = await api.posts.read({ slug: "slug"}).fields({ title: true }).fetch();
 
// ... and with browse
let result = await api.posts.browse({limit: 2}).fields({ title: true }).fetch();

Select specific fields with .fields()

The fields method lets you change the output of the result to have only your selected fields, it works by giving an object with the field name and the value true. Under the hood it will use the zod.pick method to pick only the fields you want.

let result = await api.posts
  .read({
    slug: "typescript-is-cool",
  })
  .fields({
    id: true,
    slug: true,
    title: true,
  })
  .fetch();
 
if (result.success) {
  const post = result.data;
  //     ^? type {"id": string; "slug":string; "title": string}
}

The output schema will be modified to only have the fields you selected and TypeScript will pick up on that to warn you if you access non-existing fields.

Include relations with .include()

The include method lets you include some additionnal data that the Ghost API doesn't give you by default. The include params is specific to each resource and is defined in the "include" Schema of the resource. You will have to let TypeScript guide you to know what you can include.

let result = await api.authors
  .read({
    slug: "phildl",
  })
  .include({ "count.posts": true })
  .fetch();

Available include keys by resource:

• Posts & Pages: authors, tags
• Authors: count.posts
• Tags: count.posts
• Tiers: monthly_price, yearly_price, benefits

The output type will be modified to make the fields you include non-optionals.

Output page/post content into different .formats()

In the Admin API, the formats method lets you add alternative content formats on the output of Post or Page resource to get the content in plaintext or html. Available options are plaintext | html | mobiledoc.

let result = await api.posts
  .read({
    slug: "this-is-a-post-slug",
  })
  .formats({
    plaintext: true,
    html: true,
  })
  .fetch();

The output type will be modified to make the formatted fields you include non-optionals.

Combining output modifiers

You can combine output modifiers to get the result you want. For example if you want to get the html and plaintext content of a Post:

let result = await api.posts
  .read({
    slug: "this-is-a-post-slug",
  })
  .fields({
    title: true,
    slug: true,
    plaintext: true,
    html: true,
  })
  .formats({
    plaintext: true,
    html: true,
  })
  .fetch();