Sviluppatori

Iniziare

Tutti i percorsi vivono sotto /api/v1 e si autenticano con un’intestazione Authorization: Bearer. Le risposte sono JSON UTF-8, il CORS è aperto in GET: una chiamata da un browser funziona.

Specifica completa (OpenAPI 3.1): /api/v1/openapi.json

Ottenere una chiave

Nessuna registrazione automatica in questa prima versione: scrivici descrivendo l’uso previsto, il volume atteso e il punto in cui apparirà l’attribuzione. Creiamo la chiave a mano e te la inviamo.

La chiave viene consegnata UNA sola volta: ne conserviamo solo un’impronta SHA-256, quindi non possiamo rileggertela. Se viene persa o esposta, viene revocata e sostituita — una chiave revocata lo è definitivamente.

Scrivici: [email protected]

Punti di accesso

Parametri

• lang — codice ISO 639-1 (fr, en, zh…). Il contenuto è servito tradotto se la traduzione esiste, altrimenti in inglese, altrimenti nella lingua originale.
• topic — slug di sezione (vedi /topics).
• limit — da 1 a 50 (20 per impostazione predefinita).
• cursor — il nextCursor della risposta precedente. Opaco: non interpretarlo, la sua codifica cambierà.

Esempi

# le ultime notizie
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories?lang=it&limit=5"

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

# pagina successiva (cursore opaco)
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" }
}

Quote ed errori

Ogni chiave ha una quota giornaliera azzerata a mezzanotte. Le risposte portano X-RateLimit-Limit e X-RateLimit-Remaining; oltre la quota, l’API risponde 429 con Retry-After (in secondi) — e la chiamata rifiutata non viene conteggiata.

• 400 — parametro non valido (limit fuori intervallo, cursore illeggibile…).
• 401 — chiave assente, sconosciuta o revocata.
• 404 — notizia sconosciuta o non pubblicata.
• 429 — quota giornaliera raggiunta.
• 500 — errore dalla nostra parte: riprova, poi segnalacelo.

Attribuzione

Ogni risposta porta un oggetto attribution. Ogni riutilizzo pubblico deve citare «Aube» e puntare alla pagina di origine (il campo url della notizia). Non è un vezzo: i nostri articoli rimandano a loro volta alle loro fonti primarie, e questa catena di citazioni è ciò che distingue un’informazione da una voce.

In pratica:

• cita «Aube» accanto al contenuto ripreso, con un link cliccabile a story.url;
• per le serie di /metrics, cita ANCHE la fonte primaria fornita (source.name / source.url);
• non ripubblicare il corpo completo (bodyMd) di un articolo: riprendi il TL;DR o un estratto, e rimanda a Aube;
• conserva l’etichetta «contenuto sponsorizzato» (isSponsored) quando è presente — senza eccezioni.

Widget incorporabile

La buona notizia del giorno, in 180 pixel di altezza, senza cookie né script di terzi. Incolla questo iframe dove vuoi:

<iframe src="https://aube.news/widget?lang=it&theme=light"
        width="100%" height="180" frameborder="0"
        title="Aube — la buona notizia del giorno"
        loading="lazy"></iframe>

Parametri: lang=fr|en|es|pt|de|it e theme=light|dark. Il widget porta già la sua attribuzione e apre l’articolo su Aube in una nuova scheda.

Anteprima