Back

Ghost API Essential Guide

Aug 13, 20246 minute read

What type of API does Ghost provide?

Type of API

  • Ghost has a RESTful Content API

Key Details

  • It's a read-only API that delivers published content
  • Access is controlled via an API key
  • It supports filtering results using a query language called NQL
  • The API is designed to be fully cacheable

API Characteristics

  • Uses REST architectural style
  • Provides a simple, uniform interface
  • Allows data exchange in formats like JSON and XML
  • Adheres to REST architectural constraints like being stateless

Benefits of REST for Ghost

  • Quick and lightweight, good for mobile and web apps
  • Easy to discover and test via URLs
  • Flexible and scalable
  • Can be developed in many programming languages

Does the Ghost API have webhooks?

Yes, the official Ghost API does have webhooks. Here are the key points about Ghost's webhook functionality:

Available Events

Ghost supports webhooks for the following types of events:

  • Site changes:

    • site.changed - Triggered when any content or settings change on the site
  • Posts:

    • post.added
    • post.deleted
    • post.edited
    • post.published
    • post.published.edited
    • post.unpublished
    • post.scheduled
    • post.unscheduled
    • post.rescheduled
  • Pages:

    • page.added
    • page.deleted
    • page.edited
    • page.published
    • page.published.edited
    • page.unpublished
    • page.scheduled
    • page.unscheduled
    • page.rescheduled
  • Tags:

    • tag.added
    • tag.edited
    • tag.deleted
    • post.tag.attached
    • post.tag.detached
    • page.tag.attached
    • page.tag.detached
  • Members:

    • member.added
    • member.edited
    • member.deleted

Key Points

  • Webhooks allow Ghost to send POST requests to user-configured URLs when specific events occur.

  • The webhook payload is a JSON object containing data about the triggered event.

  • Webhooks can be set up through the Ghost Admin user interface.

  • The only required fields to set up a webhook are the trigger event and target URL.

  • A 2xx HTTP response from the target URL is considered a successful delivery.

Best Practices

  • Subscribe only to the webhook events that your application needs to process.

  • Ensure your event handlers are idempotent, as duplicate events may occur.

  • Return a 2xx response promptly to confirm receipt of the webhook.

  • Handle events asynchronously to manage high volumes of events efficiently.

In summary, Ghost offers a comprehensive webhook system that allows developers to integrate external applications and services with Ghost, enabling real-time reactions to various events occurring within the Ghost platform.

Rate Limits and other limitations

Based on the search results provided, here are the key points about the API rate limits for the Ghost API:

Ghost(Pro) Hosted Sites

For Ghost(Pro) hosted sites:

  • There are currently no strict rate limits imposed.
  • Ghost support recommends keeping requests under 50 per second.
  • They noted that rate limits may change in the future.

Self-Hosted Ghost Installations

For self-hosted Ghost installations:

  • By default, there is a rate limit of 100 tries per IP address every 3600 seconds (1 hour).
  • This limit can be overridden in the config.production.json file.

Best Practices

Even without strict limits, it's recommended to:

  • Add small delays (e.g. a few tenths of a second) between API calls when making many requests in a loop.
  • Keep requests under 50 per second for Ghost(Pro) sites.

Key Considerations

  • Rate limits may vary depending on your hosting setup. For custom setups, you should check with your specific host.
  • The Ghost team may implement or change rate limits in the future, so it's good to design your integrations with potential limits in mind.

Summary

While there are no strict published rate limits for the Ghost API currently, especially for Ghost(Pro) users, it's best to implement reasonable throttling in your API usage. For self-hosted installations, there is a default limit that can be adjusted. Always consider the potential impact of your API usage on the server and other users.

Latest API Version

Based on the search results, here are the key points about the most recent version of the Ghost API:

Current API Version

The most recent major version of the Ghost API is v5, introduced with Ghost 5.0.

Key Changes in Ghost 5.0 API

  1. Ghost 5.0 no longer includes multiple API versions for backwards compatibility.

  2. The URLs for the APIs are now:

    • ghost/api/content for the Content API
    • ghost/api/admin for the Admin API
  3. API versions are no longer included in the URL.

  4. An accept-version header is now supported instead of versioned URLs.

API Versioning Approach

  • Breaking changes will continue to be made only in major versions.

  • New features and additions may be added in minor version updates.

  • Backwards compatibility is now provided by sending an accept-version header with API requests.

  • When the accept-version header is present, Ghost will respond with a content-version header indicating the version that responded.

  • Requests to old, versioned URLs are rewritten internally with the relevant accept-version header set. These requests will return a deprecation header.

Content API

The Content API is Ghost's RESTful API that delivers published content. It is read-only and can be accessed by any client to render content in a website or app.

Best Practices

  • Use the Accept-Version header to indicate the minimum version of Ghost's API to operate with.

  • For the most up-to-date information on API changes and versioning, refer to the official Ghost documentation.

In summary, the most recent version of the Ghost API is v5, introduced with Ghost 5.0. The API has undergone significant changes in its versioning approach, moving away from versioned URLs to using headers for version specification.

How to get a Ghost developer account and API Keys?

To get a developer account for Ghost and create an API integration, follow these steps:

  1. Create a Ghost account:

    • If you don't already have a Ghost account, sign up for one at ghost.org.
  2. Access Ghost Admin:

    • Log in to your Ghost admin panel (usually at yourdomain.com/ghost).
  3. Navigate to Integrations:

    • In the Ghost Admin sidebar, go to "Settings" and then click on "Integrations".
  4. Add a custom integration:

    • On the Integrations screen, click the "Add custom integration" button.
  5. Set up the integration:

    • Give your integration a name.
    • Optionally, add an icon and description for your reference.
  6. Get API keys:

    • Once created, the integration will automatically generate Content API and Admin API keys.
    • Copy these keys as you'll need them to authenticate your API requests.

What can you do with the Ghost API?

Based on the search results provided, here is a list of data models that can be interacted with using the Ghost API, along with what is possible for each:

Posts

  • Retrieve published posts
  • Filter posts using NQL (Ghost's query language)
  • Include related data like authors, tags, etc.

Pages

  • Retrieve published pages
  • Filter pages using NQL

Authors

  • Retrieve author information
  • Include related data like posts written by the author

Tags

  • Retrieve tag information
  • Include related data like posts with that tag

Settings

  • Retrieve site-wide settings

Tiers

  • Retrieve information about membership tiers
  • Include related data like benefits, pricing

Members

  • Manage member signups and paid subscriptions
  • Retrieve member information

Content

  • Create and edit content using the rich editor
  • Store content in JSON-based Lexical format
  • Include rich media objects called Cards

Themes

  • Interact with Handlebars.js themes

Redirects

  • Manage custom 301 and 302 redirects

SEO Data

  • Generate and retrieve JSON-LD structured metadata
  • Access automatic XML sitemaps

Images

  • Upload and retrieve images (though no specific Images API mentioned)

Webhooks

  • Set up and manage webhooks for real-time updates

It's worth noting that Ghost provides a RESTful JSON API that allows for flexible interactions with these data models. The API supports filtering, including related data, and pagination. While Ghost doesn't have some advanced features like a GraphQL API or custom field types, it offers a robust set of core features for content management and publishing.