Programadores

Começar

Todas as rotas vivem sob /api/v1 e autenticam-se por um cabeçalho Authorization: Bearer. As respostas são JSON UTF-8, o CORS está aberto em GET: uma chamada a partir de um navegador funciona.

Especificação completa (OpenAPI 3.1): /api/v1/openapi.json

Obter uma chave

Não há inscrição automática nesta primeira versão: escreva-nos descrevendo a utilização prevista, o volume esperado e o local onde aparecerá a atribuição. Criamos a chave à mão e enviamo-la.

A chave é entregue UMA só vez: guardamos apenas uma impressão digital SHA-256, pelo que não a podemos voltar a ler. Se for perdida ou exposta, é revogada e substituída — e uma revogação é definitiva.

Escreva-nos: [email protected]

Pontos de entrada

Parâmetros

• lang — código ISO 639-1 (fr, en, zh…). O conteúdo é servido traduzido se a tradução existir, senão em inglês, senão na língua de origem.
• topic — slug de secção (ver /topics).
• limit — de 1 a 50 (20 por omissão).
• cursor — o nextCursor da resposta anterior. Opaco: não o interprete, a sua codificação mudará.

Exemplos

# as últimas notícias
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories?lang=pt&limit=5"

# um artigo, em inglês
curl -H "Authorization: Bearer $AUBE_KEY" \
  "https://aube.news/api/v1/stories/mon-slug?lang=en"

# página seguinte (cursor 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" }
}

Quotas e erros

Cada chave tem uma quota diária reposta a zero à meia-noite. As respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining; para além disso, a API responde 429 com Retry-After (em segundos) — e a chamada recusada não é descontada.

• 400 — parâmetro inválido (limit fora dos limites, cursor ilegível…).
• 401 — chave ausente, desconhecida ou revogada.
• 404 — notícia desconhecida ou não publicada.
• 429 — quota diária atingida.
• 500 — erro do nosso lado: tente de novo, e depois assinale-nos.

Atribuição

Cada resposta traz um objeto attribution. Qualquer reutilização pública deve citar «Aube» e apontar para a página de origem (o campo url da notícia). Não é presunção: os nossos artigos remetem eles próprios para as suas fontes primárias, e essa cadeia de citações é o que distingue uma informação de um boato.

Na prática:

• cite «Aube» junto do conteúdo reutilizado, com uma ligação clicável para story.url;
• para as séries de /metrics, cite TAMBÉM a fonte primária fornecida (source.name / source.url);
• não republique o corpo completo (bodyMd) de um artigo: reutilize o TL;DR ou um excerto, e remeta para Aube;
• conserve a etiqueta «conteúdo patrocinado» (isSponsored) quando estiver presente — sem exceção.

Widget incorporável

A boa notícia do dia, em 180 píxeis de altura, sem cookies nem scripts de terceiros. Cole este iframe onde quiser:

<iframe src="https://aube.news/widget?lang=pt&theme=light"
        width="100%" height="180" frameborder="0"
        title="Aube — a boa notícia do dia"
        loading="lazy"></iframe>

Parâmetros: lang=fr|en|es|pt|de|it e theme=light|dark. O widget já traz a sua atribuição e abre o artigo em Aube num novo separador.

Pré-visualização