ajianaz/codomate/ghost-admin-api

Ghost Admin API Skill

Manage Ghost CMS via Admin API — publish posts, manage content, upload images, send newsletters. Works with any self-hosted Ghost 5.x/6.x instance.

When to Use

• Publish/update/delete blog posts
• Create or manage pages, tags, members
• Upload images to Ghost media library
• Send or schedule newsletters
• Read site stats and analytics

Setup

Prerequisites

• Ghost Admin API Key (format: {24hex}:{64hex})
• Get it: Ghost Admin → Settings → Integrations → Add Custom Integration → Copy Admin API Key
• PyJWT: pip install PyJWT

Environment

GHOST_ADMIN_URL=https://your-ghost-domain.com/ghost/api/admin
GHOST_ADMIN_KEY=24hex_id:64hex_secret

Module

The GhostAdmin class is documented here but NOT installed as a pip package. Copy it from references/code_examples.md inline into your script.

Verify

g = GhostAdmin()
print(g.site_info())

Quick Reference

Full endpoint reference → references/api_endpoints.md

Authentication

Ghost Admin API uses JWT tokens generated from the Admin API Key:

import jwt, time
def make_token(key_id, key_secret):
    return jwt.encode(
        {"iat": int(time.time()), "exp": int(time.time()) + 300, "aud": "/admin/"},
        bytes.fromhex(key_secret), algorithm="HS256", headers={"kid": key_id}
    )

Required headers for every request:

Authorization: Ghost {jwt_token}
Accept-Version: v6.27
Content-Type: application/json
User-Agent: YourApp/1.0

Key Rules

1. `User-Agent` header required — Cloudflare blocks without it (1010 error)
2. `Accept-Version` — must match your Ghost version
3. Nested format — {"posts": [...]}, {"tags": [...]}, etc.
4. `updated_at` required for PUT — always GET first to prevent conflicts
5. `?source=html` is CRITICAL — without it, html field is silently ignored → empty post
6. Newsletter = 2-step — create draft, then PUT with query params
7. `?formats=html,lexical` — default GET returns empty html field
8. Max 100 results per request (?limit=all caps at 100)
9. JWT expires in 5 min — regenerate per request
10. DELETE returns 204 — empty body, do NOT json.loads()
11. ⚠️ ALWAYS VERIFY after publish — GET post back, verify html is non-empty
12. `newsletter` field in POST body is silently ignored — use PUT query params instead

Content Formats

Styled HTML (<div>, style, class) requires <!--kg-card-begin: html--> wrapper.

Lexical Builder

For programmatic post building, use references/lexical_builder.py — copy functions inline into your script:

from lexical_builder import text_node, heading_node, build_lexical, rich_paragraph
blocks = [
    heading_node("Section Title"),
    rich_paragraph(["Normal text ", ("bold text", "bold"), ("linked", "https://example.com")]),
]
lexical_json = build_lexical(blocks)

References