Developers

Getting started

Every route lives under /api/v1 and authenticates with an Authorization: Bearer header. Responses are UTF-8 JSON, CORS is open for GET: calling from a browser works.

Full specification (OpenAPI 3.1): /api/v1/openapi.json

Getting a key

No self-service in this first version: write to us describing the intended use, the expected volume and where the attribution will appear. We create the key by hand and send it to you.

The key is shown ONCE: we only keep a SHA-256 fingerprint, so we cannot read it back to you. If it is lost or exposed, it gets revoked and replaced — a revoked key is dead for good.

Write to us: [email protected]

Endpoints

Parameters

• lang — ISO 639-1 code (fr, en, zh…). Content is served translated when a translation exists, otherwise in English, otherwise in the original language.
• topic — topic slug (see /topics).
• limit — 1 to 50 (20 by default).
• cursor — the nextCursor from the previous response. Opaque: do not parse it, its encoding will change.

Examples

# the latest stories
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories?lang=en&limit=5"

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

# next page (opaque cursor)
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 and errors

Each key carries a daily quota, reset at midnight. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; beyond that the API returns 429 with Retry-After (in seconds) — and the rejected call is not counted.

• 400 — invalid parameter (limit out of range, unreadable cursor…).
• 401 — key missing, unknown or revoked.
• 404 — unknown or unpublished story.
• 429 — daily quota reached.
• 500 — our fault: retry, then tell us about it.

Attribution

Every response carries an attribution object. Any public reuse must credit “Aube” and link to the original page (the story’s url field). This is not vanity: our own articles link back to their primary sources, and that chain of citations is what separates information from rumour.

In practice:

• credit “Aube” next to the reused content, with a clickable link to story.url;
• for /metrics series, ALSO credit the primary source provided (source.name / source.url);
• do not republish an article’s full body (bodyMd): reuse the TL;DR or an excerpt and link back to Aube;
• keep the “sponsored content” label (isSponsored) wherever it is set — no exceptions.

Embeddable widget

Today’s good news, 180 pixels tall, no cookie and no third-party script. Paste this iframe wherever you like:

<iframe src="https://aube.news/widget?lang=en&theme=light"
        width="100%" height="180" frameborder="0"
        title="Aube — today’s good news"
        loading="lazy"></iframe>

Parameters: lang=fr|en|es|pt|de|it and theme=light|dark. The widget carries its own attribution and opens the article on Aube in a new tab.

Preview