Admin API Ghost : Gestion Complète Images, Thèmes, Membres, Tiers & Webhooks par Code

L'Admin API de Ghost est un outil puissant pour gérer votre site de manière programmatique. Elle permet d'automatiser des tâches comme l'ajout de contenu, la gestion des abonnés ou la configuration des thèmes, sans passer par l'interface admin. Pour une startup ou une petite entreprise, cela signifie gagner du temps et intégrer Ghost à d'autres outils comme Zapier ou des scripts personnalisés.

Dans cet article, nous explorons les sections clés de l'Admin API : les images, thèmes, utilisateurs, membres, tiers, offres, newsletters et webhooks. Nous utilisons des exemples en cURL pour les débutants et en JavaScript pour les intégrations plus avancées. L'API repose sur des requêtes HTTP RESTful, avec une base URL comme https://votre-site.com/ghost/api/admin/. Assurez-vous d'avoir une clé API admin (générée dans les intégrations de l'admin Ghost).

Authentification : Première Étape Essentielle

Avant toute requête, authentifiez-vous. L'Admin API utilise des tokens JWT (JSON Web Tokens) pour sécuriser les accès.

Méthode Recommandée : Token d'Intégration

Générez une clé API dans Ghost Admin > Intégrations > Ajouter une intégration personnalisée.
Utilisez l'ID et le secret pour créer un token JWT (durée max 5 minutes).

Exemple en JavaScript (avec la bibliothèque @tryghost/admin-api) :

const GhostAdminAPI = require('@tryghost/admin-api');

const api = new GhostAdminAPI({
  url: 'https://votre-site.com',
  key: 'votre_id_et_secret',
  version: 'v5.0'  // Vérifiez la version actuelle
});

const token = api.auth.getToken();  // Génère le token

Pour cURL, générez manuellement le JWT (utilisez une lib comme jsonwebtoken en Node.js) et ajoutez l'en-tête :

Authorization: Ghost <votre_token_jwt>

Autres Options

Token Staff : Pour agir comme un utilisateur spécifique (rôles Owner/Admin requis).
Session Utilisateur : Pour les apps web avec login (email/mot de passe + 2FA).

Permissions : Les intégrations ont un accès limité ; les rôles staff (Owner/Admin) donnent un accès complet. Limite de taux : Non spécifiée, mais évitez les abus pour ne pas surcharger votre serveur.

Erreurs courantes : Codes HTTP 401 (token invalide) ou 403 (permissions insuffisantes). Toujours incluez Content-Type: application/json et Accept-Version: v5.0 (version stable en 2025).

Gestion des Images : Upload Simple et Efficace

L'Admin API permet d'uploader des images directement pour l'éditeur ou les posts. C'est utile pour automatiser l'ajout de visuels depuis un CMS externe.

Endpoint Principal

POST /admin/images/upload/ : Upload une image.

Requête : Multipart/form-data avec le fichier.
Exemple cURL :

curl -X POST https://votre-site.com/ghost/api/admin/images/upload/ \
  -H "Authorization: Ghost <token>" \
  -F "file=@/chemin/vers/image.jpg"

Réponse exemple :

{
  "images": [{
    "url": "https://votre-site.com/content/images/2025/11/image.jpg",
    "ref": "image-ref",
    "meta": { "dimensions": { "original": { "width": 1200, "height": 800 } } }
  }]
}

Limites : Taille max par fichier (dépend de votre config Ghost, souvent 10-50 Mo). Meilleure pratique : Vérifiez l'URL générée et intégrez-la dans un post via l'API posts.

Pas d'endpoints pour update/delete directs ; supprimez via l'API posts si liée. En 2025, l'API supporte les formats WebP pour l'optimisation.

Exemple JS :

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const form = new FormData();
form.append('file', fs.createReadStream('/chemin/image.jpg'));

fetch('https://votre-site.com/ghost/api/admin/images/upload/', {
  method: 'POST',
  headers: { Authorization: `Ghost ${token}` },
  body: form
}).then(res => res.json()).then(data => console.log(data.images[0].url));

Pour une startup, utilisez cela pour importer des images depuis Google Drive via un script cron.

Gestion des Thèmes : Upload et Activation Automatisés

Les thèmes Ghost sont des ZIP avec package.json. L'API permet de les uploader et activer sans l'admin.

Endpoints

POST /admin/themes/upload/ : Upload un thème ZIP.
PUT /admin/themes/{name}/activate/ : Active un thème par nom.

Exemple cURL pour upload :

curl -X POST https://votre-site.com/ghost/api/admin/themes/upload/ \
  -H "Authorization: Ghost <token>" \
  -F "file=@/chemin/theme.zip"

Réponse :

{
  "themes": [{
    "name": "mon-theme",
    "package": { "name": "mon-theme", "version": "1.0.0" },
    "active": false,
    "templates": [{ "filename": "post.hbs", "name": "Post" }]
  }]
}

Activation :

curl -X PUT https://votre-site.com/ghost/api/admin/themes/mon-theme/activate/ \
  -H "Authorization: Ghost <token>"

Permissions : Seul Owner peut activer. Pas de delete direct mentionné ; gérez via FTP ou admin.

En JS :

// Similaire à images, avec FormData pour le ZIP
fetch('https://votre-site.com/ghost/api/admin/themes/upload/', {
  method: 'POST',
  headers: { Authorization: `Ghost ${token}` },
  body: form  // avec file: theme.zip
}).then(() => {
  // Puis activate
  fetch(`https://votre-site.com/ghost/api/admin/themes/mon-theme/activate/`, {
    method: 'PUT',
    headers: { Authorization: `Ghost ${token}` }
  });
});

Utile pour des startups testant des thèmes A/B via CI/CD (GitHub Actions).

Gestion des Utilisateurs : Staff et Invites

L'API gère les utilisateurs staff (rôles : Owner, Admin, Author, etc.). CRUD basique pour ajouter/éditer.

Endpoints

GET /admin/users/ : Liste les staff.
POST /admin/users/ : Ajouter un utilisateur.
PUT /admin/users/{id}/ : Éditer.
Pas de delete direct (sécurité).

Exemple GET cURL :

curl -X GET https://votre-site.com/ghost/api/admin/users/ \
  -H "Authorization: Ghost <token>"

Réponse partielle :

{
  "users": [{
    "id": "user-id",
    "name": "John Doe",
    "email": "[email protected]",
    "role": "Author"
  }],
  "meta": { "pagination": { ... } }
}

Pour ajouter (rôles via paramètre role) :

curl -X POST https://votre-site.com/ghost/api/admin/users/ \
  -H "Authorization: Ghost <token>" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"name":"New User","email":"[email protected]","role":"Contributor"}]}'

Invites : Utilisez l'endpoint pour envoyer des invitations (détails dans docs users/invites, non fetchés mais standards).

Permissions : Owner seulement pour changer rôles. En 2025, supporte 2FA via session.

Exemple JS pour lister :

api.users.browse().then(users => console.log(users));

Pour SMB, automatisez l'ajout de freelances comme Authors.

Gestion des Membres : Abonnés et Imports

Les membres sont vos abonnés payants/gratuits. API pour CRUD et imports.

Endpoints

GET /admin/members/ : Liste (avec include=subscription pour détails paiements).
POST /admin/members/ : Créer.
PUT /admin/members/{id}/ : Mettre à jour (labels, notes).
Imports : Via bulk POST ou CSV upload (non direct, via script).

Exemple GET :

curl -X GET "https://votre-site.com/ghost/api/admin/members/?include=subscription&limit=10" \
  -H "Authorization: Ghost <token>"

Réponse :

{
  "members": [{
    "id": "member-id",
    "name": "Jane Smith",
    "email": "[email protected]",
    "subscribed": true,
    "subscription": { "status": "active", "tier": "paid" }
  }]
}

Créer membre :

curl -X POST https://votre-site.com/ghost/api/admin/members/ \
  -H "Authorization: Ghost <token>" \
  -d '{"members":[{"name":"New Member","email":"[email protected]","subscribed":true}]}'

Labels/notes : Ajoutez via PUT, e.g., {"labels":[{"name":"vip"}]}.

En JS :

api.members.add({ members: [{ name: 'New', email: '[email protected]' }] });

Pour startups, importez depuis CSV pour onboarder rapidement une audience.

Gestion des Tiers : Abonnements Payants

Les tiers définissent vos niveaux d'abonnement (free/paid). Liés à Stripe.

Endpoints

GET /admin/tiers/ : Liste (include=monthly_price,yearly_price,benefits).
POST /admin/tiers/ : Créer.
PUT /admin/tiers/{id}/ : Éditer.
DELETE /admin/tiers/{id}/ : Archiver.

Paramètres clés : name, description, slug, type (free/paid), active, visibility (public/none), monthly_price (500 pour 5 USD), benefits (array de strings).

Exemple GET :

curl -X GET "https://votre-site.com/ghost/api/admin/tiers/?include=monthly_price,benefits" \
  -H "Authorization: Ghost <token>"

Réponse :

{
  "tiers": [{
    "id": "tier-id",
    "name": "Bronze",
    "slug": "bronze",
    "type": "paid",
    "active": true,
    "monthly_price": { "amount": 500, "currency": "USD" },
    "benefits": ["Accès basique"]
  }]
}

Créer :

curl -X POST https://votre-site.com/ghost/api/admin/tiers/ \
  -H "Authorization: Ghost <token>" \
  -d '{"tiers":[{"name":"Premium","slug":"premium","type":"paid","monthly_price":1200,"benefits":["Accès complet"]}]}'

Filtres : filter=type:paid+active:true. Lié aux offres pour discounts.

En JS :

api.tiers.add({
  tiers: [{
    name: 'Premium',
    type: 'paid',
    monthly_price: 1200
  }]
});

Idéal pour tester de nouveaux pricing models.

Gestion des Offres : Promotions et Discounts

Les offres sont des promos liées aux tiers (e.g., 50% off premier mois).

Endpoint Structure

GET /admin/offers/ : Liste.
POST /admin/offers/ : Créer (lié à tier, avec discount et expires_at).
PUT /admin/offers/{id}/ : Éditer.
DELETE /admin/offers/{id}/ .

Objet offre : Inclut tier_id, name, slug, type (paid/free_trial), duration, duration_type (month/year), cadence (multiple/single-use).

Exemple création (inféré) :

curl -X POST https://votre-site.com/ghost/api/admin/offers/ \
  -H "Authorization: Ghost <token>" \
  -d '{"offers":[{"name":"Promo 50%","tier":"premium-tier-id","discount":50,"expires_at":"2025-12-31"}]}'

Utilisez pour Black Friday ou onboarding.

Gestion des Newsletters : Configuration Automatisée

Newsletters contrôlent les envois email. Par défaut, une par site.

Endpoints

GET /admin/newsletters/ : Liste (limit=50).
POST /admin/newsletters/ : Créer.
PUT /admin/newsletters/{id}/ : Éditer (status: active/archived).
Validation sender_email : Nullable, mais vérifiez SPF/DKIM.

Paramètres : name, description, sender_name, sender_email, status, visibility (members/public), subscribe_on_signup.

Exemple GET :

curl -X GET "https://votre-site.com/ghost/api/admin/newsletters/?limit=50" \
  -H "Authorization: Ghost <token>"

Réponse :

{
  "newsletters": [{
    "id": "nl-id",
    "name": "Newsletter Principale",
    "description": "Contenu hebdo",
    "status": "active",
    "sender_email": "[email protected]"
  }]
}

Créer :

curl -X POST https://votre-site.com/ghost/api/admin/newsletters/ \
  -H "Authorization: Ghost <token>" \
  -d '{"newsletters":[{"name":"Tech News","description":"Tech hebdo","status":"active"}]}'

En JS : api.newsletters.add({ newsletters: [...] });

Pour SMB, automatisez la création de newsletters thématiques.

Webhooks : Automatisation des Événements

Les webhooks notifient une URL externe sur événements (e.g., member.created).

Endpoints

POST /admin/webhooks/ : Créer (avec event array, target_url, secret).
PUT /admin/webhooks/{id}/ : Éditer.
DELETE /admin/webhooks/{id}/ : Supprimer.

Événements : member.created, post.published, subscription.created, etc. (liste complète dans docs).

Exemple création :

curl -X POST https://votre-site.com/ghost/api/admin/webhooks/ \
  -H "Authorization: Ghost <token>" \
  -d '{"webhooks":[{"name":"Mon Webhook","event":["member.created"],"target_url":"https://mon-app.com/webhook","secret":"mon_secret"}]}'

Test : Ghost envoie un payload JSON signé avec HMAC-SHA256 (vérifiez via secret).

En JS :

api.webhooks.add({
  webhooks: [{
    name: 'Slack Notify',
    event: ['post.published'],
    target_url: 'https://hooks.slack.com/...',
    secret: 'secret'
  }]
});

Pour startups, connectez à Slack ou Mailchimp pour notifications auto.

Conclusion : Automatisez Votre Flux Ghost

Avec l'Admin API, vous contrôlez 100% de Ghost par code. Commencez par des scripts simples en JS pour les membres et tiers, puis étendez aux webhooks pour des intégrations. Testez en local avec Ghost CLI. Pour plus, consultez les docs officielles.

Admin API Ghost Détail

Admin API Ghost : Gestion Complète Images, Thèmes, Membres, Tiers & Webhooks par Code

Authentification : Première Étape Essentielle

Méthode Recommandée : Token d'Intégration

Autres Options

Gestion des Images : Upload Simple et Efficace

Endpoint Principal

Gestion des Thèmes : Upload et Activation Automatisés

Endpoints

Gestion des Utilisateurs : Staff et Invites

Endpoints

Gestion des Membres : Abonnés et Imports

Endpoints

Gestion des Tiers : Abonnements Payants

Endpoints

Gestion des Offres : Promotions et Discounts

Endpoint Structure

Gestion des Newsletters : Configuration Automatisée

Endpoints

Webhooks : Automatisation des Événements

Endpoints

Conclusion : Automatisez Votre Flux Ghost

You may be interested

Tutoriels Ghost

Fonctionnalités Avancées Ghost