Ghost — Ranket Docs

Ranket connects to your Ghost site and publishes generated articles via the Admin API. Each article ships with title, slug, HTML body, custom excerpt, meta title/description, target-keyword tag, and a feature image. Updates and deletes propagate to the same post.

What you need before you start

A Ghost site, either self-hosted or on Ghost(Pro) (any tier — Admin API is included on all plans).
Owner or Administrator access — only these roles can create custom integrations.
The site reachable over HTTPS at the URL you’ll register. The Admin API lives at <apiUrl>/ghost/api/admin/. If your site sits behind a reverse proxy, make sure /ghost/api/ is not blocked.
Ghost version 4.x or newer. The Admin API JWT auth scheme used by Ranket was introduced in 3.0 but post-creation behavior we rely on (HTML source flag, custom excerpt) stabilized in 4.x.

Step-by-step setup

In Ghost admin, go to Settings → Integrations.
Scroll down and click + Add custom integration.
Name the integration Ranket and click Create.
On the integration page, copy the Admin API Key. It looks like <24-hex-id>:<64-hex-secret> (a colon-separated pair). The Content API Key and API URL are also shown — you only need the Admin API Key.
Copy your site’s API URL. This is the base URL of your Ghost install (e.g. https://example.com), not the API path itself — Ranket appends /ghost/api/admin/ automatically.
In Ranket, open your brand → Webhooks tab → Add endpoint and pick Ghost.
Paste the API URL (no trailing slash) and the Admin API Key (the full id:secret string, including the colon).
Optionally change Default Status — published (default) goes live immediately, draft keeps posts unpublished, scheduled requires you to set a publish date manually after delivery.
Click Test connection before saving — Ranket mints a short-lived JWT and hits /ghost/api/admin/site/ to confirm the key is valid and the site is reachable.

Configuration options

Field	Required	Default	What it does
`apiUrl`	yes	—	Base URL of the Ghost install (e.g. `https://example.com`). The Admin API path is appended automatically.
`adminApiKey`	yes	—	Admin API key in the form `<id>:<secret>` (hex pairs). Used to sign 5-minute JWTs for each request.
`defaultStatus`	no	`published`	One of `published`, `draft`, `scheduled`. Sets the initial post status.

What gets sent

Each article.published event creates a post via POST /ghost/api/admin/posts/?source=html with:

title, slug, html (the body — ?source=html tells Ghost to convert it to its native Lexical format on ingest), custom_excerpt (truncated to 300 chars to fit Ghost’s limit).
meta_title and meta_description (Ghost’s built-in SEO fields).
tags: a single tag matching the article’s targetKeyword (Ghost auto-creates the tag if it doesn’t exist).
feature_image: URL of the hero image (Ghost fetches and caches the asset).
status from defaultStatus.

JSON-LD schema and FAQ blocks are present in the original webhook payload but are not auto-injected — Ghost generates its own JSON-LD from the post fields, which covers the basics.

Updates and deletes

When Ranket optimizes an article, the same endpoint receives an article.updated event. Ghost requires optimistic concurrency (updated_at) on updates, so Ranket first GETs the current post, then PUTs the new body with the matching timestamp. Deletions fire article.deleted and the post is removed via DELETE /ghost/api/admin/posts/<id>/.

Troubleshooting

401 “Authorization failed” / invalid token — the Admin API Key is wrong, the integration was deleted, or the secret half got truncated when copying. Generate a new key in Settings → Integrations.
404 on /ghost/api/admin/ — your reverse proxy or CDN is blocking the admin path. Most common with Cloudflare WAF rules — add a path exception for /ghost/api/.
422 “Validation failed” on update — the cached updated_at is stale because someone edited the post in Ghost between the prefetch and the PUT. The retry will pick up the new timestamp and succeed.
Body looks wrong / formatting lost — make sure your Ghost version is 4.0+. Older versions handle the ?source=html flag differently and may strip block-level formatting.
Tag created with weird casing — Ghost normalizes tag names but the slug is derived from the first occurrence. If you want a specific tag, create it in Ghost first with the casing you want, then Ranket will reuse it.