Articles

L’API renvoie les articles générés par tous les Oscars du site de la clé. Les articles en cours de génération ne sont pas renvoyés.

Les exemples lisent la clé depuis la variable d’environnement OSCAR_API_KEY : voir Protéger votre clé.

Lister les articles

GET /v1/articles

Paramètres

Paramètre	Type	Par défaut	Description
pageSize	entier de 1 à 50	20	Nombre d’articles par page.
cursor	texte	aucun	Valeur de nextCursor reçue lors de l’appel précédent. Sans curseur, la liste part du premier article.
oscarId	UUID	aucun	Limite la liste aux articles d’un Oscar du site.
status	liste	tous les statuts	Un ou plusieurs statuts séparés par des virgules, par exemple ready,published.

curl

curl "https://beta-api.oscar-seo.ai/v1/articles?status=ready,published&pageSize=50" \
  -H "Authorization: Bearer $OSCAR_API_KEY"

Pour la page suivante, ajoutez &cursor= suivi de la valeur de nextCursor.

PHP

lister-articles.php

<?php
$apiKey = getenv('OSCAR_API_KEY');
$cursor = null; // nextCursor reçu lors de l’appel précédent, s’il y en a un

$params = ['status' => 'ready,published', 'pageSize' => 50];
if ($cursor !== null) {
    $params['cursor'] = $cursor;
}

$curl = curl_init('https://beta-api.oscar-seo.ai/v1/articles?' . http_build_query($params));
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($curl), true);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($status !== 200) {
    exit('Erreur ' . $status . ' : ' . $body['error'] . PHP_EOL);
}

foreach ($body['data'] as $article) {
    echo $article['id'] . ' ' . $article['title'] . PHP_EOL;
}
echo 'Curseur suivant : ' . $body['nextCursor'] . PHP_EOL;

JavaScript (Node.js)

lister-articles.mjs

const apiKey = process.env.OSCAR_API_KEY
const cursor = null // nextCursor reçu lors de l’appel précédent, s’il y en a un

const params = new URLSearchParams({ status: 'ready,published', pageSize: '50' })
if (cursor !== null) {
  params.set('cursor', cursor)
}

const response = await fetch(`https://beta-api.oscar-seo.ai/v1/articles?${params}`, {
  headers: { Authorization: `Bearer ${apiKey}` }
})
const body = await response.json()

if (!response.ok) {
  throw new Error(`Erreur ${response.status} : ${body.error}`)
}

for (const article of body.data) {
  console.log(article.id, article.title)
}
console.log('Curseur suivant :', body.nextCursor)

Réponse

Champ	Type	Description
data	tableau	Les articles de la page, avec tous leurs champs.
nextCursor	texte	Position du dernier article renvoyé. Toujours présent, même quand data est vide.
hasMore	booléen	true s’il reste des articles après cette page.

Ordre et curseur

Les articles sont triés par date de dernière modification, de la plus ancienne à la plus récente. Un article modifié dans Oscar (relecture, changement de statut, retouche du contenu) passe donc en fin de liste : il est renvoyé à nouveau après le curseur. Servez-vous de son id pour mettre à jour l’article déjà importé plutôt que d’en créer un second.

Pour parcourir la liste, renvoyez nextCursor dans le paramètre cursor de l’appel suivant, tant que hasMore vaut true.

Fiez-vous à hasMore, pas au nombre d’articles

Une page peut contenir moins d’articles que pageSize, voire aucun, alors que hasMore vaut true. Continuez tant que hasMore vaut true.

• Conservez nextCursor tel quel : son contenu peut changer sans préavis.
• Gardez les mêmes filtres status et oscarId tant que vous réutilisez un même curseur.

Erreurs possibles

Statut	Code	Cause
400	INVALID_REQUEST	Un paramètre est invalide. Le champ details indique lequel.
404	OSCAR_NOT_FOUND	oscarId ne correspond à aucun Oscar du site de la clé.
503	ARTICLE_CONTENT_UNAVAILABLE	Le contenu des articles est momentanément indisponible. Réessayez plus tard.

Exemple de réponse avec pageSize=51 :

{
  "error": "INVALID_REQUEST",
  "details": {
    "errors": [],
    "properties": {
      "pageSize": { "errors": ["Too big: expected number to be <=50"] }
    }
  }
}

Les erreurs communes à toutes les routes sont décrites dans Limites et erreurs.

Récupérer un article

GET /v1/articles/{articleId}

La réponse est l’article seul, avec tous ses champs.

curl

curl "https://beta-api.oscar-seo.ai/v1/articles/3f6b2c1e-8a4d-4b7e-9c2a-5d1e0f7a9b34" \
  -H "Authorization: Bearer $OSCAR_API_KEY"

PHP

recuperer-article.php

<?php
$apiKey = getenv('OSCAR_API_KEY');
$articleId = '3f6b2c1e-8a4d-4b7e-9c2a-5d1e0f7a9b34';

$curl = curl_init('https://beta-api.oscar-seo.ai/v1/articles/' . $articleId);
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
    CURLOPT_RETURNTRANSFER => true,
]);
$article = json_decode(curl_exec($curl), true);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($status !== 200) {
    exit('Erreur ' . $status . ' : ' . $article['error'] . PHP_EOL);
}

echo $article['title'] . PHP_EOL;

JavaScript (Node.js)

recuperer-article.mjs

const apiKey = process.env.OSCAR_API_KEY
const articleId = '3f6b2c1e-8a4d-4b7e-9c2a-5d1e0f7a9b34'

const response = await fetch(`https://beta-api.oscar-seo.ai/v1/articles/${articleId}`, {
  headers: { Authorization: `Bearer ${apiKey}` }
})
const article = await response.json()

if (!response.ok) {
  throw new Error(`Erreur ${response.status} : ${article.error}`)
}

console.log(article.title)

Erreurs possibles

Statut	Code	Cause
400	INVALID_REQUEST	articleId n’est pas un UUID.
404	ARTICLE_NOT_FOUND	L’article n’existe pas, appartient à un autre site, n’a pas encore été généré ou son Oscar a été supprimé.
503	ARTICLE_CONTENT_UNAVAILABLE	Le contenu de l’article est momentanément indisponible. Réessayez plus tard.

Champs d’un article

Champ	Type	Description
id	UUID	Identifiant de l’article. Il permet de reconnaître un article déjà importé.
oscarId	UUID	Identifiant de l’Oscar qui a généré l’article.
title	texte ou null	Titre de l’article.
slug	texte ou null	Slug proposé pour l’adresse de l’article.
metaDescription	texte ou null	Méta-description destinée aux moteurs de recherche.
wordCount	entier ou null	Nombre de mots.
status	texte	Statut de l’article : voir Statuts.
html	texte	Contenu complet de l’article en HTML, sans balise <script> ni <style>. La mise en forme est à définir dans les styles de votre site.
jsonLd	objet, tableau ou null	Données structurées de l’article au format JSON-LD (schema.org).
featuredImage	objet ou null	Image à la une : { "url": "…" }.
images	tableau	Images présentes dans html, dans l’ordre d’apparition : { "url": "…", "alt": "…" }. url est identique à l’adresse écrite dans html ; alt vaut null si l’image n’a pas de texte alternatif.
createdAt	date	Date de création, au format ISO 8601 en UTC.
updatedAt	date	Date de la dernière modification dans Oscar, au même format.

Hébergez vous-même les images

Les adresses de featuredImage et de images pointent vers nos serveurs et ne sont pas garanties dans le temps. Téléchargez les images et remplacez leurs adresses : voir Synchroniser vos articles.

Statuts

Statut	Signification
to_review	Article généré, pas encore relu.
ready	Article relu et prêt à publier.
published	Article marqué comme publié dans Oscar.

Le statut évolue dans Oscar, avec les actions Marquer comme relu et Marquer comme publié de l’article. Pour un site connecté à un CMS, ready regroupe aussi les articles en attente de publication, enregistrés en brouillon dans le CMS ou dont l’envoi vers le CMS a échoué.

L’API ne modifie jamais le statut d’un article. Après avoir publié un article sur votre site, marquez-le comme publié dans Oscar pour garder un suivi à jour.