Ghost setup

The Ghost connector creates draft posts through a custom integration on Ghost’s Admin API. Works with Ghost(Pro) and self-hosted Ghost 5 and up. You publish from Ghost admin.

Step 1 - create a custom integration

1. In Ghost admin, open Settings → Advanced → Integrations.

2. Click Add custom integration, name it BirchSeek, and create it.

3. Ghost shows three values. BirchSeek needs two of them:

   • Admin API key - a long pair of the form {id}:{secret}, separated by a colon. Copy the whole thing.
   • API URL - e.g. https://your-site.ghost.io (Ghost(Pro)) or your own domain (self-hosted).

   The Content API key isn’t used; BirchSeek only writes.

Step 2 - connect in BirchSeek

In onboarding (or Connectors → Ghost later), enter:

Setting	Meaning
Admin API URL	The API URL from the integration screen
Admin API key	The full {id}:{secret} value
Default status	draft (recommended)
Default tag	Applied to every delivered article; birchseek by default, editable

Save the connector, then run the test in step 3.

How authentication works

Ghost’s Admin API doesn’t accept the key directly. For every request, BirchSeek mints a short-lived signed token (JWT, five-minute maximum life) from your key’s secret, so the key itself never travels over the network after setup. It is stored encrypted at rest, and deleting the integration in Ghost admin revokes access.

Step 3 - send a test

Send a test validates the key with a read-only call to GET /ghost/api/admin/site/. That one endpoint proves the whole chain at once: the key parses into its {id}:{secret} halves, the token signed from the secret is accepted, and the API URL points at a real Ghost site. It reports that site’s title and Ghost version back to you, so a key pasted against the wrong site is obvious straight away rather than at your first publish.

The test creates nothing. No post, no draft, no tag. The first thing BirchSeek writes to your site is your first approved article.

What BirchSeek writes

Per article, via POST /ghost/api/admin/posts/ (as HTML, which Ghost converts to its native editor format):

• title, html (the rendered article), slug
• status - draft by default
• meta_title and meta_description - Ghost stores both natively, so no SEO plugin is involved
• custom_excerpt and your default tag

html ends with a ## Sources block: a numbered list pairing each verified claim with the page it was checked against, converted into Ghost’s editor format with the rest of the article. BirchSeek composes that body once, before any connector sees it, so every connector publishing to your own site writes the same block - there is nothing to append yourself. (A syndicated copy to dev.to, Hashnode or Medium carries the same block, and the canonical link back to your page besides. That copy is not covered by the project setting: those three platforms have no citation field of their own, so the body is the only place the evidence can travel.) The block is on by default, and there is no switch for it in the dashboard: it is a project setting called append_sources_section, and the only way to change it today is PATCH /v1/projects/{id} carrying the whole settings object, because that request replaces the object rather than merging into it.

Troubleshooting

• 401 Unknown Admin API Key - the key was pasted partially (it must include the colon and everything after it), or the integration was deleted. Re-create and re-paste.
• 403 - the integration exists but lacks admin access; custom integrations have it by default, so this usually means a staff access token was pasted instead of the integration’s Admin API key.
• Version warnings - BirchSeek pins its requests to Ghost’s v5 API. Ghost 4.x sites should upgrade; Ghost(Pro) is always current.
• Self-hosted behind a proxy - ensure /ghost/api/admin/ is reachable from the internet; some hardening guides block the admin API path entirely.