Automatisation

Chinaski expose une API REST JSON pour que les scripts, les cron jobs et les assistants IA puissent lire votre contenu, le créer et le mettre à jour, déclencher des builds et lancer des batch jobs : tout ce que vous cliqueriez normalement dans la zone admin, sauf la suppression. Cette page est le point d'entrée pour l'automatisation ; la référence endpoint par endpoint se trouve ailleurs dans la section Reference, et la surface pour assistants IA a sa propre page MCP.

Authentification

L'accès automatisé utilise des clés API, créées par un admin sous Settings → API Keys. Chaque clé est nommée, a sa propre date d'expiration (optionnelle) et porte un scope read ou write :

• Les clés read peuvent récupérer mais jamais modifier le contenu.
• Les clés write peuvent créer et mettre à jour : explicitement requises pour tout appel POST/PUT, quel que soit ce que ferait le handler.
• Les requêtes s'identifient avec un en-tête X-API-Key. Les clés manquantes ou expirées obtiennent un 401 ; une clé read tentant une écriture obtient un 403.

L'accès API peut être coupé entièrement depuis l'onglet API Keys de l'admin, avec lui désactivé, chaque requête API reçoit un 503 « API access is disabled ».

Le rate limiting est par clé, par 60 secondes, à 100 requêtes par minute par défaut (configurable dans Settings). Le dépasser renvoie un 429 avec un en-tête Retry-After vous indiquant combien de temps attendre.

Chaque usage de clé est consigné dans la piste d'audit avec la méthode et le chemin HTTP, et le timestamp de dernière utilisation est suivi par clé, pratique pour repérer les clés à retirer.

Ce que l'API peut faire

• Lire: pages, posts, blocks, snippets, catégories, documents, navigation, redirections, auteurs, custom fields, couverture de traduction et workflows publiés, recherche par mots-clés, rapports de content gaps, et tous les réglages non secrets. Les listes sont paginées (data plus un bloc meta avec total/page/limit/pages) et allégées sauf si vous demandez les lignes complètes.
• Créer et mettre à jour: POST/PUT pour les pages, posts, blocks, snippets, catégories, documents, auteurs et nav items, y compris les variantes upsert qui créent-ou-mettent-à-jour par slug et langue, plus la configuration des webhooks et l'écriture des réglages. Les valeurs secrètes des réglages sont chiffrées à l'entrée, les clés inconnues sont rejetées par élément, et les valeurs d'URL de webhook sont validées pour la sécurité.
• Builder: POST un déclencheur pour rebuild le site statique (la réponse indique dispatched / already-busy / missing), puis GET le statut de build pour la progression par langue : pages et posts faits vs. total, élément courant et message d'erreur.
• La suppression n'est pas dans l'API: il n'y a aucun endpoint DELETE ; la suppression définitive ou vers la trash se fait dans l'interface admin. Les scripts qui doivent retirer du contenu devraient publier/marquer plutôt que supprimer, ou faire la suppression à la main.

Batch jobs

Pour les tâches lourdes, soumettez un job asynchrone plutôt que de nombreux appels individuels :

• Soumission : POST /api/jobs avec un type (bulk_upsert_pages, bulk_upsert_posts ou bulk_create_blocks) et un tableau items non vide.
• Suivi : GET /api/jobs/:id renvoie le statut du job, la progression (total et fait) et le payload de résultat une fois terminé.

Monitoring : un statut façon GET /build/status est aussi exposé ; et GET /api/health est l'endpoint de health non authentifié que votre monitor d'uptime peut interroger : il rapporte le statut, le nombre de pages publiées, l'heure du dernier build, l'existence d'un build en cours, et signale un avertissement si des pages ont été publiées mais jamais de build.

Workflows assistés par IA

Le serveur MCP intégré est la passerelle prévue pour les assistants IA comme Claude Code : il se lance localement comme un processus JSON-RPC-over-stdio, communique avec cette même API REST via une clé API, et expose des outils de plus haut niveau par-dessus : création de page/post avec blocks en un seul appel, traduction de contenu avec audit automatique des manques, import/upsert en masse, nettoyage des blocks orphelins et audits de qualité de contenu. Pointez-le vers l'URL de votre CMS et une clé API avec permission write, et votre assistant travaille directement sur l'API.

Bonnes habitudes pour les scripts

• Donnez à vos scripts leurs propres clés API nommées afin que les entrées d'audit les identifient distinctement, et fixez une expiration aux clés temporaires. L'usage d'une clé met à jour last_used_at audité ; nettoyez les clés inutilisées depuis l'onglet API Keys.
• Prenez au sérieux la séparation read/write : une clé qui ne fait que lire ne devrait pas détenir la permission write « au cas où ».
• Soyez propriétaire des secrets : les réglages récupérés via l'API n'incluent jamais les valeurs secrètes (le mot de passe SMTP et les secrets de webhook sont toujours omis), et le chemin d'écriture chiffre correctement les nouvelles valeurs secrètes.