API de lecture
Une API de contenu SEO sur chaque article que vous avez planifié.
L’API répond à la question que pose un rapport : qu’avons-nous publié, où, dans quelle langue, et que dit l’article. Un endpoint par besoin, une forme fixe, rien à installer — et aucun moyen pour une intégration de réécrire dans votre contenu.
Lire la référence de l’APIJSON via HTTPSClé Bearer ou x-api-keyEn lecture seule, toujours
Que pouvez-vous demander à l’API de contenu ?
Deux endpoints, cinq paramètres, une enveloppe. C’est toute la surface — d’où l’absence de bibliothèque cliente à maintenir.
La version courte
- Deux endpoints : une liste d’articles, et un article unique par son id numérique ou par son préfixe slug: et son slug.
- Les filtres sont website, status, language, limit (100 par défaut, 200 maximum) et offset.
- Chaque article renvoie les mêmes 13 clés de premier niveau ; un champ pas encore généré est une chaîne vide plutôt qu’absent.
- L’authentification est une clé au niveau du compte, envoyée comme token Bearer ou comme en-tête x-api-key ; la limite est de 120 requêtes par minute.
- Elle est en lecture seule. Rien dans l’API ne peut modifier un article, une date ou un site.
- GET /api/v2/posts
- Chaque article du compte, du plus récent au plus ancien, avec les métadonnées de pagination. La taille de page est de 100 par défaut et accepte jusqu’à 200 ; offset parcourt le reste.
- GET /api/v2/posts/{id}
- Un article par son id numérique, ou par slug sous la forme `slug:your-post-slug`, pour qu’un CMS puisse retrouver un article par l’URL qu’il connaît déjà.
- ?website=<domain>
- Restreindre à un site — le domaine principal ou le domaine du blog, sans distinction de casse. Le filtre est appliqué avant le comptage, la pagination reste donc correcte.
- ?status=published
- Le statut est comparé exactement : draft, pending_approval, published, unpublished, in_progress, failed_review. Sans filtre, vous les obtenez tous — y compris ce qui attend encore.
- ?language=de
- Une ligne éditoriale. Utile quand le même sujet existe sur plusieurs marchés et qu’un seul a sa place dans ce rapport.
- 120 requêtes / minute
- Par compte, avec un en-tête Retry-After lorsque vous le dépassez. Assez pour une synchronisation nocturne et une recherche interne en direct ; pas un endpoint de scraping.
Deux chemins, deux formes
/api/v2/posts est le chemin actuel, et /api/posts en est un alias. /api/v1/posts sert toujours la forme plate d’origine, figée, pour qu’une intégration existante continue de fonctionner ; les nouveaux clients devraient partir sur v2. Seul l’objet article diffère — authentification, filtres, codes de statut et pagination sont identiques.
La référence complète
Chaque paramètre, chaque champ de la charge utile et chaque code d’erreur — avec des exemples à copier — se trouve dans la référence ci-dessous. Cette page est la visite guidée ; l’autre est le contrat. référence de l’API posts
À quoi ressemble un article sur le fil.
Treize clés de premier niveau, toutes toujours présentes. Trois regroupent les champs qui vont ensemble, et l’article voyage avec ses métadonnées, si bien qu’un consommateur n’a jamais à faire un second appel pour savoir si un article est en ligne.
/api/v2/posts?status=published&limit=1Authorization: Bearer xt4b_••••••••••••{
"data": [
{
"id": "57",
"status": "published",
"slug": "seo-content-cost-per-article",
"title": "Combien coûte le contenu SEO par article ?",
"meta": {
"title": "Combien coûte le contenu SEO par article ?",
"description": "Three pricing models and what each one hides."
},
"searchIntent": "commercial",
"keywords": {
"primary": "coût du contenu seo",
"secondary": ["seo content pricing"]
},
"images": { "cover": "https://cdn.xt4b.com/…/cover.svg" },
"language": "fr",
"website": "xt4b.com",
"publishedAt": "2026-09-11T09:00:04.118Z"
}
],
"pagination": { "limit": 1, "offset": 0, "total": 7 }
}La réponse est une enveloppe avec data et pagination. Un article unique renvoie le même objet dans data, si bien qu’un seul parseur gère les deux appels.
Les champs que le pipeline n’a pas encore produits sont des chaînes vides plutôt qu’absents : un article planifié a un titre, des métadonnées, une intention et des mots-clés, et pas de markdown, pas de couverture ni de date de publication. Un client peut afficher cette ligne sans une seule condition pour les clés manquantes.
La forme est un contrat, pas une commodité. C’est ce que lisent le blog de Xt4b et ses panneaux Search Console, si bien qu’une nouvelle colonne dans la base ne peut pas devenir discrètement un nouveau champ dans votre intégration.
L’article, et la fiche qui l’entoure.
La moitié de la charge utile est ce que voit un lecteur ; la moitié est la provenance dont un éditeur ou un rapport a besoin.
L’article
- title — le titre sous lequel l’article est publié
- meta.title et meta.description — écrits pour la SERP, pas repris du corps
- markdown — l’article comme source, c’est-à-dire ce que vous modifiez
- html — le même article rendu par le publisher, ancres de titres incluses
La fiche
- id et slug — des clés stables sous forme de chaînes, et l’URL où vit l’article
- status — où en est l’article dans le pipeline, pas seulement en ligne ou non
- website et language — quel site, quel marché
- publishedAt — horodatage ISO, vide tant que l’article est encore planifié
- keywords.primary, keywords.secondary et searchIntent — le brief pour lequel il a été écrit
- images.cover — la couverture générée
De zéro à votre première ligne.
Quatre étapes, et la quatrième est une ligne curl à coller dans un terminal ou une tâche cron.
- 01
Créez un compte et connectez un site
L’API est une fenêtre sur vos propres articles, elle a donc besoin d’un site et d’un plan derrière. L’analyse gratuite montre les requêtes qui manquent à un site avant que vous ne connectiez quoi que ce soit.
- 02
Copiez la clé depuis les paramètres
Une clé par compte, affichée sur la page des paramètres. La régénérer révoque immédiatement la précédente, et c’est toute l’histoire de la rotation — il n’y a ni client id, ni secret, ni URL de callback.
- 03
Envoyez-la comme en-tête
`Authorization: Bearer <key>` ou `x-api-key: <key>`. Les deux fonctionnent sur chaque endpoint, si bien qu’un script et un outil dans le navigateur peuvent utiliser le plus simple.
- 04
Demandez ce dont vous avez besoin
Commencez par `?status=published&limit=50`, puis affinez avec `website` et `language` une fois la forme connue. Paginez avec `offset` plutôt que de demander les articles un par un.
Trois appels, à copier-coller.
Le premier renvoie une page d’articles en ligne, le deuxième en retrouve un par le slug de son URL, le troisième demande ce qui attend encore une validation.
Lister ce qui est en ligne, site par site
curl "https://xt4b.com/api/v2/posts?website=xt4b.com\ &status=published&limit=50" \ -H "Authorization: Bearer $XT4B_API_KEY"
Un article, par le slug de son URL
curl "https://xt4b.com/api/v2/posts/\ slug:seo-content-cost-per-article" \ -H "x-api-key: $XT4B_API_KEY"
Ce qui attend une décision
curl "https://xt4b.com/api/v2/posts?status=draft\ &language=de&limit=100&offset=0" \ -H "Authorization: Bearer $XT4B_API_KEY"
L’enveloppe d’erreur
{
"error": {
"code": "rate_limited",
"message": "Too many requests — retry after 12s."
}
}Ce que les gens construisent avec.
Les quatre intégrations qui viennent d’abord, dans l’ordre où elles sont généralement construites.
- 01
Un rapport qui se construit tout seul
Récupérez les articles avec status=published une fois par nuit et écrivez les lignes dans votre tableau de bord. Pas de scraping de votre propre blog, pas de recopie de tableur.
- 02
Votre CMS comme destination
Si le blog vit ailleurs, prenez le markdown (ou le HTML rendu), les métadonnées et les images, et publiez-le vous-même. L’API est en lecture seule, rien ici ne peut donc écraser ce que vos éditeurs ont écrit.
- 03
Une recherche interne qui vous appartient
Filtrez par site et par langue pour construire une recherche ou un bloc d’articles liés sur votre propre archive — y compris les articles encore en brouillon.
- 04
Une file de contrôle qualité
Demandez status=draft ou failed_review et relisez ce que le pipeline a produit avant sa mise en ligne, avec vos propres outils plutôt que les nôtres.
Ce que l’API n’est pas.
À dire clairement, car une API de lecture promet vite trop.
- Pas un endpoint de génération
- Il n’y a pas de POST pour demander un article. Le contenu est planifié et écrit par le pipeline contre un plan, et l’API en rapporte le résultat.
- Pas un endpoint de publication
- Rien de ce que vous envoyez ne peut modifier un article, une date ou un site. Si un client veut publier via son propre CMS, il récupère puis publie là-bas — le mode d’échec d’une mauvaise intégration est un article manquant, jamais un article faux.
- Pas de clés par site
- Une clé par compte, avec ?website= comme filtre. Plus simple à faire tourner, et cela signifie qu’une intégration d’agence se configure une fois plutôt que par client.
- Pas de promesse sur le classement
- Elle rapporte ce qui a été publié, et ce que montre une Search Console connectée. Elle ne peut pas rapporter une position qui n’existe pas encore, et rien de tout cela ne garantit trafic ou chiffre d’affaires — le classement, le trafic et le chiffre d’affaires ne sont garantis ni par celle-ci ni par aucune autre API.
Plus sur le contenu
- Contenu SEO multilingue
Une langue est une ligne éditoriale, pas une traduction de vos pages anglaises.
- Blog hébergé
Un blog sur votre domaine, derrière un enregistrement DNS, maintenu pour vous.
- Pour les marchés multilingues
Quel marché ouvrir ensuite, et ce qu'il coûte.
- llms.txt
Le fichier de synthèse destiné aux modèles de langage, et ce que contient le nôtre.
Les questions que posent les développeurs.
Y compris les deux sur ce qu’elle refuse de faire.
Existe-t-il un endpoint qui écrit ou publie ?
Non. L’API est en lecture seule par conception : elle expose ce que le pipeline a planifié et publié, et rien en elle ne peut modifier un article, une date ou un site. La publication se fait dans le tableau de bord, là où c’est une personne qui décide.
À quoi ressemble l’authentification ?
Une clé par compte, affichée dans vos paramètres, envoyée soit comme `Authorization: Bearer <key>`, soit comme en-tête `x-api-key`. Régénérer la clé révoque immédiatement l’ancienne, et il n’y a pas de danse OAuth, pas de client secret et rien à installer.
Ai-je besoin d’un SDK ?
Non. C’est du JSON via HTTPS avec un jeu de filtres et une enveloppe — un appel fetch dans n’importe quel langage, ou une ligne curl dans un cron. La forme de la réponse est fixe : chaque clé est présente pour chaque article, et les champs pas encore générés reviennent à null plutôt que manquants.
Pourquoi renvoyer à la fois le markdown et le HTML rendu ?
Parce que la plupart des consommateurs ont besoin de l’un des deux. Le markdown est ce que vous modifiez et stockez ; le HTML est l’article tel que le publisher le rend, avec les ancres de titres et des liens fiabilisés, si bien qu’un site peut servir un article sans parser le markdown lui-même. Ni l’un ni l’autre n’est dérivé au moment de la requête — les deux sont lus dans la ligne stockée.
La clé voit-elle tous les sites du compte ?
Oui — les clés sont par compte, et les sites se filtrent avec ?website=. Pour une agence, cela veut dire une seule intégration pour tous les clients, le filtre de site étant la seule chose à changer d’un rapport à l’autre.
Que se passe-t-il quand j’atteins la limite de requêtes ?
Vous recevez un 429 avec un en-tête Retry-After, et le compteur est par compte sur une fenêtre fixe d’une minute. Paginez avec limit et offset plutôt que d’envoyer des requêtes par article : limit accepte jusqu’à 200.
Comment obtenir une clé d’API ?
Elle est générée pour vous : créez un compte, et la clé apparaît sur la page des paramètres, prête à copier. Il n’y a pas de formulaire de demande, pas de client OAuth à enregistrer et pas de clé par site à distribuer.
Puis-je filtrer par plage de dates ?
Non — les filtres sont website, status, language, limit et offset. Les articles arrivent du plus récent au plus ancien, si bien qu’une fenêtre de dates se parcourt par pagination : prenez 200 à la fois et arrêtez-vous quand publishedAt est plus ancien que la fenêtre qui vous intéresse. C’est délibéré : un filtre de dates à moitié pris en charge serait pire qu’une pagination honnête.
L’API renvoie-t-elle des articles pas encore publiés ?
Oui, sauf si vous les filtrez. Une lecture sans filtre renvoie chaque article avec son statut, y compris les brouillons, les articles en attente de validation et ceux qui ont échoué à la relecture — c’est ce qui rend possible une file de contrôle qualité. La plupart des intégrations de reporting commencent par ?status=published.
Existe-t-il un bac à sable ou un mode test ?
Non. Il y a une API et une clé. Comme l’API est en lecture seule, la pointer vers un vrai compte est sans danger — au pire, une erreur renvoie des lignes dont vous n’aviez pas besoin.
À quoi ressemblent les erreurs ?
La même enveloppe que les données : un objet `error` avec un `code` lisible par machine et un message — invalid_api_key (401), invalid_post_id (400), post_not_found (404), rate_limited (429). Rien ne renvoie une chaîne nue, si bien qu’un client peut brancher sur le code plutôt que d’analyser de la prose.
Puis-je obtenir les données sans utiliser le blog hébergé ?
C’est tout l’intérêt de publier l’API. Le blog est la destination par défaut parce qu’il supprime entièrement le travail d’intégration, mais les mêmes articles sont disponibles sous forme de données, si bien qu’un CMS existant, un build de site statique ou un entrepôt de données peut être la destination à la place.
Une clé, tous les sites
Publiez sur votre propre domaine, lisez-le comme des données.
Créez un compte et connectez un site : le pipeline produit les articles, le blog les sert, et l’API vous remet les lignes pour le prouver.
Markdown et HTML rendu120 requêtes par minute3 jours gratuits, sans carte bancaire