seo-generator-server/API.md

API Documentation - SEO Generator Server

🚀 Endpoints API Disponibles

Base URL

http://localhost:3002/api

---

📝 GESTION ARTICLES

GET /api/articles

Récupère la liste des articles générés.

Query Parameters:

• limit (optional): Nombre d'articles à retourner (défaut: 50)
• offset (optional): Position de départ (défaut: 0)
• project (optional): Filtrer par projet
• status (optional): Filtrer par statut

Response:

{
  "success": true,
  "data": {
    "articles": [...],
    "total": 150,
    "limit": 50,
    "offset": 0
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}

GET /api/articles/:id

Récupère un article spécifique.

Query Parameters:

• format (optional): Format de réponse (json, html, text)

Response:

{
  "success": true,
  "data": {
    "id": "article_123",
    "content": "...",
    "metadata": {...}
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}

POST /api/articles

Crée un nouvel article.

Request Body:

{
  "keyword": "plaque personnalisée",
  "project": "client_xyz",
  "config": {
    "selectiveStack": "standardEnhancement",
    "adversarialMode": "light",
    "humanSimulationMode": "none",
    "patternBreakingMode": "none"
  },
  "personalityPreference": {
    "nom": "Marc",
    "style": "professionnel"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "article_456",
    "article": {...},
    "config": {...}
  },
  "message": "Article créé avec succès",
  "timestamp": "2025-09-16T00:00:00.000Z"
}

---

📁 GESTION PROJETS

GET /api/projects

Récupère la liste des projets.

Response:

{
  "success": true,
  "data": {
    "projects": [...],
    "total": 25
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}

POST /api/projects

Crée un nouveau projet.

Request Body:

{
  "name": "Projet Client XYZ",
  "description": "Génération de contenu SEO pour le client XYZ",
  "config": {
    "defaultPersonality": "Marc",
    "selectiveStack": "fullEnhancement"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "project_789",
    "name": "Projet Client XYZ",
    "description": "...",
    "config": {...},
    "createdAt": "2025-09-16T00:00:00.000Z",
    "articlesCount": 0
  },
  "message": "Projet créé avec succès"
}

---

📋 GESTION TEMPLATES

GET /api/templates

Récupère la liste des templates XML.

Response:

{
  "success": true,
  "data": {
    "templates": [...],
    "total": 12
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}

POST /api/templates

Crée un nouveau template.

Request Body:

{
  "name": "Template Article Blog",
  "content": "<?xml version='1.0' encoding='UTF-8'?>...",
  "description": "Template pour articles de blog SEO",
  "category": "blog"
}

Response:

{
  "success": true,
  "data": {
    "id": "template_101",
    "name": "Template Article Blog",
    "content": "...",
    "description": "...",
    "category": "blog",
    "createdAt": "2025-09-16T00:00:00.000Z"
  },
  "message": "Template créé avec succès"
}

---

⚙️ CONFIGURATION

GET /api/config/personalities

Récupère la configuration des personnalités.

Response:

{
  "success": true,
  "data": {
    "personalities": [
      {
        "nom": "Marc",
        "style": "professionnel et précis",
        "description": "...",
        "connecteurs": ["par ailleurs", "en effet"]
      }
    ],
    "total": 15
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}

---

📊 MONITORING

GET /api/health

Health check du système.

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-09-16T00:00:00.000Z",
    "version": "1.0.0",
    "uptime": 3600,
    "memory": {...},
    "environment": "development"
  }
}

GET /api/metrics

Métriques système et statistiques.

Response:

{
  "success": true,
  "data": {
    "articles": {
      "total": 1250,
      "recent": 45
    },
    "projects": {
      "total": 25
    },
    "templates": {
      "total": 12
    },
    "system": {
      "uptime": 3600,
      "memory": {...},
      "platform": "linux",
      "nodeVersion": "v24.3.0"
    }
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}

---

🎭 ENDPOINTS EXISTANTS (Compatibilité)

GET /api/status

Statut du serveur.

GET /api/personalities

Liste des personnalités (legacy).

POST /api/generate-simple

Génération simple avec mot-clé.

POST /api/test-modulaire

Test modulaire individuel.

POST /api/workflow-modulaire

Workflow complet modulaire.

POST /api/benchmark-modulaire

Benchmark des stacks.

---

🔧 Configuration par Défaut

Stacks Selective Enhancement

• lightEnhancement
• standardEnhancement
• fullEnhancement
• creativeEnhancement
• adaptive

Modes Adversarial

• none
• light
• standard
• heavy
• adaptive

Modes Human Simulation

• none
• lightSimulation
• standardSimulation
• heavySimulation
• personalityFocus
• adaptive

Modes Pattern Breaking

• none
• syntaxFocus
• connectorsFocus
• structureFocus
• styleFocus
• comprehensiveFocus
• adaptive

---

🚨 Gestion d'Erreurs

Toutes les erreurs retournent un format standard :

{
  "success": false,
  "error": "Description de l'erreur",
  "message": "Message détaillé",
  "timestamp": "2025-09-16T00:00:00.000Z"
}

Codes d'Erreur

• 400: Bad Request - Paramètres invalides
• 404: Not Found - Ressource non trouvée
• 500: Internal Server Error - Erreur serveur

---

📝 Exemples d'Utilisation

Créer un article simple

curl -X POST http://localhost:3002/api/articles \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "plaque personnalisée",
    "project": "test",
    "config": {
      "selectiveStack": "standardEnhancement",
      "adversarialMode": "light"
    }
  }'

Récupérer les métriques

curl http://localhost:3002/api/metrics

Créer un projet

curl -X POST http://localhost:3002/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon Projet SEO",
    "description": "Projet de test"
  }'

---

🔄 Intégration avec Google Sheets

L'API utilise automatiquement l'intégration Google Sheets pour :

• Récupérer les données de lignes spécifiques
• Charger les 15 personnalités disponibles
• Sauvegarder les articles générés
• Maintenir la cohérence des données