Développeurs

Démarrer

Toutes les routes vivent sous /api/v1 et s’authentifient par un en-tête Authorization: Bearer. Les réponses sont du JSON UTF-8, le CORS est ouvert en GET : un appel depuis un navigateur fonctionne.

Spécification complète (OpenAPI 3.1) : /api/v1/openapi.json

Obtenir une clé

Pas d’auto-inscription pour cette première version : écrivez-nous en décrivant l’usage prévu, le volume attendu et l’endroit où l’attribution apparaîtra. Nous créons la clé à la main et vous la transmettons.

La clé est remise UNE seule fois : nous n’en gardons qu’une empreinte SHA-256, nous ne pouvons donc pas vous la relire. Si elle est perdue ou exposée, elle est révoquée et remplacée — une clé révoquée l’est définitivement.

Nous écrire : [email protected]

Points d’entrée

Paramètres

• lang — code ISO 639-1 (fr, en, zh…). Le contenu est servi traduit si la traduction existe, sinon en anglais, sinon en langue d’origine.
• topic — slug de rubrique (cf. /topics).
• limit — 1 à 50 (20 par défaut).
• cursor — le nextCursor de la réponse précédente. Opaque : ne l’interprétez pas, son encodage changera.

Exemples

# les dernières stories
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories?lang=fr&limit=5"

# un article, en anglais
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories/mon-slug?lang=en"

# page suivante (curseur opaque)
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories?limit=5&cursor=$CURSOR"

{
  "stories": [ /* … */ ],
  "nextCursor": "bzE6NQ",
  "lang": "en",
  "attribution": { "name": "Aube", "url": "https://aube.news" }
}

Quotas et erreurs

Chaque clé porte un quota journalier remis à zéro à minuit. Les réponses portent X-RateLimit-Limit et X-RateLimit-Remaining ; au-delà, l’API rend 429 avec Retry-After (en secondes) — et l’appel refusé n’est pas décompté.

• 400 — paramètre invalide (limit hors bornes, curseur illisible…).
• 401 — clé absente, inconnue ou révoquée.
• 404 — story inconnue ou non publiée.
• 429 — quota journalier atteint.
• 500 — erreur de notre côté : réessayez, puis signalez-la-nous.

Attribution

Chaque réponse porte un objet attribution. Toute réutilisation publique doit citer « Aube » et pointer vers la page d’origine (le champ url de la story). Ce n’est pas de la coquetterie : nos articles renvoient eux-mêmes à leurs sources primaires, et cette chaîne de citations est ce qui distingue une information d’une rumeur.

En pratique :

• citez « Aube » à côté du contenu repris, avec un lien cliquable vers story.url ;
• pour les séries de /metrics, citez AUSSI la source primaire fournie (source.name / source.url) ;
• ne republiez pas le corps complet (bodyMd) d’un article : reprenez le TL;DR ou un extrait, et renvoyez vers Aube ;
• conservez l’étiquette « contenu sponsorisé » (isSponsored) quand elle est présente — sans exception.

Widget embarquable

La bonne nouvelle du jour, en 180 pixels de haut, sans cookie ni script tiers. Collez cette iframe où vous voulez :

<iframe src="https://aube.news/widget?lang=fr&theme=light"
        width="100%" height="180" frameborder="0"
        title="Aube — la bonne nouvelle du jour"
        loading="lazy"></iframe>

Paramètres : lang=fr|en|es|pt|de|it et theme=light|dark. Le widget porte déjà son attribution et ouvre l’article sur Aube dans un nouvel onglet.

Aperçu