API publique (plugin & intégrations)

Easy Content Flow expose une API publique qui permet à n'importe quelle intégration (le plugin WordPress, un autre CMS, un site sur mesure, un script ou un outil d'automatisation) de générer du contenu, suivre vos cocons et récupérer vos articles par programmation. Les réponses sont du HTML standard : rien n'y est propre à WordPress.

Vous authentifiez vos requêtes avec une clé API que vous générez depuis votre tableau de bord, et l'API renvoie des données prêtes à publier (HTML, titre SEO, méta-description, image).

URL de base

https://easycontentflow.com/api/public/v1

Tous les chemins indiqués dans ce guide sont relatifs à cette URL.

Conventions

Identifiants (content_id, cocoon_id…) : chaînes opaques. Conservez-les tels quels, ne présumez pas de leur format.
Dates (created_at) : entier, en millisecondes depuis le 1ᵉʳ janvier 1970.
Corps des requêtes POST : champs en camelCase.
Corps des réponses : champs en snake_case.

Authentification

Chaque requête doit inclure votre clé API dans l'en-tête Authorization, au format Bearer :

Authorization: Bearer ecf_live_xxxxxxxx.xxxxxxxxxxxx

Obtenir une clé

Dans votre tableau de bord Easy Content Flow, ouvrez API et plugin WordPress.
Cliquez sur Créer une clé et donnez-lui un nom (ex. « Mon site vitrine »).
La clé (ecf_live_…) s'affiche une seule fois. Copiez-la immédiatement et conservez-la en lieu sûr — elle n'est plus récupérable ensuite.
Renseignez cette clé dans votre intégration (réglages du plugin WordPress, ou variable d'environnement de votre script).

attention

La clé n'est affichée qu'à sa création. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Clé liée à un projet

À la création d'une clé, vous pouvez la lier à un projet (un projet = un site, gérés depuis votre tableau de bord). Une clé liée à un projet ne voit alors que les contenus et cocons de ce projet — c'est la configuration recommandée pour connecter un site (plugin WordPress ou autre) : il ne liste que ses propres contenus, sans tri manuel. Les contenus créés via cette clé sont automatiquement rattachés au projet.

Une clé sans projet conserve le comportement historique : elle accède à tous vos contenus. Les clés existantes ne changent donc pas de comportement.

Révoquer une clé

Depuis la même page API et plugin WordPress, révoquez une clé à tout moment. Une clé révoquée cesse immédiatement de fonctionner (réponse 401). Vous pouvez créer autant de clés que nécessaire (une par site, par exemple).

Limite de débit

L'API est limitée à 60 requêtes par minute et par clé. Au-delà, elle répond avec un code 429 :

{ "detail": "Rate limit exceeded: 60 per 1 minute" }

L'API ne renvoie pas d'en-tête Retry-After : votre intégration doit gérer ce cas elle-même (attendre ~60 secondes avant de réessayer).

:::warning Débit de soumission ≠ débit de génération La limite de 60 requêtes/minute concerne la soumission de requêtes à l'API, pas le rythme auquel vos contenus sont réellement générés.

La génération de contenu est asynchrone : POST /contents place votre demande dans une file d'attente, et le contenu est produit en arrière-plan. La génération d'un contenu prend plusieurs minutes, et le débit réel est de l'ordre de quelques contenus par minute (traitement asynchrone partagé).

Ne dimensionnez pas votre intégration en supposant 60 contenus générés par minute. Soumettez vos demandes, puis interrogez GET /contents/{content_id} jusqu'à ce que job_status passe à done. :::

Codes d'erreur

Code	Signification
`400`	`contentType` inconnu (sur la création de contenu)
`401`	Clé API absente, invalide ou révoquée
`402`	Crédits insuffisants pour générer le contenu
`403`	En-tête `Authorization` manquant
`429`	Limite de débit dépassée (voir ci-dessus)

Endpoints

Les 8 endpoints ci-dessous requièrent tous l'en-tête Authorization: Bearer ….

`GET /me` — Compte et crédits

curl https://easycontentflow.com/api/public/v1/me \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

{
  "email": "client@example.com",
  "credits_remaining": 42,
  "credits": {
    "content": 42,
    "cocoon": 5
  }
}

credits_remaining : crédits de contenu disponibles (identique à credits.content).
credits.content / credits.cocoon : détail par type de crédit.

`GET /personas` — Liste des personas

curl https://easycontentflow.com/api/public/v1/personas \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

[
  { "personna_id": "b3f1c2a4-8d7e-4a1b-9c2d-0e1f2a3b4c5d", "label": "Expert SEO" }
]

`GET /projects` — Liste des projets

Renvoie vos projets. Une clé liée à un projet ne renvoie que celui-ci.

curl https://easycontentflow.com/api/public/v1/projects \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

[
  {
    "project_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "Mon site façades",
    "website_url": "https://mon-site.fr"
  }
]

Anciens cocons (avant le 27 octobre 2026)

Les cocons créés avec l'ancienne version de l'outil restent lisibles, et leurs articles restent à générer avec POST /contents (articleId). Les nouveaux cocons se créent et se lisent avec les routes /cocoons-v3 décrites plus bas.

`GET /cocoons` — Liste des anciens cocons

Paramètres :

Paramètre	Type	Défaut	Description
`page`	entier ≥ 1	`1`	Numéro de page
`per_page`	entier 1–100	`20`	Taille de page
`status`	texte	—	Filtre : `pending` \| `done` \| `error`
`project_id`	texte	—	Filtre par projet (ignoré si la clé est liée à un projet)

curl "https://easycontentflow.com/api/public/v1/cocoons?page=1&per_page=20&status=done" \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

{
  "items": [
    {
      "cocoon_id": "9a2e7b10-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "name": "Panneau solaire",
      "main_keyword": "panneau solaire",
      "website": "https://exemple.fr",
      "job_status": "done",
      "created_at": 1733300000000,
      "error_message": null,
      "project_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
    }
  ],
  "total": 1,
  "page": 1
}

`GET /cocoons/{cocoon_id}` — Détail d'un ancien cocon

Renvoie le cocon et la liste de ses articles planifiés.

curl https://easycontentflow.com/api/public/v1/cocoons/9a2e7b10-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

{
  "cocoon_id": "9a2e7b10-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
  "main_keyword": "panneau solaire",
  "articles": [
    {
      "article_id": "1f0a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "title": "Comment choisir ses panneaux solaires",
      "keyword": "choisir panneau solaire",
      "volume": 1300,
      "content_id": "c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f"
    }
  ]
}

content_id vaut null tant qu'aucun contenu n'a été généré pour cet article.

Cocons sémantiques

Un cocon se mène de bout en bout par l'API, comme dans l'application :

Créer le cocon : POST /cocoons-v3 (un crédit cocon). L'outil lit le site et prépare la fiche de cadrage, en une minute environ (status: cadrage_running, puis cadrage_ready).
Relire et valider la fiche : GET /cocoons-v3/{cocoon_id} (champ perimeter), puis PUT /cocoons-v3/{cocoon_id}/perimeter avec "validate": true, corrections comprises. Une fois validée, la fiche ne se modifie plus (seul rubric_categories change encore).
Calculer le plan : POST /cocoons-v3/{cocoon_id}/plan, environ 5 minutes (plan_running, puis plan_ready). Le plan se calcule une seule fois par cocon.
Rédiger les pages : une à une (…/pages/{page_id}/write) ou en lot (…/write-batch), un crédit contenu par page ; le résultat de chaque page se lit avec GET /contents/{content_id}.

Pendant un calcul (cadrage_running, plan_running), interrogez GET /cocoons-v3/{cocoon_id} toutes les 10 à 30 secondes : progress (0-100) et step disent où il en est. Toute modification pendant un calcul répond 409. En cas d'erreur (status: error, error_message), relancez l'étape : POST …/cadrage si la fiche n'est pas prête, sinon POST …/plan (possible tant qu'aucun plan n'a été livré).

`POST /cocoons-v3` — Créer un cocon

Consomme un crédit cocon (402 sinon, rien n'est créé).

{
  "site": "exemple.fr",
  "keyword": "panneau solaire",
  "sense": "installer des panneaux solaires chez soi : choix, pose, aides, rentabilité",
  "localSite": false,
  "sitemaps": [],
  "projectId": null
}

Champ	Description
`site`	Adresse ou domaine du site à lire
`keyword`	Sujet du cocon, en un ou deux mots, tel que les internautes le tapent
`sense`	Une phrase qui lève toute ambiguïté sur le sujet
`localSite`	`true` pour une activité locale (artisan, commerce)
`sitemaps`	Sitemaps à lire en plus de ceux annoncés par `robots.txt` (facultatif)
`projectId`	Projet où ranger le cocon (imposé si la clé est liée à un projet)
`project`	Site pas encore en ligne : `{ "activity": "…", "target": "…", "values": "…" }` (activité et cible : 10 caractères au moins) ; `site` devient alors l'adresse prévue, facultative

Réponse 201 : le cocon (même format que GET /cocoons-v3/{cocoon_id}), avec status: cadrage_running. Si le compte a déjà un cocon sur ce sujet et ce site, l'API répond 409 avec detail.cocoonId : reprenez ce cocon plutôt que d'en créer un second.

`GET /cocoons-v3` — Liste des cocons

Paramètre facultatif : project_id (ignoré si la clé est liée à un projet).

[
  {
    "cocoon_id": "5b1c…",
    "keyword": "panneau solaire",
    "sense": "Installer des panneaux solaires chez soi",
    "site": "exemple.fr",
    "status": "plan_ready",
    "created_at": 1733300000000,
    "updated_at": 1733400000000,
    "project_id": null,
    "pages_total": 24,
    "pages_existing": 6,
    "pages_written": 4,
    "pages_to_create": 14
  }
]

status : cadrage_running, cadrage_ready, plan_running, plan_ready ou error.
pages_existing : pages déjà publiées sur le site ; pages_written : pages dont la rédaction est lancée ; pages_to_create : le reste.

`GET /cocoons-v3/{cocoon_id}` — Cocon, fiche et plan

{
  "cocoon_id": "5b1c…",
  "keyword": "panneau solaire",
  "sense": "Installer des panneaux solaires chez soi",
  "site": "exemple.fr",
  "status": "plan_ready",
  "error_message": null,
  "project_id": null,
  "progress": null,
  "step": null,
  "perimeter": { "include": ["…"], "exclude": ["…"], "rubrics": ["…"], "validated": true },
  "created_at": 1733300000000,
  "updated_at": 1733400000000,
  "pages": [
    {
      "page_id": "a1",
      "role": "page",
      "silo": "Installation",
      "title": "Installer ses panneaux solaires",
      "keyword": "installation panneau solaire",
      "volume": 900,
      "url": null,
      "angle": "Les étapes, du devis à la mise en service",
      "slug": "installation/installer-panneaux-solaires",
      "planned_url": "https://exemple.fr/installation/installer-panneaux-solaires/",
      "content_id": null,
      "category": { "name": "Installation", "url": "https://exemple.fr/categorie/installation/", "id": "12", "new": false }
    }
  ]
}

progress, step : avancement du calcul en cours (null sinon).
perimeter : la fiche de cadrage (thèmes couverts, écartés avec leur raison, rubriques…) ; validated dit si elle est validée. Vide tant que le premier brouillon n'est pas prêt.
pages : vide tant que le plan n'est pas calculé.
role : pilier, hub (page mère d'une rubrique) ou page.
url : adresse de la page si elle existe déjà sur le site.
angle : ce que la page apporte au lecteur.
planned_url : adresse que les autres pages du cocon utilisent pour lier celle-ci (son adresse publiée, sinon son adresse prévue). Publiez chaque page à son adresse prévue et le maillage fonctionne tel quel, quel que soit votre CMS. Si votre CMS impose une autre adresse, remplacez planned_url par l'adresse réelle dans le content_html des autres pages du cocon (le plugin WordPress le fait automatiquement).
slug : adresse prévue pour une page à créer. Publiez la page à cette adresse pour que les liens entre les pages du cocon fonctionnent.
slug_proposed : true si cette adresse a été proposée par l'outil d'après le titre (sans les petits mots) et pas encore vérifiée par l'éditeur.
content_id : contenu ECF de la page, une fois sa rédaction lancée. Son résultat se récupère avec GET /contents/{content_id}.
rewrite : true si la page, déjà publiée (url), a été envoyée en réécriture. Son contenu (content_id) remplace la page à son adresse : mettez à jour la page existante au lieu d'en publier une autre.
category : catégorie du site où publier la page, celle de sa rubrique. Une rubrique reprend une catégorie existante quand elle convient ; id est l'identifiant de votre CMS si vous avez envoyé vos catégories (voir PUT /site-categories). new: true : le site n'a pas encore cette catégorie, le client l'a validée dans la fiche du cocon, créez-la avant d'y ranger la page. Absent pour le pilier et pour un cocon cadré avant octobre 2026.

`PUT /cocoons-v3/{cocoon_id}/perimeter` — Corriger et valider la fiche

{ "perimeter": { "exclude": ["piscines municipales : hors offre, le site vise les particuliers"] }, "validate": true }

perimeter contient les seuls champs à changer, repris tels que GET /cocoons-v3/{cocoon_id} les renvoie ; le reste de la fiche est gardé. validate: true valide la fiche (indispensable avant le plan) ; false l'enregistre en brouillon. Une fiche validée est définitive : seul rubric_categories (la catégorie du site de chaque rubrique) change encore, et la fiche reste validée ; tout autre champ modifié répond 409. Réponse : le cocon.

`POST /cocoons-v3/{cocoon_id}/plan` — Calculer le plan

Sans corps. Calcule le plan avec la fiche validée (environ 5 minutes), une seule fois par cocon : 409 si un plan a déjà été livré. Si le calcul échoue sans livrer de plan (status: error), vous pouvez le relancer. 400 si la fiche n'est pas validée. Réponse : le cocon, status: plan_running.

`POST /cocoons-v3/{cocoon_id}/cadrage` — Refaire la fiche

Sans corps. Relance le brouillon de la fiche, après une erreur ou pour repartir de zéro, tant que la fiche n'est pas validée (409 ensuite). Réponse : le cocon, status: cadrage_running.

`DELETE /cocoons-v3/{cocoon_id}` — Supprimer un cocon

Supprime la fiche et le plan. Les pages déjà rédigées restent dans vos contenus ; le crédit cocon n'est pas rendu. Réponse : { "deleted": "…" }.

`PUT /site-categories` — Catégories de votre site

Envoyez les catégories éditoriales de votre site, quel que soit votre CMS : au cadrage d'un cocon sur ce site, chaque rubrique reprend une de ces catégories quand elle convient, sous son nom exact, et le plan vous rend leur id. Sans envoi, l'outil repère les catégories en lisant le site (pages de catégorie, dossiers d'articles). Chaque envoi remplace le précédent.

{
  "site": "exemple.fr",
  "categories": [
    { "name": "Installation", "url": "https://exemple.fr/categorie/installation/", "id": "12" },
    { "name": "Aides et financement", "id": "15" }
  ]
}

name est obligatoire, url et id facultatifs (500 catégories au plus). Réponse : { "site": "exemple.fr", "count": 2 }.

`POST /cocoons-v3/{cocoon_id}/pages/{page_id}/write` — Rédiger une page

Lance la rédaction d'une page du plan, avec sa requête, son brief et ses liens vers les autres pages du cocon. Consomme un crédit contenu (402 sinon).

{ "personnaId": "b3f1c2a4-…", "includeFaq": true, "includeInfographics": true, "infographicStyle": "presse" }

Tous les champs sont facultatifs : personnaId, ce que contient l'article, comme pour POST /contents (includeEssentiel, includeFaq, includeInfographics, infographicStyle), et specificInstructions : vos consignes et vos données pour cette page (chiffres, études, exemples, lien à insérer, angle à privilégier ou à éviter). Elles sont transmises au rédacteur avec le brief du cocon et font foi. Sans ce champ, la page reçoit celles enregistrées dans l'écran (détail de la page). Réponse 201 : { "content_id": "…", "job_status": "pending", "created_at": … }.

Page déjà publiée sur le site : ajoutez "rewrite": true pour la réécrire. Une nouvelle version complète est rédigée sur l'angle et la requête du plan, pour remplacer la page à la même adresse (la page porte ensuite rewrite: true). Sans ce champ, l'API répond 400 pour une page déjà publiée. Elle répond aussi 409 si la rédaction est déjà lancée ou si un calcul est en cours sur le cocon.

`POST /cocoons-v3/{cocoon_id}/write-batch` — Rédiger plusieurs pages

{ "pageIds": ["a1", "a2", "b4"], "personnaId": "b3f1c2a4-…", "includeFaq": true }

Chaque page part comme avec la route précédente (même brief, mêmes liens, un crédit contenu par page), avec le même persona et les mêmes options pour tout le lot. Consignes et données (facultatives, elles font foi) :

pageInstructions : celles propres à chaque page, { "a1": "…", "b4": "…" }. Une page absente reçoit celles enregistrées dans l'écran (détail de la page) ;
specificInstructions : celles communes à tout le lot (ton, lien à insérer partout, données générales), ajoutées à celles de chaque page. Le rédacteur de chaque page n'en garde que ce qui concerne son sujet. Une page refusée n'arrête pas les autres. Réponse 201 :

{
  "launched": [{ "page_id": "a1", "content_id": "c4d5…" }],
  "skipped": [{ "page_id": "a2", "reason": "Page déjà envoyée en rédaction" }]
}

Crédits épuisés : la page et toutes les suivantes reviennent dans skipped.

`POST /contents` — Créer un contenu

Lance la génération d'un contenu. Cette opération consomme un crédit (402 si vous n'en avez plus).

Corps de requête (camelCase). Champs principaux :

Champ	Type	Description
`contentType`	texte	Type de contenu (défaut `agentic`). Valeurs : `agentic`, `news`, `product_card`, `ecommerce_category`, `affiliate`, `service`, `personna`
`keyword`	texte	Mot-clé principal
`toneOfVoice`	texte	Ton de voix (ignoré si `personnaId` est fourni)
`personnaId`	texte	Persona à utiliser comme ton
`cocoonId` / `articleId`	texte	Rattachement à un cocon / un article
`country`	texte	Pays (défaut `fr`)
`specificInstructions`	texte	Instructions ponctuelles
`includeInfographics`	booléen	Article SEO : 1 ou 2 infographies d'après les chiffres de l'article (par défaut `false`, sans crédit en plus)
`infographicStyle`	texte	Style des infographies : `presse` (par défaut), `decodeurs`, `rapport` ou `encre`
`projectId`	texte	Projet auquel rattacher le contenu. Ignoré si la clé est liée à un projet (le contenu est alors rattaché au projet de la clé)

Champs spécifiques au type service :

Champ	Type	Description
`serviceName`	texte	Nom du service (obligatoire pour ce type)
`serviceDescription`	texte	Description libre du service (obligatoire)
`serviceWebsiteUrl`	texte	URL du site client, analysée pour le ton et le positionnement
`serviceCity`	texte	Ville / zone. Renseignée → page locale (schema LocalBusiness) ; vide → page corporate
`serviceTargetAudience`	texte	Cible client
`serviceKeyBenefits`	liste de textes	Arguments clés / USP
`serviceTestimonials`	texte	Témoignages clients, cités tels quels
`ctaType`	texte	Type de CTA : `devis`, `rdv`, `contact`, `appel` ou `auto` (défaut)
`ctaUrl`	texte	URL cible des 3 CTA. Vide → ancre `#contact`
`ctaEnabled`	booléen	`false` = page générée sans aucun CTA (la FAQ et les données structurées sont conservées). Absent ou `true` = 3 CTA inclus (comportement par défaut)

curl -X POST https://easycontentflow.com/api/public/v1/contents \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "agentic",
    "keyword": "panneau solaire monocristallin",
    "toneOfVoice": "Expert, pédagogue",
    "country": "fr"
  }'

Réponse (201) :

{
  "content_id": "c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f",
  "job_status": "pending",
  "created_at": 1733300000000
}

La génération est asynchrone : le contenu est créé avec le statut pending. Récupérez le résultat via GET /contents/{content_id} (voir Cycle d'intégration).

`GET /contents` — Liste des contenus

Paramètres :

Paramètre	Type	Défaut	Description
`page`	entier ≥ 1	`1`	Numéro de page
`per_page`	entier 1–100	`20`	Taille de page
`status`	texte	—	Filtre : `pending` \| `done` \| `error`
`workflow_type`	texte	—	Filtre par type (ex. `agentic`, `news`)
`project_id`	texte	—	Filtre par projet (ignoré si la clé est liée à un projet)

curl "https://easycontentflow.com/api/public/v1/contents?status=done&workflow_type=agentic" \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

{
  "items": [
    {
      "content_id": "c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f",
      "title": "Panneau solaire monocristallin : guide complet",
      "workflow_type": "agentic",
      "job_status": "done",
      "created_at": 1733300000000,
      "word_count": 1850,
      "article_id": null,
      "cocoon_id": null,
      "error_message": null,
      "project_id": null
    }
  ],
  "total": 1,
  "page": 1
}

La liste ne contient pas le HTML de l'article : utilisez le détail (GET /contents/{content_id}) pour le récupérer.

`GET /contents/{content_id}` — Détail d'un contenu

Renvoie le contenu et, lorsqu'il est prêt, le résultat généré.

curl https://easycontentflow.com/api/public/v1/contents/c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f \
  -H "Authorization: Bearer ecf_live_xxxx.xxxx"

Contenu généré (job_status = done) :

{
  "content_id": "c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f",
  "title": "Panneau solaire monocristallin : guide complet",
  "workflow_type": "agentic",
  "job_status": "done",
  "created_at": 1733300000000,
  "word_count": 1850,
  "article_id": null,
  "cocoon_id": null,
  "error_message": null,
  "result": {
    "content_html": "<h1>Panneau solaire monocristallin</h1><p>...</p>",
    "seo_title": "Panneau solaire monocristallin : guide complet",
    "meta_description": "Découvrez comment choisir vos panneaux...",
    "image_url": "https://easycontentflow.com/api/images/abc123"
  }
}

Contenu pas encore prêt (pending ou error) — result vaut null :

{
  "content_id": "c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f",
  "title": "",
  "workflow_type": "agentic",
  "job_status": "pending",
  "created_at": 1733300000000,
  "word_count": 0,
  "article_id": null,
  "cocoon_id": null,
  "error_message": null,
  "result": null
}

Le bloc result (présent uniquement quand job_status = done) :

Champ	Description
`content_html`	Corps HTML de l'article, à insérer dans votre CMS
`seo_title`	Titre SEO
`meta_description`	Méta-description
`image_url`	URL de l'image générée, téléchargeable directement (`null` s'il n'y en a pas)
`images`	Images du corps hébergées par Easy Content Flow (infographies, et deuxième photo des articles de plus de 1 250 mots) : `[{url, alt}]`. Copiez-les sur votre site et remplacez leur adresse dans `content_html` pour ne pas dépendre de nos serveurs (le plugin WordPress le fait pour vous)

À savoir

Identifiants opaques : content_id, cocoon_id, article_id, personna_id sont des clés à conserver telles quelles, sans en interpréter le format.
job_status prend trois valeurs : pending (en cours), done (prêt), error (échec).
Le résultat n'est disponible qu'une fois done. Tant que le contenu est pending, interrogez régulièrement GET /contents/{content_id} jusqu'à obtenir done (ou error).
error_message contient un message explicatif lorsque job_status = error ; sinon null. Il dit ce qui a échoué (service externe indisponible, durée dépassée, erreur interne), à quelle étape, si le crédit a été remboursé (« Le crédit utilisé est automatiquement remboursé. ») et si une relance a des chances d'aboutir (« Réessayez dans quelques minutes. », « Vous pouvez la relancer. »). Une erreur interne qui se reproduit à l'identique se signale au support plutôt que de se relancer en boucle.
image_url est une URL complète, téléchargeable sans authentification.
Pagination : total reflète le nombre d'éléments après filtres ; per_page est limité à 100.

Cycle d'intégration

Étapes typiques, quel que soit votre CMS :

Créer le contenu avec POST /contents → récupérez le content_id (statut pending).
Interroger GET /contents/{content_id} jusqu'à ce que job_status passe à done (ou error).
Récupérer result.content_html, result.seo_title, result.meta_description et result.image_url, puis publier sur votre site (copiez au passage les images de result.images).

Avant de créer un contenu, vous pouvez vérifier vos crédits avec GET /me. Pour rédiger les pages d'un cocon, passez par POST /cocoons-v3/{cocoon_id}/pages/{page_id}/write ou …/write-batch : chaque page part avec son brief et ses liens. Pour un ancien cocon, listez-le avec GET /cocoons puis passez son articleId à POST /contents.

:::tip Pensez « file d'attente », pas « temps réel » La génération est asynchrone et prend plusieurs minutes par contenu. Soumettez vos demandes au fil de l'eau, puis pollez GET /contents/{content_id} pour récupérer chaque résultat — n'attendez pas une réponse immédiate et ne comptez pas générer 60 contenus en une minute. Pour de gros volumes, espacez vos créations et laissez la file se vider. :::

Historique des changements

27 octobre 2026 — le cocon de la nouvelle version est ouvert à tous les comptes et se mène entièrement par l'API : POST /cocoons-v3 (création), PUT /cocoons-v3/{cocoon_id}/perimeter (fiche), POST …/cadrage, POST …/plan, POST …/write-batch et DELETE /cocoons-v3/{cocoon_id}. GET /cocoons-v3/{cocoon_id} rend aussi progress, step, perimeter, created_at et updated_at. Les routes /cocoons servent les anciens cocons, sans changement.

Octobre 2026 — uniquement des ajouts : les intégrations existantes continuent de fonctionner sans modification.

Routes des cocons de la nouvelle version : GET /cocoons-v3, GET /cocoons-v3/{cocoon_id} et POST /cocoons-v3/{cocoon_id}/pages/{page_id}/write.
Champs ajoutés au plan d'un cocon : sense, error_message, et pour chaque page angle et planned_url.
POST /contents (article SEO) : includeInfographics et infographicStyle (presse, decodeurs, rapport, encre) ajoutent 1 ou 2 infographies tirées des chiffres de l'article. Le résultat liste les images du corps dans result.images.
Catégories : PUT /site-categories pour envoyer les catégories du site, et category sur chaque page d'un cocon (catégorie existante ou nouvelle).
Réécriture d'une page publiée : rewrite dans le corps de POST /cocoons-v3/{cocoon_id}/pages/{page_id}/write et sur chaque page du plan.
Le plugin WordPress passe en 2.6.0 (catégorie de chaque rubrique, remplacement d'un article publié réécrit) après la 2.3.0. Téléchargez-le depuis la page Plugin WordPress de votre tableau de bord. Les versions suivantes s'installeront directement depuis l'écran « Extensions » de WordPress.

24 octobre 2026 — sécurité, sans changement de format :

Le HTML des contenus ne contient plus rien d'exécutable : scripts (sauf les données structurées JSON-LD), iframes, formulaires, attributs on… et liens javascript: sont retirés à l'enregistrement. Le reste du HTML est inchangé.
POST /contents répond 404 si personnaId ou articleId désigne un persona ou un article d'un autre compte.
Supprimer un projet révoque les clés API limitées à ce projet.
Plugin WordPress 2.6.1 : le texte importé est filtré par WordPress, et « Remplacer l'article publié » ne vise qu'un article ou une page publiés, à l'adresse exacte de la page du cocon, que votre compte peut modifier.

Questions fréquentes

Où trouver ma clé API ? Dans votre tableau de bord, section API et plugin WordPress. La clé s'affiche une seule fois à sa création.

Que faire si j'ai perdu ma clé ? Révoquez-la depuis API et plugin WordPress et créez-en une nouvelle.

Pourquoi mon contenu reste-t-il en pending ? La génération est asynchrone et prend généralement quelques minutes. Interrogez le détail du contenu jusqu'à ce que job_status passe à done.

Combien de requêtes puis-je envoyer ? 60 par minute et par clé. Au-delà, l'API répond 429 ; attendez environ une minute avant de réessayer.

URL de base​

Conventions​

Authentification​

Obtenir une clé​

Clé liée à un projet​

Révoquer une clé​

Limite de débit​

Codes d'erreur​

Endpoints​

GET /me — Compte et crédits​

GET /personas — Liste des personas​

GET /projects — Liste des projets​

Anciens cocons (avant le 27 octobre 2026)​

GET /cocoons — Liste des anciens cocons​

GET /cocoons/{cocoon_id} — Détail d'un ancien cocon​

Cocons sémantiques​

POST /cocoons-v3 — Créer un cocon​

GET /cocoons-v3 — Liste des cocons​

GET /cocoons-v3/{cocoon_id} — Cocon, fiche et plan​

PUT /cocoons-v3/{cocoon_id}/perimeter — Corriger et valider la fiche​

POST /cocoons-v3/{cocoon_id}/plan — Calculer le plan​

POST /cocoons-v3/{cocoon_id}/cadrage — Refaire la fiche​

DELETE /cocoons-v3/{cocoon_id} — Supprimer un cocon​

PUT /site-categories — Catégories de votre site​

POST /cocoons-v3/{cocoon_id}/pages/{page_id}/write — Rédiger une page​

POST /cocoons-v3/{cocoon_id}/write-batch — Rédiger plusieurs pages​

POST /contents — Créer un contenu​

GET /contents — Liste des contenus​

GET /contents/{content_id} — Détail d'un contenu​

À savoir​

Cycle d'intégration​

Historique des changements​

Questions fréquentes​