👻 Ghost Admin API

A Admin API do Ghost só responde a quem se identifica como uma Custom Integration. Não dá pra usar a senha de admin nem o token do dashboard — toda automação precisa de uma integração própria, com escopo isolado e revogável em um clique.

No painel do Ghost vá em Settings → Integrations → Add custom integration. Dê um nome descritivo (ex.: MkBlogs Publisher) — esse nome aparece no histórico de cada post publicado pela API.

Conceitos-chave

Cada integração gera duas chaves: a Content API Key (read-only, para apps públicos) e a Admin API Key (read/write, para publicar). Para escrever posts você precisa da segunda.

A Admin Key vem no formato id:secret — duas strings hex separadas por dois-pontos. O id identifica a integração (24 chars), o secret é o segredo HMAC de 64 chars hex usado para assinar JWTs.

# Formato da Admin API Key
# <id 24 hex>:<secret 64 hex>
6582f1c4a3e9b7d8f201e3a4:0f2b9c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b

# Estrutura
# ├─ id     → cola na claim "kid" do JWT
# └─ secret → assina o JWT com HS256 (precisa ser convertido de hex p/ bytes)

Conceitos-chave

Dá pra falar com a Admin API "na mão" (montar JWT + fetch), mas o jeito recomendado pela própria Ghost é a lib oficial @tryghost/admin-api. Ela cuida da geração do JWT, do versionamento de endpoint e do parsing das respostas.

Instale via npm/pnpm e importe em Node ≥ 18. A lib é puramente server-side — não funciona no browser porque expõe o secret.

# Instalação
npm install @tryghost/admin-api
# ou
pnpm add @tryghost/admin-api

# Versão mínima recomendada: ^1.13.0 (suporta Ghost 5.x)

// init.js — inicializar o client
import GhostAdminAPI from '@tryghost/admin-api';

const api = new GhostAdminAPI({
  url: process.env.GHOST_URL,           // ex: https://meublog.com
  key: process.env.GHOST_ADMIN_KEY,     // formato id:secret
  version: 'v5.0'                       // versão da API
});

// Teste rápido — listar últimos 3 posts
const posts = await api.posts.browse({ limit: 3 });
console.log(posts.map(p => p.title));

Conceitos-chave

Por baixo dos panos, cada chamada à Admin API vai com um header Authorization: Ghost <token>. O token é um JWT assinado com HS256, usando o secret da Admin Key como chave HMAC.

O JWT tem expiração curtíssima — 5 minutos. A ideia é que cada request gere um token novo. Tokens "eternos" são anti-padrão aqui; se vazarem, comprometem por muito tempo.

// Gerar token JWT manualmente (a lib oficial já faz isso por você)
import jwt from 'jsonwebtoken';

function ghostToken(adminKey) {
  const [id, secret] = adminKey.split(':');

  // O secret vem em hex — precisa virar Buffer
  const secretBuffer = Buffer.from(secret, 'hex');

  return jwt.sign({}, secretBuffer, {
    keyid: id,             // claim "kid" — identifica a integração
    algorithm: 'HS256',
    expiresIn: '5m',       // expiração curta (recomendado)
    audience: '/admin/'    // audiência fixa exigida pelo Ghost
  });
}

// Uso
const token = ghostToken(process.env.GHOST_ADMIN_KEY);
const res = await fetch('https://meublog.com/ghost/api/admin/posts/', {
  headers: { Authorization: `Ghost ${token}` }
});

Conceitos-chave

O endpoint posts.add aceita conteúdo em HTML (padrão) ou em Mobiledoc/Lexical (formato interno do Ghost). Para automação a partir de Markdown, o caminho mais simples é converter MD → HTML no seu lado e mandar como HTML, sinalizando source: 'html'.

O campo status controla o destino: draft (rascunho, default), published (publica na hora) ou scheduled (combinado com published_at futuro).

// publish.js — publicar post a partir de HTML
import GhostAdminAPI from '@tryghost/admin-api';

const api = new GhostAdminAPI({
  url: process.env.GHOST_URL,
  key: process.env.GHOST_ADMIN_KEY,
  version: 'v5.0'
});

const html = `
  <h2>Primeira automação no Ghost</h2>
  <p>Esse post foi criado via Admin API.</p>
  <ul>
    <li>JWT gerado pela lib</li>
    <li>Markdown convertido para HTML</li>
    <li>Status: published</li>
  </ul>
`;

const post = await api.posts.add(
  {
    title: 'Olá Ghost via API',
    html,
    status: 'published',
    tags: ['automação', 'api'],
    excerpt: 'Primeiro post automatizado no blog.'
  },
  { source: 'html' }  // 👈 diz ao Ghost para parsear o campo `html`
);

console.log('Publicado:', post.url);

// Markdown → HTML antes de mandar (usando `marked`)
import { marked } from 'marked';

const md = `
## Título

Texto com **negrito** e [link](https://exemplo.com).

- item 1
- item 2
`;

const html = marked.parse(md);
await api.posts.add({ title: 'Post MD', html, status: 'draft' }, { source: 'html' });

Conceitos-chave

Um post "completo" no Ghost não é só título + corpo. Ele tem feature image (capa exibida no topo e em cards sociais), meta_title / meta_description (SEO e Open Graph) e og_image / twitter_image (override por canal).

A feature image precisa ser uma URL pública — ou você faz upload via api.images.upload() e usa a URL retornada, ou aponta para um CDN externo (Unsplash, S3, R2).

// Post completo com capa + SEO
const post = await api.posts.add(
  {
    title: 'Como configurar seu blog em 2026',
    html: '<p>Conteúdo do post...</p>',
    status: 'published',

    // Capa
    feature_image: 'https://cdn.meublog.com/capas/setup-blog-2026.jpg',
    feature_image_alt: 'Tela de configuração do Ghost',
    feature_image_caption: 'Painel de Settings do Ghost 5.x',

    // SEO base (usado em <title> e meta description)
    meta_title: 'Configurar Blog em 2026 — Guia Prático',
    meta_description: 'Passo a passo de setup de blog com Ghost, Admin API e CI.',

    // Open Graph (Facebook/LinkedIn) — opcional, herda dos meta_*
    og_title: 'Guia: configurar seu blog em 2026',
    og_description: 'Setup completo de blog moderno em menos de uma hora.',
    og_image: 'https://cdn.meublog.com/og/setup-blog-2026.jpg',

    // Twitter Card — opcional, herda dos og_*
    twitter_title: 'Configurar Blog em 2026',
    twitter_description: 'Setup prático de blog em 2026.',
    twitter_image: 'https://cdn.meublog.com/twitter/setup-blog-2026.jpg'
  },
  { source: 'html' }
);

Conceitos-chave