Documentation API

CalliCMS — API REST v1

Introduction

L’API CalliCMS vous permet d’accéder programmatiquement au contenu de vos projets. Cette API REST utilise JSON pour les échanges de données et supporte CORS pour les applications web.

Rapide
Réponses optimisées
Sécurisé
Clés API 256 caractères
CORS
Support complet
Prérequis et Configuration

Avant d'utiliser l'API, assurez-vous que votre projet et vos contenus sont correctement configurés.

1

Activez votre projet

Votre projet doit avoir le statut

ACTIVE
pour être accessible via l'API.

Navigation : Dashboard → Votre Projet → Paramètres → Status → ACTIVE
2

Publiez vos articles

Seuls les articles avec le statut

PUBLISHED
sont retournés par l'API.

Navigation : Projet → Articles → Sélectionner un article → Status → PUBLISHED
✅ Visible dans l'API
Status: PUBLISHED
❌ Invisible dans l'API
Status: DRAFT, ARCHIVED
3

Récupérez votre clé API

Chaque projet possède une clé API unique de 256 caractères.

Navigation : Projet → Paramètres → API → Clé API → Copier
Format de la clé
cm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Authentification

L'API utilise des clés d'authentification de 256 caractères pour sécuriser l'accès à vos données. Chaque projet possède sa propre clé API unique.

Méthodes d'authentification

x-api-key: cm_your_256_character_api_key
Header recommandé
Authorization: Bearer cm_your_256_character_api_key
Header Bearer token
?apiKey=cm_your_256_character_api_key
Paramètre de requête (non recommandé en production)
Endpoints disponibles
GET
/api/v1/projects/{projectSlug}
Project

Récupère les informations générales du projet et ses statistiques

GET
/api/v1/projects/{projectSlug}/posts
Posts

Liste tous les articles publiés avec pagination et filtres

GET
/api/v1/projects/{projectSlug}/posts/{postSlug}
Posts

Récupère un article spécifique avec les articles liés

GET
/api/v1/projects/{projectSlug}/authors
Authors

Liste tous les auteurs avec le nombre d'articles

GET
/api/v1/projects/{projectSlug}/categories
Categories

Liste toutes les catégories avec le nombre d'articles

Paramètres de requête communs

page
Numéro de page (défaut: 1)
limit
Éléments par page (défaut: 10, max: 100)
search
Recherche textuelle
category
Filtrer par slug de catégorie
author
Filtrer par slug d'auteur
sortBy
Champ de tri (défaut: publishedAt)

Blocs éditoriaux exposés (posts)

tableOfContents
Sommaire saisi dans l'éditeur
images / videos / tables
Médias et tableaux détectés
headings / links / lists
Structure éditoriale extraite du contenu
quotes / codeBlocks / stats
Citations, code et stats de lecture
Exemples de code
// Installation
npm install axios

// Configuration
const API_KEY = 'cm_your_256_character_api_key_here'
const BASE_URL = 'https://your-domain.com/api/v1'

// Fonction utilitaire
const apiCall = async (endpoint, options = {}) => {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
      ...options.headers
    },
    ...options
  })
  
  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`)
  }
  
  return response.json()
}

// Exemples d'utilisation
try {
  // Récupérer les informations du projet
  const project = await apiCall('/projects/my-blog')
  
  // Lister les articles avec pagination
  const posts = await apiCall('/projects/my-blog/posts?page=1&limit=10')
  
  // Rechercher des articles
  const searchResults = await apiCall('/projects/my-blog/posts?search=javascript')
  
  // Filtrer par catégorie
  const techPosts = await apiCall('/projects/my-blog/posts?category=tech')
  
  // Récupérer un article spécifique
  const post = await apiCall('/projects/my-blog/posts/my-article-slug')
  
} catch (error) {
  console.error('Erreur API:', error)
}
Dépannage

Solutions aux problèmes les plus courants rencontrés lors de l'utilisation de l'API.

❌ Erreur 404 - Route non trouvée

Problème : L'URL de votre API retourne une erreur 404
Solutions :
  • Vérifiez que votre serveur Next.js est démarré (npm run dev)
  • Confirmez l'URL : http://localhost:3000/api/v1/projects/YOUR_SLUG/posts
  • Vérifiez que le slug du projet est correct (sans espaces, caractères spéciaux)

⚠️ Erreur 401 - Non autorisé

Problème : Votre clé API est rejetée
Solutions :
  • Vérifiez que la clé API est correcte (256 caractères commençant par "cm_")
  • Confirmez que votre projet est ACTIF (pas DRAFT ou ARCHIVED)
  • Essayez de régénérer votre clé API dans les paramètres du projet
  • Vérifiez le header : x-api-key: VOTRE_CLE

📝 Aucun article retourné

Problème : L'API retourne une liste vide d'articles
Solutions :
  • Vérifiez que vos articles sont PUBLIÉS (pas DRAFT ou ARCHIVED)
  • Confirmez que les articles appartiennent bien au bon projet
  • Essayez sans filtres : /posts (sans paramètres category, author, etc.)
  • Vérifiez la date de publication (publishedAt ne doit pas être dans le futur)

🌐 Problèmes CORS

Problème : Erreurs CORS dans le navigateur
Solutions :
  • CORS est automatiquement géré par l'API (pas de configuration nécessaire)
  • Utilisez l'API depuis votre backend plutôt que depuis le frontend
  • Pour les tests, utilisez un outil comme Postman ou curl
  • En développement, les requêtes depuis localhost sont autorisées

🔍 Test rapide de votre configuration

curl -H "x-api-key: VOTRE_CLE_API" \\
    "http://localhost:3000/api/v1/projects/VOTRE_SLUG"

Cette commande doit retourner les informations de votre projet. Si elle échoue, vérifiez d'abord les prérequis ci-dessus.

Gestion d'erreurs

L'API utilise les codes de statut HTTP standards et retourne des erreurs au format JSON.

401
Unauthorized

Clé API manquante ou invalide

Causes possibles : Clé API incorrecte, projet inactif, ou clé expirée
404
Not Found

Ressource non trouvée

Causes possibles : Projet inexistant, article non publié, ou slug incorrect
429
Too Many Requests

Quota mensuel atteint ou abonnement suspendu

{ "error": "Invalid API key", "code": "INVALID_API_KEY", "timestamp": "2024-01-15T10:30:00Z" }
Limites de taux

Chaque offre comprend un volume mensuel d’appels API. Une tolérance de 10 % évite une coupure brutale avant le blocage.

Starter
250 000
appels API par mois
Pro
1 million
d’appels API par mois
Agence
5 millions
d’appels API par mois