Publishing integrations

Ghost

Ghost’s Admin API takes a key that is two halves separated by a colon — an id and a secret — and we sign a short-lived token with it for every request.

Create a custom integration#

  1. In Ghost admin, open Settings → Integrations.
  2. Scroll to the bottom and click Add custom integration.
  3. Name it Rankli and create it.
  4. Copy the Admin API key — it looks like 63f1…:8c2a…, an id and a secret joined by a colon. Copy the whole string including the colon.
  5. Copy the API URL too. It is usually your Ghost site’s address, e.g. https://acme.com, and on Ghost(Pro) it may be https://acme.ghost.io.

Custom integrations are not available on the Ghost Starter plan. If the “Add custom integration” button is missing, that is why — the webhook integration is the way in on that plan.

Connect it#

  1. In Rankli, open Integrations → New integration → Ghost.
  2. API URL — the address from the integration screen, without a trailing slash and without /ghost/api.
  3. Admin API key — the whole id:secret string.
  4. Publish mode — published, or draft for review in Ghost.
  5. Save. We read the site record as the connection test, which proves both halves of the key.

What lands on your site#

FieldWhere it goes
TitleThe post title.
BodyThe post content. Ghost stores Lexical; we send HTML and let Ghost convert it, which is the supported path.
SlugThe post slug.
Meta descriptionThe post’s custom excerpt and meta description.
Hero imageThe feature image, uploaded to Ghost first.
TagsFrom the article’s keyword cluster. Tags that do not exist are created.
Statuspublished or draft, per the connection.

Ghost’s HTML-to-Lexical conversion is lossy for exotic markup. Everything we send is headings, paragraphs, lists, links, images and blockquotes, all of which survive intact.

When it does not work#

401 “Invalid token”

Usually only half the key was pasted, or a Content API key was used instead of an Admin API key. The Admin key has a colon in it; the Content key does not.

404 on the API URL

The URL should be the site root — we add /ghost/api/admin/ ourselves. Pasting the full API path produces a doubled one.

Clock skew

Ghost rejects tokens whose iat is in the future. This is ours to get right and it is worth knowing the symptom: an intermittent 401 that clears on retry.

rankli-cli integrations test <integrationId> --json