Documentação da API
OSNOdata API
Notícias, média transcrita e eventos, recolhidos e servidos por API, por pedido, em tempo real ou por webhook.
Introdução
A API do OSNOdata serve notícias, média transcrita (televisão, rádio, podcasts) e eventos, recolhidos de centenas de fontes.
Todos os pedidos vão para https://api.osnodata.com, respondem em JSON e levam a chave do cliente no cabeçalho Authorization. Há três formas de receber os dados, que se podem combinar:
- Pedir:
GET /v1/itemspara navegar ou sincronizar, eGET /v1/searchpara pesquisar. - Manter um stream aberto:
GET /v1/streamenvia cada item à medida que chega, por Server-Sent Events. - Receber em casa: um webhook recebe os itens novos num POST assinado para um endereço teu.
Um item é um article (notícia, publicação, email), um media (episódio ou peça de um programa) ou um event (evento com data e local). Cada item tem um id de 12 letras e algarismos e um seq, um número que cresce sempre que um item é guardado ou alterado e que serve para sincronizar sem perder nada.
Nos exemplos, a chave está na variável de ambiente OSNODATA_KEY:
export OSNODATA_KEY="osk_live_..."Autenticação e scopes
Uma chave por cliente, criada no dashboard em API keys. O token completo só é mostrado uma vez, quando a chave é criada.
A chave (osk_live_...) vai em todos os pedidos como Authorization: Bearer <chave>. Uma chave pode expirar e ser revogada a qualquer momento; a partir daí os pedidos com ela respondem 401. As chaves só abrem os endpoints de dados em /v1: não servem para gerir a conta nem para criar outras chaves.
Cada chave tem os scopes que lhe foram dados:
Scopes
items:read- Itens, um item e a pesquisa.
sources:read- As fontes e o estado da recolha.
media:read- Transcrições, peças, ficheiros de média, clips e documentos (páginas, tabelas, partes).
stream:read- O stream de itens em tempo real (SSE).
live:read- Bilhetes para ver o directo dos canais pelo proxy (POST /v1/channels/{id}/ticket).
webhooks:write- Criar e gerir webhooks que recebem os itens novos e, com items:read, subscrições de pesquisas guardadas.
ingest:write- Enviar URLs, ficheiros e textos para virarem itens (POST /v1/ingest).
Um pedido sem o scope necessário responde 403 {"error": "insufficient_scope", "scope": "media:read"}. Para confirmar a configuração de um cliente, pergunta-se à API que chave é esta:
/v1/keyA chave que faz o pedido, os seus scopes e os seus limites. Não precisa de scope.
curl "https://api.osnodata.com/v1/key" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": 7,
"name": "omelhorsite",
"prefix": "osk_live_a1B2c3",
"scopes": [
"items:read",
"stream:read"
],
"status": "active",
"last_used_at": "2026-09-29T10:14:58Z",
"expires_at": null,
"revoked_at": null,
"created_at": "2026-09-01T09:00:00Z",
"limits": {
"requests_per_minute": 120,
"requests_per_day": 50000
},
"owner": {
"id": 1,
"name": "Afonso"
}
}Limites de pedidos
Cada chave tem um limite por minuto e outro por dia (dia UTC). Por omissão, 120 pedidos por minuto e 50 000 por dia; o dono da chave pode baixá-los no dashboard, e só um admin os sobe.
Todos os pedidos com chave contam, incluindo os recusados. Cada resposta diz onde a chave está:
Cabeçalhos
X-RateLimit-Limit- Pedidos por minuto desta chave.
X-RateLimit-Remaining- Pedidos que restam neste minuto.
X-RateLimit-Reset- Quando o minuto recomeça (Unix, segundos).
X-RateLimit-Limit-Day- Pedidos por dia (UTC) desta chave.
X-RateLimit-Remaining-Day- Pedidos que restam hoje.
X-RateLimit-Reset-Day- Quando o dia recomeça (Unix, segundos).
Passado um limite, a API responde 429 com o cabeçalho Retry-After (em segundos) e diz qual das janelas se esgotou:
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790676960
{
"error": "rate_limited",
"window": "minute",
"retry_after": 17
}Retry-After antes de repetir. Para ler muito, prefere o stream ou os webhooks a perguntar em ciclo: um stream aberto conta como um único pedido.Erros
Um erro é sempre um JSON com error, às vezes com mais contexto.
Códigos
400 invalid_param- Um parâmetro com um valor inválido, nomeado em
param:{"error": "invalid_param", "param": "published_after"} 401 invalid_api_key- Chave desconhecida, revogada ou expirada (ou nenhuma).
403 insufficient_scope- A chave não tem o scope, indicado em
scope. 403 api_key_not_allowed- O endpoint não aceita chaves (gestão da conta).
404 not_found- O recurso não existe.
409 media_not_ready- A média do episódio ainda não foi descarregada (clips).
422 invalid- Dados inválidos ao criar ou alterar; os campos com problema vêm em
details. 429 rate_limited- Limite de pedidos; também
too_many_streams,too_many_open_clipsedaily_clip_limit. TrazRetry-After. 503- Pesquisa semântica sem vectores disponíveis de momento.
{
"error": "invalid",
"details": {
"url": [
"Url tem de ser https"
]
}
}Uma resposta 5xx ou uma ligação cortada são temporárias (por exemplo durante uma actualização do servidor): repete com uma espera crescente.
Itens
GET /v1/items lê os itens de duas maneiras, com os mesmos filtros: a navegar (mais recentes primeiro) ou a sincronizar (por seq, mais antigos primeiro). Precisa de items:read.
Navegar com cursor
Sem since_seq, a resposta traz os itens mais recentes e um next_cursor. Para a página seguinte, repete o pedido com cursor=<next_cursor>; quando next_cursor é null, não há mais. O cursor é estável: os itens que chegam entretanto não deslocam as páginas.
/v1/itemsitems:readUma página de itens, mais recentes primeiro.
Parâmetros
sourcestring- Um id de fonte, ou vários separados por vírgulas. Até 1000; mais é um
400comreason: "too_many_values", nunca uma lista cortada. Numa query string cabem cerca de 700: para mais, usaPOST /v1/items/query(ou o POST da pesquisa e do stream). source_metaobject- As fontes cujos metadados têm este valor nesta chave:
source_meta[oms_feed]=Reconquistadá uma pasta inteira do omelhorsite sem listar ids (também as fontes que absorveram uma dessa pasta). Cada valor é exacto; vários comsource_meta[oms_feed][]=A&source_meta[oms_feed][]=B. Até 5 chaves. importedbooleantrue: só os itens que vieram do histórico do omelhorsite (comimported: true);false: só os que o OSNOdata recolheu.kindstringarticle,media,event,document(vírgulas para vários).parentstring- Um id de item (os seus filhos, por exemplo as peças de um episódio), ou
nonepara só os itens de topo. storystring- Um id de história (os itens que contam a mesma notícia), ou vários separados por vírgulas.
qstring- Texto completo em português sobre o título e o conteúdo, com a sintaxe de pesquisa web:
"frase exacta",-palavra,or. Até 500 caracteres. published_after, published_beforestring- ISO 8601 (
2026-09-28T10:00:00Z) ou uma data (2026-09-28é o início desse dia em Lisboa). starts_after, starts_beforestring- O mesmo, sobre o início dos eventos.
blocksstring- Os blocos de um minuto dos canais em directo ficam de fora:
includejunta-os,onlyresponde só esses. country, language, categorystring- O país (
PT), a língua (pt) e a categoria (regional-news) da fonte do item; vírgulas para vários. restrictionstring- Etiquetas de restrição (
personal:private), famílias (personal) ounonepara itens sem etiquetas; vírgulas para vários. Ver Restrições e direitos. limitinteger- De 1 a 200, 50 por omissão.
cursorstring- O
next_cursorda página anterior. since_seqinteger- Sincronizar a partir deste seq (ver abaixo).
curl "https://api.osnodata.com/v1/items?kind=article&q=lisboa&limit=20" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"items": [
{
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"url": "https://24noticias.sapo.pt/...",
"published_at": "2026-09-28T21:36:18.000Z"
}
],
"next_cursor": "1833"
}Sincronizar com since_seq
Para manter uma cópia local, pede-se tudo o que foi guardado, alterado ou apagado depois de um seq, do mais antigo para o mais recente:
- Começa com
since_seq=0(ou com o último seq que guardaste). - A resposta traz
next_since_seqehas_more. Repete comsince_seq=<next_since_seq>enquantohas_morefortrue. - Guarda o último
next_since_seqe continua a partir dele da próxima vez. Um item alterado volta a aparecer com um seq novo: deduplica peloid.
curl "https://api.osnodata.com/v1/items?since_seq=1800&limit=200" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"items": [
{
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"url": "https://24noticias.sapo.pt/...",
"published_at": "2026-09-28T21:36:18.000Z"
}
],
"deleted": [
{
"id": "M4Viu41U6RY7",
"seq": 1833,
"source_id": "Q3W5k3hgVJCc",
"parent_id": null,
"kind": "article",
"reason": "upstream_deleted",
"deleted_at": "2026-09-29T10:12:40Z"
}
],
"next_since_seq": 1834,
"has_more": false
}Itens apagados
Ao sincronizar, a resposta traz também deleted: os itens apagados nesse intervalo, cada um com o seu próprio seq na mesma sequência dos itens. Aplica items e deleted juntos por ordem de seq e apaga da tua cópia cada id de deleted. O stream manda-os como eventos item.deleted e os webhooks que o pedirem recebem-nos em deleted.
reasondiz porquê:source_deleted(a fonte foi apagada),upstream_deleted(a origem apagou-o),replaced(uma peça que a nova segmentação de um episódio já não tem),retention(passou o tempo de guarda) oudeleted(à mão). Os filhos de um item apagado, como as peças de um episódio, vêm também, cada um com o seu.- Nos apagados só contam os filtros
source,source_meta,kind,parent,blocks,country,language,categoryerestriction. Podes receber o apagamento de um item que nunca tiveste: ignora-o. - O apagamento de um item que a tua chave não pode ver (uma restrição que o esconde) fica de fora, tal como o item ficava.
- As fases dos ficheiros (o vídeo e o áudio comprimidos com o tempo, ou apagados quando a política da fonte o diz) não apagam o item: a transcrição e as peças ficam, e só
/mediamuda.
since_seq=0 e descarta o que não voltar.Filtros
Os filtros são os mesmos em /v1/items, /v1/search, /v1/stream e nos webhooks. Um valor inválido responde 400 invalid_param.
Parâmetros
sourcestring- Um id de fonte, ou vários separados por vírgulas. Até 1000; mais é um
400comreason: "too_many_values", nunca uma lista cortada. Numa query string cabem cerca de 700: para mais, usaPOST /v1/items/query(ou o POST da pesquisa e do stream). source_metaobject- As fontes cujos metadados têm este valor nesta chave:
source_meta[oms_feed]=Reconquistadá uma pasta inteira do omelhorsite sem listar ids (também as fontes que absorveram uma dessa pasta). Cada valor é exacto; vários comsource_meta[oms_feed][]=A&source_meta[oms_feed][]=B. Até 5 chaves. importedbooleantrue: só os itens que vieram do histórico do omelhorsite (comimported: true);false: só os que o OSNOdata recolheu.kindstringarticle,media,event,document(vírgulas para vários).parentstring- Um id de item (os seus filhos, por exemplo as peças de um episódio), ou
nonepara só os itens de topo. storystring- Um id de história (os itens que contam a mesma notícia), ou vários separados por vírgulas.
qstring- Texto completo em português sobre o título e o conteúdo, com a sintaxe de pesquisa web:
"frase exacta",-palavra,or. Até 500 caracteres. published_after, published_beforestring- ISO 8601 (
2026-09-28T10:00:00Z) ou uma data (2026-09-28é o início desse dia em Lisboa). starts_after, starts_beforestring- O mesmo, sobre o início dos eventos.
blocksstring- Os blocos de um minuto dos canais em directo ficam de fora:
includejunta-os,onlyresponde só esses. country, language, categorystring- O país (
PT), a língua (pt) e a categoria (regional-news) da fonte do item; vírgulas para vários. restrictionstring- Etiquetas de restrição (
personal:private), famílias (personal) ounonepara itens sem etiquetas; vírgulas para vários. Ver Restrições e direitos.
Os eventos trazem starts_at, ends_at e location; um evento conhecido só pela data ocupa o dia inteiro em Lisboa e diz "all_day": true em metadata. Num episódio de média, media diz onde está o processamento (status, downloaded, transcribed, segmented, duration_s, summary...) e o content é a transcrição em linhas [m:ss] texto; numa peça, media diz onde fica no episódio (start_s, end_s).
Um post do Bluesky (fonte bluesky) é um artigo com o texto do post, o autor como Nome (@handle) e o link bsky.app em url; metadata traz links, images (url, alt) e bluesky (did, handle, uri, reply_to, quote...), com o item_id do post citado ou respondido quando também está cá. Quando o autor apaga o post, ou a conta, o item desaparece da API; quem o guardou deve apagá-lo também.
Um post do X, do Instagram ou do Facebook (fontes x, instagram e facebook, lidas da página pública, sem conta) é um artigo com o texto, o autor e o link do post em url; metadata traz links e x, instagram ou facebook (o id, a conta, as contagens). Cada imagem é um item filho lido pelo OCR e cada vídeo um item filho transcrito. Quando o post deixa de aparecer na página entre outros que lá continuam, o item é apagado da API.
Um item
/v1/items/{id}items:readUm item, com a mesma forma da lista.
curl "https://api.osnodata.com/v1/items/Q3W5k3hgVJCc" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"parent_id": null,
"story_id": "b7Tq2LmX9aKe",
"external_id": "https://24noticias.sapo.pt/?p=674780",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"content": "A Câmara Municipal de Lisboa aprovou esta segunda-feira...",
"url": "https://24noticias.sapo.pt/...",
"author": "David Pacheco",
"language": "pt",
"published_at": "2026-09-28T21:36:18.000Z",
"fetched_at": "2026-09-28T21:40:02.114Z",
"starts_at": null,
"ends_at": null,
"location": null,
"metadata": {},
"media": null,
"restrictions": [],
"redacted_fields": [],
"document": null,
"ingest": null,
"created_at": "2026-09-28T21:40:02.114Z",
"updated_at": "2026-09-28T21:40:02.114Z"
}Um item que veio do histórico do omelhorsite traz imported: true e imported_at; os que o OSNOdata recolheu trazem imported: false.
Listas longas
/v1/items/queryitems:readO mesmo que GET /v1/items, com os parâmetros num corpo JSON; as listas podem ir como arrays.
curl -X POST "https://api.osnodata.com/v1/items/query" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"source":["Q3W5k3hgVJCc","M4Viu41U6RY7"],"since_seq":0}'{
"items": [
{
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"parent_id": null,
"story_id": "b7Tq2LmX9aKe",
"external_id": "https://24noticias.sapo.pt/?p=674780",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"content": "A Câmara Municipal de Lisboa aprovou esta segunda-feira...",
"url": "https://24noticias.sapo.pt/...",
"author": "David Pacheco",
"language": "pt",
"published_at": "2026-09-28T21:36:18.000Z",
"fetched_at": "2026-09-28T21:40:02.114Z",
"starts_at": null,
"ends_at": null,
"location": null,
"metadata": {},
"media": null,
"restrictions": [],
"redacted_fields": [],
"document": null,
"ingest": null,
"created_at": "2026-09-28T21:40:02.114Z",
"updated_at": "2026-09-28T21:40:02.114Z"
}
],
"deleted": [],
"next_since_seq": 1834,
"has_more": false
}Pesquisa
Por palavras, por significado ou pelas duas, com o excerto que bateu e as palavras encontradas.
keyword: texto completo em português, com a sintaxe de pesquisa web. Oscoreé ots_rank_cd.semantic: vectores bge-m3 (1024 dimensões), pela semelhança de cosseno com a pergunta. Encontra textos sobre o mesmo assunto sem as mesmas palavras. Oscoreé a semelhança.hybrid(por omissão): as duas listas fundidas por Reciprocal Rank Fusion. Oscoreé o RRF, e cada resultado diz a posição que teve em cada lista (keyword.rank,semantic.rank).
Cada resultado traz um excerpt e, em highlights, as posições das palavras encontradas nesse excerto: pares [início, fim] em caracteres, com o fim exclusivo (excerpt.slice(início, fim)).
/v1/searchitems:readOs resultados, melhores primeiro.
Parâmetros
qstring- Obrigatório. A pergunta, até 500 caracteres.
modestringhybrid(por omissão),semanticoukeyword.limitinteger- De 1 a 50, 20 por omissão.
offsetinteger- De 0 a 150, para as páginas seguintes.
source, kind, parent, ...- Os filtros de /v1/items.
curl "https://api.osnodata.com/v1/search?q=greve%20dos%20professores&mode=hybrid&limit=10" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"query": "greve dos professores",
"mode": "hybrid",
"degraded": null,
"results": [
{
"score": 0.0325,
"keyword": {
"rank": 1,
"score": 0.41
},
"semantic": {
"rank": 2,
"similarity": 0.71
},
"excerpt": "...os sindicatos convocaram uma greve dos professores para...",
"highlights": [
[
32,
37
],
[
42,
53
]
],
"item": {
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"url": "https://24noticias.sapo.pt/...",
"published_at": "2026-09-28T21:36:18.000Z"
}
}
]
}"degraded": "semantic_unavailable"; o modo semântico responde 503. O texto ordena as 2000 correspondências mais recentes e, se exceder 3 s, o modo keywordresponde 503 search_timeout e o híbrido responde só pelos vectores com "degraded": "keyword_timeout". Se a procura nos vectores exceder 3 s, o híbrido e o semântico respondem pelo texto com "degraded": "semantic_timeout". Cada chave tem no máximo 2 pesquisas em curso; a mais responde 429 search_busy com Retry-After.Histórias
A mesma notícia contada por várias fontes: artigos e peças de televisão agrupados pela semelhança do que dizem.
Cada artigo ou peça junta-se à história do item mais parecido (cosseno dos embeddings de pelo menos 0,80) entre os que aconteceram até 72 h antes ou depois; senão abre uma história nova. O título é o do artigo mais ao centro da história, e passa a ser escrito por um modelo quando três ou mais fontes a contam. Cada item traz o seu story_id, que chega pouco depois do item (a seguir ao embedding) e não muda o seu seq.
Só entram em histórias os itens que uma chave sem entitlements pode ver: um item escondido por uma restrição (sua ou da fonte) fica de fora, e sai da história se uma política passar a escondê-lo. Os itens de uma história vêm como em /v1/items, com os mesmos cortes.
/v1/storiesitems:readAs histórias, as mais recentes ou as que estão a crescer.
Parâmetros
orderstringrecent(por omissão), as vistas mais recentemente primeiro;growing, as contadas por mais fontes nas últimashourshoras primeiro, comrecent_sources.hoursinteger- Com growing, a janela: 1 a 72, 6 por omissão.
min_sourcesinteger- Só as contadas por pelo menos tantas fontes.
seen_after, seen_beforestring- Vistas pela última vez depois de, ou pela primeira vez antes de. ISO 8601 ou uma data.
limit, offsetinteger- Até 100 por página; continua-se com next_offset.
curl "https://api.osnodata.com/v1/stories?order=growing&hours=6&min_sources=2" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"stories": [
{
"id": "b7Tq2LmX9aKe",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"first_seen_at": "2026-09-28T21:36:18.000Z",
"last_seen_at": "2026-09-29T08:12:00.000Z",
"items_count": 7,
"sources_count": 5,
"source_ids": [
"M4Viu41U6RY7",
"E4ZJkyFNZztF",
"P4BosYKLvGQw"
],
"opener_source_id": "M4Viu41U6RY7",
"created_at": "2026-09-28T21:40:05.000Z",
"updated_at": "2026-09-29T08:15:31.000Z",
"recent_sources": 4
}
],
"next_offset": 50
}/v1/stories/{id}items:readUma história com os seus itens, pela ordem em que aconteceram.
curl "https://api.osnodata.com/v1/stories/b7Tq2LmX9aKe" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "b7Tq2LmX9aKe",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"first_seen_at": "2026-09-28T21:36:18.000Z",
"last_seen_at": "2026-09-29T08:12:00.000Z",
"items_count": 7,
"sources_count": 5,
"source_ids": [
"M4Viu41U6RY7",
"E4ZJkyFNZztF",
"P4BosYKLvGQw"
],
"opener_source_id": "M4Viu41U6RY7",
"created_at": "2026-09-28T21:40:05.000Z",
"updated_at": "2026-09-29T08:15:31.000Z",
"items": [
{
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"parent_id": null,
"story_id": "b7Tq2LmX9aKe",
"external_id": "https://24noticias.sapo.pt/?p=674780",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"content": "A Câmara Municipal de Lisboa aprovou esta segunda-feira...",
"url": "https://24noticias.sapo.pt/...",
"author": "David Pacheco",
"language": "pt",
"published_at": "2026-09-28T21:36:18.000Z",
"fetched_at": "2026-09-28T21:40:02.114Z",
"starts_at": null,
"ends_at": null,
"location": null,
"metadata": {},
"media": null,
"restrictions": [],
"redacted_fields": [],
"document": null,
"ingest": null,
"created_at": "2026-09-28T21:40:02.114Z",
"updated_at": "2026-09-28T21:40:02.114Z"
},
"..."
]
}Gastos públicos
Contratos, apoios e pagamentos públicos de Portugal: Estado, municípios, freguesias, empresas públicas e fundos europeus.
Um registo por contrato, apoio ou pagamento, lido dos conjuntos de dados abertos: todos os contratos do BASE desde 2008, as subvenções da IGF, o PRR (cada beneficiário de cada projecto), o Portugal 2020 e o Portugal 2030. Cada conjunto é lido de novo sozinho; /v1/spending/datasets diz quantos registos tem cada um e a última leitura.
q é uma pesquisa web em português, sem acentos e pela raiz das palavras, sobre a descrição, quem pagou, quem recebeu, o programa e o local: plantação de árvores, arborização OR reflorestação, -eucalipto. Um particular nunca é encontrado pelo nome e aparece como «Particular», sem NIF, a quem não tenha o direito de personal:private. O mesmo dinheiro pode estar em mais do que um conjunto (um apoio europeu e o contrato que ele paga).
/v1/spendingitems:readOs registos que batem nos filtros.
Parâmetros
qstring- A pesquisa.
levelstring- Quem pagou: freguesia, municipio, empresa_publica, regiao, estado, ue. Vários separados por vírgulas.
dataset, kindstring- base, subvencoes, prr, pt2020, pt2030; contract, grant.
payer, payeestring- Parte do nome de quem pagou ou recebeu.
nifstring- NIF de quem pagou ou recebeu.
municipality, parish, programme, cpvstring- O local, o programa, o prefixo do CPV.
from, tostring- Datas (AAAA-MM-DD).
min, maxnumber- Valor em euros.
sortstring- relevance (com q), amount ou date.
limit, offsetinteger- Até 200 por página.
curl "https://api.osnodata.com/v1/spending?q=plantação%20de%20árvores&level=freguesia&sort=amount" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"results": [
{
"id": 1048576,
"dataset": "base",
"external_id": "10811736",
"kind": "contract",
"payer": {
"name": "União das Freguesias de Lumiar",
"nif": "510836123",
"level": "freguesia"
},
"payee": {
"name": "Jardins Verdes, Lda",
"nif": "509000001",
"person": false
},
"amount_eur": 12500,
"amount_kind": "executado",
"date": "2024-03-01",
"description": "Fornecimento e plantação de árvores no parque",
"cpv": "77211400-6",
"programme": null,
"procedure": "Ajuste Direto Regime Geral",
"place": {
"region": "Lisboa",
"municipality": "Lisboa"
},
"url": "https://www.base.gov.pt/Base4/pt/detalhe/?type=contratos&id=10811736",
"metadata": {
"contracted_eur": 12500,
"effective_eur": 12500
}
}
]
}/v1/spending/summaryitems:readQuanto somam: o total, por ano, por nível de quem pagou, por conjunto, e quem pagou e recebeu mais.
curl "https://api.osnodata.com/v1/spending/summary?q=reflorestação&from=2020-01-01" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"count": 1843,
"total_eur": 48210334.5,
"first_date": "2020-01-07",
"last_date": "2026-10-30",
"by_year": [
{
"key": 2024,
"total_eur": 9100220.1,
"count": 301
},
"..."
],
"by_level": [
{
"key": "municipio",
"total_eur": 21004550.2,
"count": 744
},
"..."
],
"by_dataset": [
{
"key": "prr",
"total_eur": 30120900,
"count": 812
},
"..."
],
"top_payers": [
{
"name": "FUNDO AMBIENTAL",
"nif": "600084779",
"total_eur": 18000000,
"count": 410
},
"..."
],
"top_payees": [
"..."
],
"people": {
"count": 12,
"total_eur": 84200
}
}/v1/spending/{id}items:readUm registo.
curl "https://api.osnodata.com/v1/spending/1048576" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": 1048576,
"dataset": "base",
"external_id": "10811736",
"kind": "contract",
"payer": {
"name": "União das Freguesias de Lumiar",
"nif": "510836123",
"level": "freguesia"
},
"payee": {
"name": "Jardins Verdes, Lda",
"nif": "509000001",
"person": false
},
"amount_eur": 12500,
"amount_kind": "executado",
"date": "2024-03-01",
"description": "Fornecimento e plantação de árvores no parque",
"cpv": "77211400-6",
"programme": null,
"procedure": "Ajuste Direto Regime Geral",
"place": {
"region": "Lisboa",
"municipality": "Lisboa"
},
"url": "https://www.base.gov.pt/Base4/pt/detalhe/?type=contratos&id=10811736",
"metadata": {
"contracted_eur": 12500,
"effective_eur": 12500
}
}Fontes
De onde vêm os itens e como está a recolha de cada fonte. A configuração das fontes não é mostrada aos clientes.
health é unknown (nunca correu), ok, error (a última recolha falhou) ou failing (três ou mais falhas seguidas). mechanism é poll (pedida com intervalo), stream (ligação contínua: canais de TV, Bluesky) ou push (enviada para cá, como os emails).
/v1/sourcessources:readTodas as fontes.
Parâmetros
kindstring- O tipo de fonte (
rss,youtube,live_tv...). enabledboolean- Só as ligadas, ou só as desligadas.
country, language, categorystring- O país (
PT,ES), a língua (pt,en) e a categoria (regional-news,podcast-news...) da fonte; vírgulas para vários. statsbooleantruejunta a cada fontestats: itens por dia, atraso entre a publicação e a recolha, quem dá primeiro e quem repete, taxa de falhas e a última recolha com itens novos, nos últimos 7 dias.
curl "https://api.osnodata.com/v1/sources?enabled=true&country=PT" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"sources": [
{
"id": "M4Viu41U6RY7",
"kind": "rss",
"mechanism": "poll",
"item_kind": "article",
"name": "SAPO 24",
"country": "PT",
"language": "pt",
"category": "national-news",
"restrictions": [
"copyright:full_text"
],
"enabled": true,
"health": "ok",
"poll_interval_minutes": 10,
"last_run_at": "2026-09-29T10:10:00Z",
"last_success_at": "2026-09-29T10:10:00Z",
"created_at": "2026-09-01T09:00:00Z"
}
]
}/v1/sources/{id}sources:readUma fonte, com a mesma forma.
curl "https://api.osnodata.com/v1/sources/M4Viu41U6RY7" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "M4Viu41U6RY7",
"kind": "rss",
"name": "SAPO 24",
"enabled": true,
"health": "ok",
"...": "..."
}Média
Os episódios de televisão, rádio e podcasts são descarregados, transcritos e partidos em peças (uma por notícia), que são itens filhos do episódio.
Um episódio passa por pending, downloading, downloaded, transcribing, transcribed, segmenting e done (ou failed); um programa em directo passa antes por recording e recorded. As peças encontram-se com GET /v1/items?parent=<id do episódio>.
O estado vem dos passos do núcleo de ingestão, que o item traz em ingest como qualquer outro: resolve, extract, comments (num vídeo do YouTube), transcribe, pieces, summary e embed. Um episódio pode entrar por POST /v1/ingest com o URL de um vídeo do YouTube, da página de um episódio de podcast, do RTP Play, do TVI Player, da CMTV e da NOW, ou do próprio áudio ou vídeo.
/v1/items/{item_id}/mediamedia:readA transcrição com tempos, as peças e URLs assinados do áudio, do vídeo e das imagens. Para uma peça, responde o do seu episódio, com a peça em piece.
curl "https://api.osnodata.com/v1/items/VqXKLaXkkn8I/media" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"item_id": "VqXKLaXkkn8I",
"status": "done",
"downloaded": true,
"transcribed": true,
"segmented": true,
"duration_s": 3524.3,
"summary": "O Jornal da Noite abriu com...",
"transcript": [
{
"start": 0,
"end": 4.5,
"text": "Boa noite."
}
],
"pieces": [
{
"id": "Hs8dK2pQm1Zx",
"title": "Greve dos professores",
"summary": "...",
"start_s": 75,
"end_s": 120,
"url": "https://..."
}
],
"audio": {
"url": "https://minio.omelhorsite.pt/osnodata-archive/...",
"content_type": "audio/ogg",
"bytes": 21104512,
"tier": "hot",
"profile": "original",
"next_tier": "warm",
"next_tier_at": "2026-10-02T21:00:00Z",
"next_profile": "opus-16k-mono"
},
"video": {
"url": "https://...",
"content_type": "video/mp4",
"bytes": 412000000,
"width": 854,
"height": 480,
"tier": "hot",
"profile": "original",
"next_tier": "warm",
"next_tier_at": "2026-10-02T21:00:00Z",
"next_profile": "hevc-360p"
},
"frames": [
{
"t": 0,
"url": "https://...",
"content_type": "image/jpeg",
"tier": "hot",
"profile": "original"
}
],
"urls_expire_at": "2026-09-29T10:30:00Z"
}urls_expire_at): pede outra vez para URLs novos. O texto (a transcrição e as peças) fica sempre inteiro. Num vídeo do YouTube com legendas carregadas pelo canal, o texto são essas legendas, com os tempos delas; o metadata.text_source do item diz de onde veio (captions_manual ou transcription). Os ficheiros passam por fases, em tier: hot como chegaram, warm com compressão forte (ao fim de 3 dias, por omissão) e cold com compressão no limite (ao fim de 3 meses); profile diz a compressão aplicada (por exemplo opus-16k-mono, hevc-360p, avif-800-q50), pending_profile a que a fase pede e ainda não foi feita, e next_tier_at quando muda de fase. Na fase fria o vídeo só fica nas fontes marcadas como informação; nas outras ficam as capturas. Um ficheiro que a política da fonte manda apagar responde expired: true, sem URL (frames_expired nas capturas).Clips
Um excerto de um episódio, cortado a pedido, em mp4 (ou áudio mp4 num programa só com áudio).
O corte corre em segundo plano, por isso o fluxo é assíncrono:
POST /v1/items/{item_id}/clipcomstarteendem segundos do episódio responde202com o clip empending. Um pedido igual a um clip ainda guardado responde200com esse clip.- Numa peça, sem
startnemend, o clip é a peça inteira: de 3 segundos antes do início até ao fim dela, cortada do episódio (ou dos blocos do canal). Comterms(as palavras de uma menção) econtext(o resumo dela), numa peça, num episódio ou num bloco de um canal em directo, um modelo lê a transcrição à volta das linhas que as dizem e escolhe onde começa a conversa sobre o assunto e onde ele muda: uma menção de passagem com o contexto para se perceber, uma peça sobre o assunto inteira, até 600 segundos. Se falhar, fica o troço por regra: uma peça sobre os termos inteira e pelas seguintes que ainda os digam, ou só as frases que os dizem. Odecisiondo clip diz como ficou; os mesmos termos dão o mesmo clip. - Pergunta-se por ele em
GET /v1/clips/{id}(a cada poucos segundos) até ostatusserdone, com ourlassinado, oufailed, com oerror. - O
urldura 15 minutos; pede o clip outra vez para um novo. Os clips ficam guardados 7 dias.
429 too_many_open_clips, daily_clip_limit). Se a média ainda não foi descarregada, a resposta é 409 media_not_ready. Os clips cortam-se do vídeo ou do áudio guardados, na fase em que estiverem: se a política da fonte os apagou, a resposta é 410 media_expired, com reason: "video_cold" e uma message quando o vídeo passou à fase fria de uma fonte que não é de informação./v1/items/{item_id}/clipmedia:readPede um clip entre dois instantes do episódio, ou uma peça inteira.
Corpo (JSON)
startnumber- Segundos do episódio, a partir de 0. Opcional numa peça.
endnumber- Segundos do episódio, depois de start. Opcional numa peça.
termsstring[]- As palavras de uma menção: sem start nem end, um modelo escolhe o troço que as diz.
contextstring- O resumo da menção, para o modelo.
curl -X POST "https://api.osnodata.com/v1/items/VqXKLaXkkn8I/clip" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"start":75,"end":120}'{
"id": "c7Lq2VnX9aBd",
"item_id": "VqXKLaXkkn8I",
"piece_id": null,
"start": 75,
"end": 120,
"status": "pending",
"error": null,
"url": null,
"url_expires_at": null,
"content_type": null,
"bytes": null,
"width": null,
"height": null,
"origin": null,
"decision": null,
"created_at": "2026-09-29T10:15:00Z",
"finished_at": null,
"expires_at": null
}/v1/clips/{id}media:readUm clip; quando está pronto, com o URL assinado.
curl "https://api.osnodata.com/v1/clips/c7Lq2VnX9aBd" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "c7Lq2VnX9aBd",
"item_id": "VqXKLaXkkn8I",
"piece_id": null,
"start": 75,
"end": 120,
"status": "done",
"error": null,
"url": "https://minio.omelhorsite.pt/osnodata-archive/clips/...",
"url_expires_at": "2026-09-29T10:31:00Z",
"content_type": "video/mp4",
"bytes": 5210442,
"width": 854,
"height": 480,
"origin": "video",
"decision": null,
"created_at": "2026-09-29T10:15:00Z",
"finished_at": "2026-09-29T10:15:21Z",
"expires_at": "2026-10-06T10:15:00Z"
}/v1/clipsmedia:readOs clips pedidos com esta chave, mais recentes primeiro.
Parâmetros
limitinteger- De 1 a 200, 50 por omissão.
curl "https://api.osnodata.com/v1/clips?limit=20" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"clips": [
{
"id": "c7Lq2VnX9aBd",
"item_id": "VqXKLaXkkn8I",
"piece_id": null,
"start": 75,
"end": 120,
"status": "processing",
"error": null,
"url": null,
"url_expires_at": null,
"content_type": null,
"bytes": null,
"width": null,
"height": null,
"origin": null,
"decision": null,
"created_at": "2026-09-29T10:15:00Z",
"finished_at": null,
"expires_at": null
}
]
}Documentos
PDF, Word, PowerPoint, Excel, CSV e imagens: o texto de cada página (com OCR nas digitalizadas), as tabelas e as partes.
Um documento é um item kind: document: uma edição de jornal em PDF, a capa do dia de um jornal, o anexo de um email, um PDF ligado numa notícia ou um ficheiro enviado com POST /v1/ingest. O seu content é o texto todo. As partes (os artigos de uma edição, as secções de um relatório) são itens filhos, também document, com o texto de cada uma; em document dizem onde ficam: a página e a caixa (box, [x0, y0, x1, y1] em fracções da página, a partir do canto superior esquerdo). Encontram-se com GET /v1/items?parent=<id do documento>, e a pesquisa encontra as partes.
/v1/items/{item_id}/documentmedia:readAs páginas com o texto e a imagem, as tabelas em linhas e as partes. Para uma parte, responde o do seu documento, com a parte em part. Com blocks=1, cada página traz os blocos de texto com as caixas.
Parâmetros
blocksboolean- Os blocos de cada página, com a caixa e o tamanho da letra.
curl "https://api.osnodata.com/v1/items/Tq3LmN8vKc2P/document" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"item_id": "Tq3LmN8vKc2P",
"status": "done",
"format": "pdf",
"page_count": 20,
"bytes": 4487567,
"meta": {
"title": null,
"author": null,
"producer": "Adobe PDF Library"
},
"file": {
"url": "https://minio.omelhorsite.pt/osnodata-archive/...",
"filename": "CampeaodasProvincias1323.pdf",
"content_type": "application/pdf",
"bytes": 4487567,
"tier": "hot",
"profile": "original",
"next_tier": "warm",
"next_tier_at": "2026-10-02T07:00:00Z",
"next_profile": "pdf-150dpi"
},
"pages": [
{
"n": 1,
"width": 793.7,
"height": 1162.2,
"source": "text",
"text": "Ponte reabre ao trânsito...",
"image": {
"url": "https://...",
"tier": "hot",
"profile": "original"
}
}
],
"tables": [
{
"id": "t1",
"page": 7,
"rows": [
[
"Freguesia",
"Votos"
],
[
"Sé Nova",
"1204"
]
]
}
],
"parts": [
{
"id": "Pz8Wq1Lm4Nx2",
"title": "Ponte reabre ao trânsito",
"kind": "article",
"type": "noticia",
"section": "Região",
"index": 1,
"page": 1,
"box": [
0.05,
0.12,
0.62,
0.58
]
}
],
"ingest": {
"status": "done",
"type": "pdf",
"extractor": "document",
"next": null,
"error": null,
"retry_at": null,
"steps": [
{
"name": "resolve",
"status": "done",
"attempts": 1,
"ms": 2140
},
{
"name": "extract",
"status": "done",
"attempts": 1,
"ms": 4310
},
{
"name": "ocr",
"status": "skipped",
"attempts": 1,
"ms": 12
},
{
"name": "segment",
"status": "done",
"attempts": 1,
"ms": 61200
},
{
"name": "embed",
"status": "done",
"attempts": 1,
"ms": 30
}
]
},
"urls_expire_at": "2026-09-29T10:30:00Z"
}tier: hot, warm, cold); se a política da fonte os apagar, file diz expired: true e as páginas deixam de ter image.Envio
Qualquer URL, ficheiro ou texto vira um item: o mesmo núcleo que lê as fontes resolve-o, extrai o texto e as tabelas, faz o OCR, parte-o e calcula os embeddings.
O item nasce logo e o trabalho corre em segundo plano, passo a passo; ingest diz onde está (pending, running, waiting, done ou failed, e cada passo). Pergunta-se por ele em GET /v1/items/{id} até estar done. O mesmo URL (sem parâmetros de tracking) ou os mesmos bytes são o mesmo item: a resposta é esse, com 200.
/v1/ingestingest:writeUm url, um file (multipart, até 150 MB) ou um text.
Corpo (JSON)
urlstring- Uma notícia, um PDF, uma página que mostra um PDF.
filefile- PDF, Word, PowerPoint, Excel, CSV ou imagem, em multipart.
textstring- Um texto, tal como está.
title, language, published_atstring- O que se sabe do item à partida.
segmentstring- Como partir um documento:
articles(uma edição de jornal),sectionsounone. contextstring[]- URLs que só completam o item (a página de um programa, a notícia que liga o PDF).
attachmentsstring[]- URLs que viram itens filhos.
forceboolean- Recomeça um item que já existia.
dry_runboolean- Um ensaio: não grava nada e responde o que aconteceria (abaixo).
heavy, heavy_minutesboolean, integer- No ensaio, também uma amostra dos passos pesados: os primeiros
heavy_minutes(2 por omissão, até 10) transcritos, o OCR de uma página, os artigos de uma página ou a página no browser. preview_tokenstring- Faz o item a partir de um ensaio, sem descarregar outra vez; o que se mandar com ele (title, language...) muda o que o ensaio viu.
curl -X POST "https://api.osnodata.com/v1/ingest" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.campeaoprovincias.pt/pdf/CampeaodasProvincias1323.pdf","segment":"articles"}'{
"id": "Tq3LmN8vKc2P",
"seq": 1834,
"kind": "document",
"source_id": "M4Viu41U6RY7",
"parent_id": null,
"story_id": "b7Tq2LmX9aKe",
"external_id": "https://24noticias.sapo.pt/?p=674780",
"title": "CampeaodasProvincias1323.pdf",
"content": null,
"url": "https://24noticias.sapo.pt/...",
"author": "David Pacheco",
"language": "pt",
"published_at": "2026-09-28T21:36:18.000Z",
"fetched_at": "2026-09-28T21:40:02.114Z",
"starts_at": null,
"ends_at": null,
"location": null,
"metadata": {},
"media": null,
"restrictions": [],
"redacted_fields": [],
"document": null,
"ingest": {
"status": "pending",
"type": null,
"extractor": null,
"next": "resolve",
"error": null,
"retry_at": null,
"steps": [
{
"name": "resolve",
"status": "pending",
"attempts": 0
}
]
},
"created_at": "2026-09-28T21:40:02.114Z",
"updated_at": "2026-09-28T21:40:02.114Z"
}curl -X POST "https://api.osnodata.com/v1/ingest" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-F "[email protected]" \
-F "segment=sections"Com dry_run: true é um ensaio: não nasce item nem anexos, nada vai para o arquivo, e não se transcreve nem se chama o modelo. A resposta (200) diz o resolver e o extractor escolhidos e porquê, o item que ficaria e a sua identidade (external_id), o item que já a tem (existing), os primeiros 1500 caracteres do texto, as páginas, tabelas e páginas por OCR de um documento, a duração e os formatos de um vídeo, os passos seguintes com o trabalho que dão (minutos de áudio, páginas, tokens aproximados, nunca custos), as etiquetas de restrição, e os avisos e erros (anti_bot, js_only, paywall, too_large, unsupported...). status resume: ok, duplicate, warning ou error. O ensaio guarda-se 15 minutos; o seu token, mandado como preview_token, faz o item a partir dele.
curl -X POST "https://api.osnodata.com/v1/ingest" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","dry_run":true}'{
"token": "Hq2vX9mTc4LpR7sKd3NwYb8e",
"expires_at": "2026-09-29T10:15:00Z",
"status": "ok",
"input": {
"kind": "url",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
},
"resolver": {
"key": "youtube",
"type": "video",
"why": "vídeo do YouTube: a página diz título, canal, data, duração e capítulos"
},
"extractor": {
"key": "media",
"why": "vídeo: descarregado pelo gravador (yt-dlp e ffmpeg), depois transcrito"
},
"item": {
"kind": "media",
"title": "Debate quinzenal",
"author": "Parlamento",
"language": null,
"language_from": "transcription",
"external_id": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
},
"existing": null,
"media": {
"type": "video",
"duration_s": 5412,
"format": {
"ext": "mp4",
"height": 1080
},
"stored": {
"audio_bytes": 32472000,
"video_bytes": 1266408000,
"frames": 19
}
},
"steps": [
{
"name": "resolve",
"heavy": true,
"queue": "ingest",
"note": "já feito no ensaio"
},
{
"name": "extract",
"heavy": true,
"queue": "media",
"work": {
"audio_minutes": 90.2
}
},
{
"name": "transcribe",
"heavy": true,
"queue": "media",
"work": {
"transcription_minutes": 90.2
}
},
{
"name": "pieces",
"heavy": true,
"queue": "llm",
"work": {
"llm_calls": 1,
"llm_tokens": 18040
}
}
],
"work": {
"audio_minutes": 90.2,
"transcription_minutes": 90.2,
"llm_calls": 2,
"llm_tokens": 36080,
"embedding_tokens": 18040
},
"restrictions": {
"source": [],
"chosen": [],
"added": [],
"final": [],
"children": {
"comments": [
"personal:private"
]
},
"policies": {}
},
"warnings": [],
"errors": [],
"reused_on_confirm": {
"resolve": true,
"page": false,
"file": false
}
}/v1/ingest/previews/{token}ingest:writeUm ensaio como está agora, durante 15 minutos e só para quem o fez.
Com heavy, a amostra enche-se aqui: heavy.status vai de pending a running e a done ou failed, com transcript, ocr, articles ou render.
curl "https://api.osnodata.com/v1/ingest/previews/Hq2vX9mTc4LpR7sKd3NwYb8e" \
-H "Authorization: Bearer $OSNODATA_KEY"curl -X POST "https://api.osnodata.com/v1/ingest" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"preview_token":"Hq2vX9mTc4LpR7sKd3NwYb8e","title":"Debate quinzenal de Setembro"}'Stream em tempo real
GET /v1/stream mantém uma ligação aberta e envia cada item à medida que é guardado, alterado ou apagado, por Server-Sent Events.
Cada item é um evento item.created ou item.updated cujo id é o seq do item e cujo data é o item, na mesma forma de /v1/items. Um item apagado é um evento item.deleted com o que ficou dele (ver itens apagados). O primeiro evento é ready, com o seq de partida; a cada 15 segundos sem itens chega um heartbeat com o seq a que o stream chegou.
/v1/streamstream:readUm stream text/event-stream com os itens novos.
Parâmetros
Last-Event-IDcabeçalho- Retomar depois deste seq (o id do último evento recebido).
since_seqinteger- O mesmo, como parâmetro. Sem nenhum dos dois, começa no item mais recente.
source, kind, parent, q- Os filtros de /v1/items.
curl "https://api.osnodata.com/v1/stream?kind=article" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-N \
-H "Accept: text/event-stream"retry: 3000
id: 1834
event: ready
data: {"seq":1834}
id: 1835
event: item.created
data: {"id":"Q3W5k3hgVJCc","seq":1835,"kind":"article", ...}
id: 1836
event: item.deleted
data: {"id":"M4Viu41U6RY7","seq":1836,"source_id":"Q3W5k3hgVJCc","kind":"article","reason":"upstream_deleted", ...}
id: 1836
event: heartbeat
data: {"seq":1836,"at":"2026-09-29T10:15:00Z"}Retomar e reconectar
- Guarda o
iddo último evento. Ao voltar a ligar, manda-o emLast-Event-ID(ou emsince_seq) e o stream continua daí sem perder nada, incluindo o que chegou enquanto estavas desligado. Os clientesEventSourcefazem-no sozinhos. - O servidor fecha o stream ao fim de 30 minutos. É normal: volta a ligar ao fim de 3 segundos (o
retry: 3000do início) com o último id. - Se passarem mais de 45 segundos sem nenhum evento nem heartbeat, a ligação morreu: fecha-a e volta a ligar.
- O
EventSourcedos browsers não envia cabeçalhos, e uma chave não deve ir parar a um browser: lê o stream num servidor, comfetchou com uma biblioteca de SSE que aceite cabeçalhos.
// Node 18+ ou qualquer runtime com fetch; guarda lastSeq para retomar.
let lastSeq: string | undefined;
function handle(item: { id: string; seq: number; title: string | null }) {
console.log(item.seq, item.title);
}
function remove(deleted: { id: string; reason: string }) {
console.log("apagado", deleted.id, deleted.reason);
}
async function listen() {
const response = await fetch("https://api.osnodata.com/v1/stream?kind=article", {
headers: {
Authorization: `Bearer ${process.env.OSNODATA_KEY}`,
Accept: "text/event-stream",
...(lastSeq ? { "Last-Event-ID": lastSeq } : {}),
},
});
if (!response.ok || !response.body) throw new Error(`stream ${response.status}`);
const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
const { value, done } = await reader.read();
if (done) return;
buffer += value;
let end: number;
while ((end = buffer.indexOf("\n\n")) >= 0) {
const block = buffer.slice(0, end);
buffer = buffer.slice(end + 2);
const field = (name: string) =>
block.split("\n").find((line) => line.startsWith(`${name}: `))?.slice(name.length + 2);
const event = field("event");
if (field("id")) lastSeq = field("id");
if (event === "item.created" || event === "item.updated")
handle(JSON.parse(field("data")!));
else if (event === "item.deleted") remove(JSON.parse(field("data")!));
}
}
}
// O servidor fecha ao fim de 30 minutos: volta-se a ligar, com o último seq.
for (;;) {
try {
await listen();
} catch (error) {
console.warn(error);
}
await new Promise((resolve) => setTimeout(resolve, 3000));
}Limites
- No máximo 2 streams abertos por chave; o terceiro responde
429 too_many_streamscomRetry-After: 30. - O stream atravessa o Cloudflare, que corta ligações paradas: os heartbeats de 15 segundos mantêm-na viva. Não uses proxies que guardem a resposta em buffer.
- Cada ligação conta como um pedido nos limites da chave; os bytes enviados contam no uso quando o stream fecha.
- Filtros longos (centenas de fontes) vão em
POST /v1/stream, com os mesmos parâmetros num corpo JSON, a ler comfetch.
Directo dos canais
O vídeo em directo de um canal (uma fonte live_channel) vê-se pelo proxy da API, que busca a playlist HLS com o Referer que a CDN pede. O bilhete vai na URL, porque um leitor de vídeo não manda cabeçalhos; vale 30 minutos e deixa de valer se a chave for revogada ou perder live:read.
/v1/channels/{id}/ticketlive:readUm bilhete e o playlist_url para dar ao leitor HLS.
curl -X POST "https://api.osnodata.com/v1/channels/JeVYy6JEZVlM/ticket" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"playlist_url": "https://api.osnodata.com/live/JeVYy6JEZVlM/playlist.m3u8?t=...",
"ticket": "...",
"expires_at": "2026-09-30T10:30:00Z"
}Webhooks
Um webhook recebe os itens novos num POST assinado para um endereço teu, sem teres de manter uma ligação aberta. Todos os endpoints precisam de webhooks:write.
Criar e gerir
Cada chave tem até 10 webhooks. Um webhook começa no item mais recente, ou em since_seq se o indicares, e escolhe os eventos e os filtros que quer (os mesmos de /v1/items, como texto). O endereço tem de ser https e público; os redireccionamentos não são seguidos.
/v1/webhookswebhooks:writeCria um webhook. A resposta traz o secret que assina as entregas, uma única vez: guarda-o.
Corpo (JSON)
urlstring- Obrigatório. https.
descriptionstring- Até 200 caracteres.
eventsstring[]item.created,item.updatede/ouitem.deleted; por omissão, os três.filtersobjectsource,kind,parent,q,published_after...since_seqinteger- Começar depois deste seq.
curl -X POST "https://api.osnodata.com/v1/webhooks" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://exemplo.pt/osnodata","description":"Notícias de Lisboa","events":["item.created"],"filters":{"kind":"article","q":"lisboa"}}'{
"id": "wh3Kd9sLq2Xa",
"url": "https://exemplo.pt/osnodata",
"description": "Notícias de Lisboa",
"events": [
"item.created"
],
"filters": {
"kind": "article",
"q": "lisboa"
},
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_delivery_at": "2026-09-29T10:14:02Z",
"last_success_at": "2026-09-29T10:14:02Z",
"created_at": "2026-09-20T09:00:00Z",
"updated_at": "2026-09-29T10:14:02Z",
"secret": "whsec_9fK2..."
}/v1/webhookswebhooks:writeOs webhooks desta chave.
curl "https://api.osnodata.com/v1/webhooks" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"webhooks": [
{
"id": "wh3Kd9sLq2Xa",
"url": "https://exemplo.pt/osnodata",
"description": "Notícias de Lisboa",
"events": [
"item.created",
"item.deleted",
"item.updated"
],
"filters": {
"kind": "article",
"q": "lisboa"
},
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_delivery_at": "2026-09-29T10:14:02Z",
"last_success_at": "2026-09-29T10:14:02Z",
"created_at": "2026-09-20T09:00:00Z",
"updated_at": "2026-09-29T10:14:02Z"
}
]
}/v1/webhooks/{id}webhooks:writeUm webhook. last_seq é o seq até onde as entregas foram aceites.
curl "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "wh3Kd9sLq2Xa",
"url": "https://exemplo.pt/osnodata",
"description": "Notícias de Lisboa",
"events": [
"item.created",
"item.deleted",
"item.updated"
],
"filters": {
"kind": "article",
"q": "lisboa"
},
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_delivery_at": "2026-09-29T10:14:02Z",
"last_success_at": "2026-09-29T10:14:02Z",
"created_at": "2026-09-20T09:00:00Z",
"updated_at": "2026-09-29T10:14:02Z"
}/v1/webhooks/{id}webhooks:writeAltera url, description, events, filters ou enabled. enabled: false pára as entregas; enabled: true reactiva um webhook desactivado a partir de onde parou.
curl -X PATCH "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":true}'{
"id": "wh3Kd9sLq2Xa",
"url": "https://exemplo.pt/osnodata",
"description": "Notícias de Lisboa",
"events": [
"item.created",
"item.deleted",
"item.updated"
],
"filters": {
"kind": "article",
"q": "lisboa"
},
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_delivery_at": "2026-09-29T10:14:02Z",
"last_success_at": "2026-09-29T10:14:02Z",
"created_at": "2026-09-20T09:00:00Z",
"updated_at": "2026-09-29T10:14:02Z",
"...": "..."
}/v1/webhooks/{id}/rotate_secretwebhooks:writeTroca o segredo. O anterior deixa logo de assinar: actualiza o receptor antes.
curl -X POST "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa/rotate_secret" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "wh3Kd9sLq2Xa",
"...": "...",
"secret": "whsec_Xy7..."
}/v1/webhooks/{id}webhooks:writeApaga o webhook e o seu registo de entregas.
curl -X DELETE "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa" \
-H "Authorization: Bearer $OSNODATA_KEY"HTTP/1.1 204 No ContentEntregas e payload
Cada entrega é um POST JSON com até 20 itens, pela ordem do seq, cada um com o seu event. O id do corpo é o da entrega; o next_since_seq é o seq até onde esta entrega chega. Um webhook com item.deleted recebe também deleted, os itens apagados (aplica-os junto com items por ordem de seq); os outros recebem o corpo de sempre, sem essa chave.
Cabeçalhos
X-OSNOdata-Eventitemsouping.X-OSNOdata-Delivery- O id da entrega.
X-OSNOdata-Webhook- O id do webhook.
X-OSNOdata-Signaturet=<unix>,v1=<hex>, ver abaixo.User-AgentOSNOdata-Webhooks/1
Content-Type: application/json
X-OSNOdata-Event: items
X-OSNOdata-Delivery: dl8Pz1Qw4Rt6
X-OSNOdata-Webhook: wh3Kd9sLq2Xa
X-OSNOdata-Signature: t=1790676842,v1=5f1c0e...
{
"id": "dl8Pz1Qw4Rt6",
"type": "items",
"webhook_id": "wh3Kd9sLq2Xa",
"created_at": "2026-09-29T10:14:01Z",
"next_since_seq": 1834,
"items": [
{
"event": "item.created",
"id": "Q3W5k3hgVJCc",
"seq": 1834,
"kind": "article",
"source_id": "M4Viu41U6RY7",
"parent_id": null,
"story_id": "b7Tq2LmX9aKe",
"external_id": "https://24noticias.sapo.pt/?p=674780",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"content": "A Câmara Municipal de Lisboa aprovou esta segunda-feira...",
"url": "https://24noticias.sapo.pt/...",
"author": "David Pacheco",
"language": "pt",
"published_at": "2026-09-28T21:36:18.000Z",
"fetched_at": "2026-09-28T21:40:02.114Z",
"starts_at": null,
"ends_at": null,
"location": null,
"metadata": {},
"media": null,
"restrictions": [],
"redacted_fields": [],
"document": null,
"ingest": null,
"created_at": "2026-09-28T21:40:02.114Z",
"updated_at": "2026-09-28T21:40:02.114Z"
}
],
"deleted": [
{
"event": "item.deleted",
"id": "M4Viu41U6RY7",
"seq": 1833,
"source_id": "Q3W5k3hgVJCc",
"parent_id": null,
"kind": "article",
"reason": "upstream_deleted",
"deleted_at": "2026-09-29T10:12:40Z"
}
]
}2xx é uma entrega aceite. Responde depressa (em menos de 10 segundos) e trata os itens depois. O mesmo item pode chegar mais de uma vez, quando muda ou numa repetição: deduplica pelo id do item.Verificar a assinatura
v1 é o HMAC-SHA256, com o segredo do webhook, de <t>.<corpo>: o t do cabeçalho, um ponto e o corpo tal como chegou, byte a byte. Calcula-o, compara em tempo constante e recusa um t com mais de 5 minutos, para que uma entrega interceptada não possa ser repetida.
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const SECRET = process.env.OSNODATA_WEBHOOK_SECRET!; // whsec_...
const TOLERANCE_S = 300;
export function verifySignature(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(
header.split(",").map((part) => {
const at = part.indexOf("=");
return [part.slice(0, at), part.slice(at + 1)];
}),
);
const t = parts.t ?? "";
if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_S)
return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
// O corpo tem de ser lido tal como chegou, antes de qualquer JSON.parse.
createServer(async (request, response) => {
const chunks: Buffer[] = [];
for await (const chunk of request) chunks.push(chunk as Buffer);
const rawBody = Buffer.concat(chunks).toString("utf8");
const header = String(request.headers["x-osnodata-signature"] ?? "");
if (!verifySignature(rawBody, header, SECRET)) {
response.writeHead(401).end();
return;
}
const delivery = JSON.parse(rawBody);
for (const item of delivery.items ?? []) {
// deduplicar pelo item.id: o mesmo item pode chegar mais de uma vez
}
response.writeHead(204).end();
}).listen(8080);Repetições e desactivação
- Uma resposta que não seja
2xx, ou 10 segundos sem resposta, é uma falha. A entrega é repetida ao fim de 30 s, 2 min, 10 min, 30 min, 1 h, 3 h e 6 h. - As entregas são em série: uma que falhou segura as seguintes, por isso os itens chegam por ordem e nada se perde.
- Depois da 8.ª falha seguida, o webhook é desactivado (
enabled: false, comdisabled_atedisabled_reason) e o dono da chave é avisado por email. Corrigido o receptor, reactiva-o comPATCH {"enabled": true}: as entregas continuam de onde pararam.
Registo e ping
Cada entrega fica registada durante 30 dias, com o estado (pending, retrying, delivered, failed), as tentativas, o código e os primeiros 500 bytes da tua resposta.
/v1/webhooks/{id}/deliverieswebhooks:writeO registo de entregas, mais recentes primeiro.
Parâmetros
statusstring- Um ou mais, separados por vírgulas (
failed,retrying). limitinteger- De 1 a 200, 50 por omissão.
cursorstring- O
next_cursorda página anterior.
curl "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa/deliveries?status=failed,retrying" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"deliveries": [
{
"id": "dl8Pz1Qw4Rt6",
"event": "items",
"status": "retrying",
"seq_from": 1830,
"seq_to": 1834,
"item_count": 3,
"item_ids": [
"Q3W5k3hgVJCc",
"..."
],
"deleted_count": 1,
"attempts": 2,
"response_status": 502,
"response_body": "Bad Gateway",
"error": null,
"duration_ms": 182,
"next_attempt_at": "2026-09-29T10:24:02Z",
"last_attempt_at": "2026-09-29T10:14:02Z",
"delivered_at": null,
"created_at": "2026-09-29T10:14:01Z"
}
],
"next_cursor": null
}/v1/webhooks/{id}/pingwebhooks:writeEnvia já uma entrega ping assinada e responde como correu. Serve para testar o receptor: não mexe no seq do webhook nem conta como falha.
curl -X POST "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa/ping" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "dlP1ng0000Ab",
"event": "ping",
"status": "delivered",
"seq_from": null,
"seq_to": null,
"item_count": 0,
"item_ids": [],
"deleted_count": 1,
"attempts": 1,
"response_status": 204,
"response_body": "",
"error": null,
"duration_ms": 182,
"next_attempt_at": null,
"last_attempt_at": "2026-09-29T10:14:02Z",
"delivered_at": "2026-09-29T10:14:02Z",
"created_at": "2026-09-29T10:14:01Z"
}Subscrições (pesquisas guardadas)
Uma subscrição guarda uma pesquisa e avisa um endereço teu de cada item novo que lhe corresponda, segundos depois de ficar pesquisável: o gatilho de um bot de menções. Os endpoints precisam de webhooks:write e de items:read.
Criar e gerir
A pesquisa funciona como em /v1/search: keyword (por omissão) é o texto completo em português, com e sem acentos (Gonçalves encontra GONCALVES), com aspas para uma frase exacta; semantic compara o significado (a semelhança entre os vectores da pesquisa e do item, pelo menos min_similarity, 0,6 por omissão); hybrid basta um dos dois. Os filtros de /v1/items (fonte, tipo, língua, país...) estreitam-na; os blocos dos canais em directo entram, salvo blocks. Cada chave tem até 20 subscrições, e cada uma começa no item mais recente, ou em since_seq.
/v1/subscriptionswebhooks:write + items:readCria uma subscrição. A resposta traz o secret que assina as entregas, uma única vez: o teu, se o mandaste, ou um whsec_... novo.
Corpo (JSON)
querystring- Obrigatório. Até 500 caracteres; q também serve.
urlstring- Obrigatório. https e público.
namestring- Até 200 caracteres.
modestringkeyword,semanticouhybrid.min_similaritynumber- De 0,3 a 0,95, nos modos semânticos.
filtersobjectsource,kind,language,country,blocks... (semq).secretstring- O teu segredo, com 24 caracteres ou mais.
batch_sizeinteger- Itens por entrega, de 1 a 50 (10).
since_seqinteger- Começar depois deste seq.
curl -X POST "https://api.osnodata.com/v1/subscriptions" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Menções","query":"Reconquista","url":"https://exemplo.pt/osnodata/mencoes","filters":{"language":"pt"}}'{
"id": "Sb4Tq8Lm2Wx0",
"name": "Menções",
"query": "Reconquista",
"mode": "keyword",
"min_similarity": null,
"filters": {
"language": "pt"
},
"url": "https://exemplo.pt/osnodata/mencoes",
"batch_size": 10,
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_scan_at": "2026-10-16T21:40:10Z",
"last_match_at": "2026-10-16T21:40:02Z",
"last_delivery_at": "2026-10-16T21:40:02Z",
"last_success_at": "2026-10-16T21:40:02Z",
"created_at": "2026-10-16T09:00:00Z",
"updated_at": "2026-10-16T21:40:02Z",
"secret": "whsec_9fK2..."
}/v1/subscriptionswebhooks:write + items:readAs subscrições desta chave; /v1/subscriptions/{id} dá uma.
curl "https://api.osnodata.com/v1/subscriptions" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"subscriptions": [
{
"id": "Sb4Tq8Lm2Wx0",
"name": "Menções",
"query": "Reconquista",
"mode": "keyword",
"min_similarity": null,
"filters": {
"language": "pt"
},
"url": "https://exemplo.pt/osnodata/mencoes",
"batch_size": 10,
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_scan_at": "2026-10-16T21:40:10Z",
"last_match_at": "2026-10-16T21:40:02Z",
"last_delivery_at": "2026-10-16T21:40:02Z",
"last_success_at": "2026-10-16T21:40:02Z",
"created_at": "2026-10-16T09:00:00Z",
"updated_at": "2026-10-16T21:40:02Z"
}
]
}/v1/subscriptions/{id}webhooks:write + items:readAltera query, mode, filters, url, batch_size ou enabled. enabled: true reactiva uma subscrição desactivada, com o que ficou por enviar.
curl -X PATCH "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"\"Afonso Gonçalves\" or Reconquista"}'{
"id": "Sb4Tq8Lm2Wx0",
"name": "Menções",
"query": "Reconquista",
"mode": "keyword",
"min_similarity": null,
"filters": {
"language": "pt"
},
"url": "https://exemplo.pt/osnodata/mencoes",
"batch_size": 10,
"enabled": true,
"last_seq": 1834,
"consecutive_failures": 0,
"disabled_at": null,
"disabled_reason": null,
"last_scan_at": "2026-10-16T21:40:10Z",
"last_match_at": "2026-10-16T21:40:02Z",
"last_delivery_at": "2026-10-16T21:40:02Z",
"last_success_at": "2026-10-16T21:40:02Z",
"created_at": "2026-10-16T09:00:00Z",
"updated_at": "2026-10-16T21:40:02Z",
"...": "..."
}/v1/subscriptions/{id}/rotate_secretwebhooks:write + items:readTroca o segredo, por um novo ou pelo secret que mandares. O anterior deixa logo de assinar.
curl -X POST "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/rotate_secret" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "Sb4Tq8Lm2Wx0",
"...": "...",
"secret": "whsec_Xy7..."
}/v1/subscriptions/{id}webhooks:write + items:readApaga a subscrição, as correspondências e o registo de entregas.
curl -X DELETE "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0" \
-H "Authorization: Bearer $OSNODATA_KEY"HTTP/1.1 204 No ContentQuando um item corresponde
- Um item é visto de cada vez que muda. Um vídeo encontrado antes da transcrição é avisado quando é transcrito; um bloco de um canal em directo, logo que é transcrito; as peças de um programa, quando são feitas.
- Cada item chega uma vez por subscrição, também pelos ids que ganhou numa fusão. A mesma menção contada por outro item (o bloco, depois o programa e a peça que o contêm; um episódio e a sua peça, a 90 s uma da outra) e o mesmo URL vindo de outra fonte não se repetem.
- Nos modos semânticos, um item espera pelo seu vector (até 10 minutos), que é calculado logo a seguir a ser guardado.
- Cada entrega segue os direitos da chave no momento do envio: os itens escondidos ficam de fora, os redigidos têm o excerto só do título.
Entregas e payload
Cada entrega é um POST JSON com até batch_size correspondências, cada uma um item compacto (sem o texto todo: GET /v1/items/:id ou /media para o resto) com o excerto à volta da menção. Numa peça, episode_id é o episódio e start_s/end_s o seu troço nele; match_s é onde foi dito, em segundos do episódio, do programa ou do bloco, e match_time a hora, num canal.
Cabeçalhos
X-OSNOdata-Eventsearch.matchouping.X-OSNOdata-Delivery- O id da entrega, o mesmo nas repetições.
X-OSNOdata-Subscription- O id da subscrição.
X-OSNOdata-Signaturet=<unix>,v1=<hex>, como nos webhooks, assinado de novo em cada tentativa.
Content-Type: application/json
X-OSNOdata-Event: search.match
X-OSNOdata-Delivery: Hq8sV2nL0cXe
X-OSNOdata-Subscription: Sb4Tq8Lm2Wx0
X-OSNOdata-Signature: t=1792186802,v1=8a03c1...
{
"id": "Hq8sV2nL0cXe",
"type": "search.match",
"subscription_id": "Sb4Tq8Lm2Wx0",
"subscription": {
"name": "Menções",
"query": "Reconquista",
"mode": "keyword"
},
"created_at": "2026-10-16T21:40:02Z",
"matches": [
{
"id": "Bk7m2Qx9Lp0a",
"title": "RTP3 · 21:39",
"url": "https://www.rtp.pt/play/direto/rtp3",
"kind": "media",
"source_id": "M4Viu41U6RY7",
"source_name": "RTP3",
"language": "pt",
"published_at": "2026-10-16T20:39:00Z",
"parent_id": "Dy3n0Wq1Rt5u",
"episode_id": null,
"live": "block",
"start_s": 0,
"end_s": 60,
"match_s": 12,
"match_time": "2026-10-16T20:39:12Z",
"snippet": "o líder da Reconquista disse que a marcha sai às três",
"highlights": [
[
11,
22
]
],
"keyword": true,
"similarity": null,
"restrictions": [],
"matched_at": "2026-10-16T21:40:02Z"
}
]
}t com mais de 5 minutos e deduplica pelo X-OSNOdata-Delivery. Qualquer 2xx é aceite. As falhas repetem-se como nos webhooks (30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h); à 8.ª a subscrição é desactivada e o dono avisado por email, e as correspondências ficam à espera de PATCH {"enabled": true}.Registo e ping
/v1/subscriptions/{id}/deliverieswebhooks:write + items:readO registo de entregas (30 dias), mais recentes primeiro, com status, limit e cursor como nos webhooks.
curl "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/deliveries" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"deliveries": [
{
"id": "Hq8sV2nL0cXe",
"event": "search.match",
"status": "delivered",
"attempts": 1,
"response_status": 202,
"response_body": "",
"error": null,
"duration_ms": 140,
"next_attempt_at": null,
"last_attempt_at": "2026-10-16T21:40:02Z",
"delivered_at": "2026-10-16T21:40:02Z",
"created_at": "2026-10-16T21:40:02Z",
"match_count": 1,
"item_ids": [
"Bk7m2Qx9Lp0a"
]
}
],
"next_cursor": null
}/v1/subscriptions/{id}/matcheswebhooks:write + items:readOs itens que corresponderam (90 dias), os repetidos também (duplicate), com a entrega que os levou.
curl "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/matches" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"matches": [
{
"item_id": "Bk7m2Qx9Lp0a",
"keyword": true,
"similarity": null,
"timeline": "src:M4Viu41U6RY7",
"match_at": 1792182552,
"duplicate": false,
"delivery_id": "Hq8sV2nL0cXe",
"created_at": "2026-10-16T21:40:02Z"
}
],
"next_cursor": null
}/v1/subscriptions/{id}/pingwebhooks:write + items:readEnvia já uma entrega ping assinada e responde como correu.
curl -X POST "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/ping" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "dlP1ng0000Ab",
"event": "ping",
"status": "delivered",
"attempts": 1,
"response_status": 202,
"response_body": "",
"error": null,
"duration_ms": 140,
"next_attempt_at": null,
"last_attempt_at": "2026-10-16T21:40:02Z",
"delivered_at": "2026-10-16T21:40:02Z",
"created_at": "2026-10-16T21:40:02Z",
"match_count": 0,
"item_ids": []
}Monitores e menções
Um monitor diz quem a conta vigia; o OSNOdata responde com as menções verdadeiras, julgadas, agrupadas e filtráveis, por API, webhook e MCP. Quem é avisado, por que canal e com que aprovação fica no cliente.
Criar e gerir
Um monitor pertence à conta, não à chave: revogar ou rodar uma chave não apaga a vigilância. Ver precisa de monitors:read; criar, alterar, corrigir e pedir novo juízo de monitors:write. Começa com o que chega a partir de agora (ou de since_seq).
/v1/monitorsmonitors:writeCria um monitor. O nome é único na conta e serve de id nos caminhos e no MCP.
Corpo (JSON)
namestring- Obrigatório.
termsstring[]- Obrigatório. Os nomes canónicos, procurados à letra.
aliasesstring[]- Variantes, grafias, siglas, handles.
descriptionstring- Quem é, para o juiz distinguir homónimos. É o campo que mais conta.
exclusionsstring[]- Sentidos que nunca contam ("Reconquista cristã"): um texto só com estes fecha-se sem modelo.
own_accounts, ignorestring[]- O site e as contas do próprio (o que publicam não é menção), e outros pedaços de URL ou título a ignorar.
filtersobject- Os filtros de /v1/items (fontes, países, línguas, categorias).
max_age_daysinteger- Publicado há mais do que isto (contado de quando foi encontrado) não conta. 7 por omissão.
verifystring- O verificador:
off,borderline(por omissão: só nas menções de passagem, nos textos só com título e nas datas do modelo) ouall. modelsobject- { judge, verify }: ids de modelo; vazio usa o modelo barato do OSNOdata.
daily_judgements, daily_usdnumber- Os tectos de cada dia (200 juízos, 0,5 USD). Passado um, os candidatos esperam pelo dia seguinte.
url, events, batch_size- Para onde vão os eventos mention.* (precisa também de webhooks:write).
curl -X POST "https://api.osnodata.com/v1/monitors" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Reconquista","terms":["Reconquista","Afonso Gonçalves"],"description":"Movimento político e cultural português (nacionalista e católico); Afonso Gonçalves é o seu líder e porta-voz.","exclusions":["Reconquista cristã"],"own_accounts":["recon.pt"]}'{
"id": "Mn7Rq2Lx8Wc0",
"name": "Reconquista",
"terms": [
"Reconquista",
"Afonso Gonçalves"
],
"aliases": [],
"description": "Movimento político e cultural português (nacionalista e católico); Afonso Gonçalves é o seu líder e porta-voz.",
"exclusions": [
"Reconquista cristã"
],
"own_accounts": [
"recon.pt",
"instagram.com/reconquista_pt"
],
"ignore": [],
"filters": {},
"semantic": false,
"min_similarity": null,
"max_age_days": 7,
"summary_language": "pt-PT",
"clip": "off",
"models": {},
"verify": "borderline",
"daily_judgements": 200,
"daily_usd": 0.5,
"enabled": true,
"url": null,
"events": [
"mention.created",
"mention.retracted",
"mention.updated"
],
"batch_size": 10,
"delivery_enabled": true,
"last_run_at": "2026-10-17T08:40:30Z",
"created_at": "2026-10-17T01:00:00Z",
"updated_at": "2026-10-17T01:00:00Z"
}/v1/monitors/{id}monitors:readUm monitor, pelo id ou pelo nome, com as contagens: menções, o que as pesquisas trouxeram nas últimas 24 horas, os juízos e o gasto de hoje, o último juízo, a latência. GET /v1/monitors dá todos (com counts=true, cada um com as suas contagens); PATCH altera; DELETE apaga com as menções.
curl "https://api.osnodata.com/v1/monitors/Reconquista" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "Mn7Rq2Lx8Wc0",
"name": "Reconquista",
"terms": [
"Reconquista",
"Afonso Gonçalves"
],
"aliases": [],
"description": "Movimento político e cultural português (nacionalista e católico); Afonso Gonçalves é o seu líder e porta-voz.",
"exclusions": [
"Reconquista cristã"
],
"own_accounts": [
"recon.pt",
"instagram.com/reconquista_pt"
],
"ignore": [],
"filters": {},
"semantic": false,
"min_similarity": null,
"max_age_days": 7,
"summary_language": "pt-PT",
"clip": "off",
"models": {},
"verify": "borderline",
"daily_judgements": 200,
"daily_usd": 0.5,
"enabled": true,
"url": null,
"events": [
"mention.created",
"mention.retracted",
"mention.updated"
],
"batch_size": 10,
"delivery_enabled": true,
"last_run_at": "2026-10-17T08:40:30Z",
"created_at": "2026-10-17T01:00:00Z",
"updated_at": "2026-10-17T01:00:00Z",
"counts": {
"mentions": 92,
"mentions_today": 1,
"mentions_7d": 6,
"candidates_24h": {
"accepted": 2,
"gated_out": 14,
"rejected": 3,
"superseded": 2
},
"judgements_today": 7,
"usd_today": 0.0041,
"latency_p50_s": 420,
"latency_p95_s": 2700,
"last_judged_at": "2026-10-17T09:41:12Z"
}
}Como se decide
- As pesquisas do monitor (texto completo dos termos, e uma semântica sobre a descrição se
semantic) trazem os candidatos, vídeos e blocos dos canais em directo incluídos, de cada vez que um item muda. - Portas em código fecham sem custo o que não pode ser menção: a mesma menção já registada (o mesmo item, URL, título ou vídeo noutra fonte, que vão para
also), as contas do próprio, páginas de índice, o que é mais antigo quemax_age_days, o termo só dentro de outra palavra ("reconquistar") e o sentido excluído. - Um modelo julga cada candidato sozinho, com janelas à volta de cada vez que o termo aparece. Num bloco de um directo, julga o seu minuto com cerca de 5 minutos à volta como contexto; uma recusa de um bloco é provisória e nunca cala a peça do mesmo momento, que é julgada por si e, aceite, faz ou melhora a menção. A citação tem de estar no texto do próprio item.
- O mesmo programa publicado por várias fontes (a gravação do directo do canal, o vídeo no site, o YouTube, o podcast só com o som) é uma menção: um item de média emitido ou publicado a menos de 2 dias de uma menção, com as mesmas palavras à volta do nome, é uma cópia, nunca julgada nem menção à parte, e vai para
alsocom a razãoa mesma emissão, o órgão, o meio e se tem imagem. O item da menção é a melhor cópia (o vídeo a pedido, depois a gravação com imagem, depois só o som; entre iguais, a primeira) e o clip corta-se dela; uma melhor que chegue depois toma a menção commention.updated, nunca um segundomention.created. Uma menção que já existia e se descobre cópia de outra ficastatus: copycomcopy_of_ide é enviada comomention.retracted. - O mesmo acontecimento noutro órgão é uma menção própria no mesmo
group_id; uma reacção ou um desenvolvimento é um acontecimento novo. - O juiz pode ler o texto inteiro de um item; o que cada chave recebe segue as suas restrições: uma menção de um item escondido não aparece, a de um item redigido vem sem
quotenemexcerpt.
/v1/monitors/{id}/candidatesmonitors:readO que as pesquisas trouxeram e o que foi decidido de cada um (30 dias), com status, stage e o porquê, e o item (título, URL, fonte) quando a chave o pode ver.
curl "https://api.osnodata.com/v1/monitors/Reconquista/candidates?status=rejected,gated_out" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"candidates": [
{
"id": 4211,
"item_id": "Hx2Lq9Pz0Nm1",
"status": "gated_out",
"stage": "term",
"reason": "sem o termo à vista no texto do próprio item",
"context_kind": null,
"attempts": 0,
"cost_usd": 0,
"mention_id": null,
"duplicate": false
},
{
"id": 4209,
"item_id": "Rt5Wq1Kd8Ys3",
"status": "rejected",
"stage": "judge",
"reason": "a Reconquista histórica",
"context_kind": "article",
"attempts": 0,
"cost_usd": 0.00041,
"model": "deepseek/deepseek-v4-flash-0731",
"mention_id": null,
"duplicate": false
}
],
"next_cursor": "4209"
}/v1/monitors/{id}/rejudgemonitors:writeVolta a julgar os candidatos recusados desde since (no máximo 200); com dry_run diz só quantos e quanto custaria.
curl -X POST "https://api.osnodata.com/v1/monitors/Reconquista/rejudge" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"since":"-7d","dry_run":true}'{
"candidates": 41,
"estimated_usd": 0.0172,
"dry_run": true,
"queued": 0
}Menções
/v1/mentionsmonitors:readAs menções, das encontradas mais recentemente para as mais antigas, filtradas.
Parâmetros
monitorstring- Id(s) ou nome(s), separados por vírgulas; os da conta por omissão.
since, untilstring- ISO 8601, um dia (
2026-10-16, em Lisboa; emuntil, o fim desse dia) ou relativo:today,yesterday,-24h,-7d,-30m,-2w. date_fieldstringfound(quando o OSNOdata a aceitou, por omissão) oupublished.tonestringfavourable,neutral,hostile,mixed(vírgulas).kindstringnews,opinion,interview,video,social,blog,other.mediumstringpress,tv,radio,web,social,video,podcast.source, country, languagestring- Como em /v1/items.
min_centralityinteger- 0 a 10; 5 ou mais deixa de fora as menções de passagem.
story, groupstring- Uma história do OSNOdata, ou um acontecimento (o id da sua primeira menção).
collapsestringgroup: uma linha por acontecimento, com os outros órgãos emgroup.statusstringactive(por omissão),retracted,copy(as que eram menções e afinal são cópias de outra) ouall.qstring- Texto no título, no resumo ou na citação.
limit, cursor, since_seq- Como em /v1/items: navegar com cursor, ou sincronizar com since_seq (todas as alterações, também as retiradas).
curl "https://api.osnodata.com/v1/mentions?monitor=Reconquista&since=yesterday&tone=hostile&collapse=group" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"mentions": [
{
"id": "Me4Kp9Vb1Tz2",
"seq": 812,
"monitor_id": "Mn7Rq2Lx8Wc0",
"monitor_name": "Reconquista",
"status": "active",
"item_id": "NNN6iTKonRk7",
"source_id": "S1cN0t1c1as0",
"source_name": "SIC Notícias",
"url": "https://sicnoticias.pt/programas/eixodomal/2026-10-15-video",
"title": "Debate sobre uma coligação com o Chega",
"medium": "tv",
"kind": "opinion",
"tone": "hostile",
"centrality": 2,
"summary": "Num debate sobre o Chega, um comentador refere «Reconquistas» como nome para quem está à direita do partido.",
"quote": "chamam-lhe Reconquistas, chamam-lhe o que quiserem",
"excerpt": "...que é mais à direita ainda de que o Chega formava ao seu próprio partido, chamam-lhe Reconquistas...",
"terms_matched": [
"Reconquista"
],
"published_at": "2026-10-15T21:30:00Z",
"date_source": "item",
"said_at": "2026-10-15T22:41:12Z",
"found_at": "2026-10-15T22:44:20Z",
"latency_s": 188,
"episode_id": "Pr0gr4m4Eix0",
"start_s": 1250,
"end_s": 1490,
"match_s": 1311,
"story_id": null,
"group_id": "Me4Kp9Vb1Tz2",
"also": [
{
"item_id": "Bl0ck22h41mn",
"url": "https://sicnoticias.pt/directo",
"title": "SIC · 22:41",
"reason": "o mesmo momento"
},
{
"item_id": "P0dc4stEix0s",
"source_id": "Exp4essoPod1",
"url": "https://expresso.pt/podcasts/eixo-do-mal",
"title": "Análise à entrevista de Pedro Passos Coelho",
"reason": "a mesma emissão",
"source_name": "Eixo do Mal (Expresso)",
"medium": "podcast",
"video": false,
"episode_id": "P0dc4stEp15d",
"start_s": 20,
"match_s": 397
}
],
"copy_of_id": null,
"judged_by": "model",
"model": "deepseek/deepseek-v4-flash-0731",
"clip_id": null,
"restrictions": [],
"redacted_fields": [],
"group": []
}
],
"next_cursor": null
}/v1/mentions/{id}monitors:readUma menção, com o item resumido e o grupo; include=decisions traz o caminho dos seus candidatos. /v1/mentions/stats dá as contagens por dia, tom, meio, tipo e fonte.
curl "https://api.osnodata.com/v1/mentions/Me4Kp9Vb1Tz2?include=decisions" \
-H "Authorization: Bearer $OSNODATA_KEY"{
"id": "Me4Kp9Vb1Tz2",
"seq": 812,
"monitor_id": "Mn7Rq2Lx8Wc0",
"monitor_name": "Reconquista",
"status": "active",
"item_id": "NNN6iTKonRk7",
"source_id": "S1cN0t1c1as0",
"source_name": "SIC Notícias",
"url": "https://sicnoticias.pt/programas/eixodomal/2026-10-15-video",
"title": "Debate sobre uma coligação com o Chega",
"medium": "tv",
"kind": "opinion",
"tone": "hostile",
"centrality": 2,
"summary": "Num debate sobre o Chega, um comentador refere «Reconquistas» como nome para quem está à direita do partido.",
"quote": "chamam-lhe Reconquistas, chamam-lhe o que quiserem",
"excerpt": "...que é mais à direita ainda de que o Chega formava ao seu próprio partido, chamam-lhe Reconquistas...",
"terms_matched": [
"Reconquista"
],
"published_at": "2026-10-15T21:30:00Z",
"date_source": "item",
"said_at": "2026-10-15T22:41:12Z",
"found_at": "2026-10-15T22:44:20Z",
"latency_s": 188,
"episode_id": "Pr0gr4m4Eix0",
"start_s": 1250,
"end_s": 1490,
"match_s": 1311,
"story_id": null,
"group_id": "Me4Kp9Vb1Tz2",
"also": [
{
"item_id": "Bl0ck22h41mn",
"url": "https://sicnoticias.pt/directo",
"title": "SIC · 22:41",
"reason": "o mesmo momento"
},
{
"item_id": "P0dc4stEix0s",
"source_id": "Exp4essoPod1",
"url": "https://expresso.pt/podcasts/eixo-do-mal",
"title": "Análise à entrevista de Pedro Passos Coelho",
"reason": "a mesma emissão",
"source_name": "Eixo do Mal (Expresso)",
"medium": "podcast",
"video": false,
"episode_id": "P0dc4stEp15d",
"start_s": 20,
"match_s": 397
}
],
"copy_of_id": null,
"judged_by": "model",
"model": "deepseek/deepseek-v4-flash-0731",
"clip_id": null,
"restrictions": [],
"redacted_fields": [],
"decisions": [
{
"item_id": "Bl0ck22h41mn",
"status": "superseded",
"stage": "moment",
"reason": "o mesmo momento é a menção Me4Kp9Vb1Tz2"
}
]
}/v1/mentions/{id}/feedbackmonitors:writewrong retira a menção; right confirma; corrections corrige tom, tipo, centralidade ou resumo. O texto e o veredicto passam a exemplo do juiz deste monitor. Num candidato recusado, POST /v1/candidates/{id}/feedback com right faz dele uma menção.
curl -X POST "https://api.osnodata.com/v1/mentions/Me4Kp9Vb1Tz2/feedback" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"verdict":"wrong","note":"não é sobre o movimento"}'{
"id": "Me4Kp9Vb1Tz2",
"seq": 812,
"monitor_id": "Mn7Rq2Lx8Wc0",
"monitor_name": "Reconquista",
"status": "retracted",
"item_id": "NNN6iTKonRk7",
"source_id": "S1cN0t1c1as0",
"source_name": "SIC Notícias",
"url": "https://sicnoticias.pt/programas/eixodomal/2026-10-15-video",
"title": "Debate sobre uma coligação com o Chega",
"medium": "tv",
"kind": "opinion",
"tone": "hostile",
"centrality": 2,
"summary": "Num debate sobre o Chega, um comentador refere «Reconquistas» como nome para quem está à direita do partido.",
"quote": "chamam-lhe Reconquistas, chamam-lhe o que quiserem",
"excerpt": "...que é mais à direita ainda de que o Chega formava ao seu próprio partido, chamam-lhe Reconquistas...",
"terms_matched": [
"Reconquista"
],
"published_at": "2026-10-15T21:30:00Z",
"date_source": "item",
"said_at": "2026-10-15T22:41:12Z",
"found_at": "2026-10-15T22:44:20Z",
"latency_s": 188,
"episode_id": "Pr0gr4m4Eix0",
"start_s": 1250,
"end_s": 1490,
"match_s": 1311,
"story_id": null,
"group_id": "Me4Kp9Vb1Tz2",
"also": [
{
"item_id": "Bl0ck22h41mn",
"url": "https://sicnoticias.pt/directo",
"title": "SIC · 22:41",
"reason": "o mesmo momento"
},
{
"item_id": "P0dc4stEix0s",
"source_id": "Exp4essoPod1",
"url": "https://expresso.pt/podcasts/eixo-do-mal",
"title": "Análise à entrevista de Pedro Passos Coelho",
"reason": "a mesma emissão",
"source_name": "Eixo do Mal (Expresso)",
"medium": "podcast",
"video": false,
"episode_id": "P0dc4stEp15d",
"start_s": 20,
"match_s": 397
}
],
"copy_of_id": null,
"judged_by": "model",
"model": "deepseek/deepseek-v4-flash-0731",
"clip_id": null,
"restrictions": [],
"redacted_fields": [],
"retracted_reason": "feedback: não é sobre o movimento"
}/v1/mentions/{id}/clipmonitors:read + media:readO clip de uma menção de televisão, rádio ou vídeo, cortado à volta do que se disse (um modelo escolhe o troço pela transcrição). A mesma menção dá o mesmo clip.
curl -X POST "https://api.osnodata.com/v1/mentions/Me4Kp9Vb1Tz2/clip" \
-H "Authorization: Bearer $OSNODATA_KEY" \
-H "Content-Type: application/json" \
-d '{"output":"video"}'{
"id": "Cl1pXy7Qw2Ee",
"status": "pending",
"output": "video"
}Eventos
Com um url (posto por uma chave com webhooks:write, cujos direitos moldam o que é enviado; na página Monitores do painel, escolhe-se uma chave da conta com webhooks:write e monitors:read), o monitor envia mention.created, mention.updated (melhor contexto, outra ligação ou cópia em also, uma cópia melhor que passa a ser o item, correcções) e mention.retracted (também a de uma menção que afinal é cópia de outra, status: copy), em lotes de batch_size, assinados como os webhooks. /ping, /rotate_secret e /deliveries como nas subscrições.
Cabeçalhos
X-OSNOdata-Eventmentionsouping.X-OSNOdata-Delivery- O id da entrega, o mesmo nas repetições.
X-OSNOdata-Monitor- O id do monitor.
X-OSNOdata-Signature- t=<unix>,v1=<hex>, assinado de novo em cada tentativa.
{
"id": "Dv9Lm3Qa7Rs1",
"type": "mentions",
"monitor_id": "Mn7Rq2Lx8Wc0",
"monitor": {
"name": "Reconquista"
},
"created_at": "2026-10-15T22:44:31Z",
"events": [
{
"event": "mention.created",
"event_id": 1532,
"at": "2026-10-15T22:44:20Z",
"mention": {
"id": "Me4Kp9Vb1Tz2",
"seq": 812,
"monitor_id": "Mn7Rq2Lx8Wc0",
"monitor_name": "Reconquista",
"status": "active",
"item_id": "NNN6iTKonRk7",
"source_id": "S1cN0t1c1as0",
"source_name": "SIC Notícias",
"url": "https://sicnoticias.pt/programas/eixodomal/2026-10-15-video",
"title": "Debate sobre uma coligação com o Chega",
"medium": "tv",
"kind": "opinion",
"tone": "hostile",
"centrality": 2,
"summary": "Num debate sobre o Chega, um comentador refere «Reconquistas» como nome para quem está à direita do partido.",
"quote": "chamam-lhe Reconquistas, chamam-lhe o que quiserem",
"excerpt": "...que é mais à direita ainda de que o Chega formava ao seu próprio partido, chamam-lhe Reconquistas...",
"terms_matched": [
"Reconquista"
],
"published_at": "2026-10-15T21:30:00Z",
"date_source": "item",
"said_at": "2026-10-15T22:41:12Z",
"found_at": "2026-10-15T22:44:20Z",
"latency_s": 188,
"episode_id": "Pr0gr4m4Eix0",
"start_s": 1250,
"end_s": 1490,
"match_s": 1311,
"story_id": null,
"group_id": "Me4Kp9Vb1Tz2",
"also": [
{
"item_id": "Bl0ck22h41mn",
"url": "https://sicnoticias.pt/directo",
"title": "SIC · 22:41",
"reason": "o mesmo momento"
},
{
"item_id": "P0dc4stEix0s",
"source_id": "Exp4essoPod1",
"url": "https://expresso.pt/podcasts/eixo-do-mal",
"title": "Análise à entrevista de Pedro Passos Coelho",
"reason": "a mesma emissão",
"source_name": "Eixo do Mal (Expresso)",
"medium": "podcast",
"video": false,
"episode_id": "P0dc4stEp15d",
"start_s": 20,
"match_s": 397
}
],
"copy_of_id": null,
"judged_by": "model",
"model": "deepseek/deepseek-v4-flash-0731",
"clip_id": null,
"restrictions": [],
"redacted_fields": []
}
}
]
}PATCH com "delivery_enabled": true retoma do evento onde pararam. Um monitor sombra (shadow_of_id) nunca entrega.Webhooks de entrada
O contrário dos webhooks: outro serviço (um formulário, o GitHub, o Slack, o Stripe, uma ferramenta de alertas) envia para um URL do OSNOdata, e o que envia vira itens.
Cada webhook de entrada é criado por um administrador no painel e tem um URL secreto, https://api.osnodata.com/inbound/in_..., mostrado só ao criar e ao gerar outro. Não leva chave: o URL e a verificação são as credenciais. Um token desconhecido e um webhook desligado respondem o mesmo 404.
/inbound/{token}Recebe o corpo (até 1 MB), verifica-o e transforma-o em itens da fonte do webhook.
curl -X POST "https://api.osnodata.com/inbound/in_..." \
-H "Content-Type: application/json" \
-d '{"title":"Novo pedido","text":"Mensagem do formulário"}'{
"accepted": 1,
"duplicates": 0,
"items": [
"Hk2PqL9sVx4T"
],
"truncated": false
}Verificação
Sempre sobre o corpo tal como chega, byte a byte, com comparações em tempo constante. Uma assinatura errada ou em falta responde 401.
Esquemas
none- Só o URL secreto.
hmac- Um cabeçalho configurável (
X-Signaturepor omissão) com o HMAC do corpo, SHA-256 ou SHA-1, em hex ou base64, com um prefixo opcional (sha256=). githubX-Hub-Signature-256: sha256=<hex>, o HMAC-SHA256 do corpo.slackX-Slack-Signature: v0=<hex>dev0:<timestamp>:<corpo>, comX-Slack-Request-Timestamp; um timestamp com mais de 5 minutos é recusado.stripeStripe-Signature: t=..,v1=..sobre<t>.<corpo>(basta um dosv1), com 5 minutos de tolerância.header- Um cabeçalho configurável igual ao segredo partilhado.
BODY='{"title":"Novo pedido","text":"Mensagem do formulário"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SEGREDO" -hex | sed 's/^.* //')
curl -X POST "https://api.osnodata.com/inbound/in_..." \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: sha256=$SIG" \
-d "$BODY"Do corpo aos itens
- Payload inteiro como texto: o JSON formatado (ou o corpo como veio, se não for JSON) é o texto do item.
- Caminhos JSON: caminhos simples como
data.items[0].urlou$.titledizem onde estão o URL, o título, o texto, um ficheiro por URL, a data e um id externo. Com um URL, o item é essa página e o texto completa-o; um ficheiro por URL é o item quando não há URL, e um item filho quando há. - Um corpo que seja uma lista, ou um caminho de itens configurado, dá um item por elemento, até 50 (
truncateddiz se havia mais). - O mesmo URL, id externo ou conteúdo é o mesmo item: um envio repetido responde
200comduplicates.
Respostas e limites
Códigos
202- Aceite: accepted itens novos, a seguir pelo núcleo de ingestão.
200- Todos os itens já existiam.
401- Assinatura errada, em falta ou com um timestamp antigo.
404- Token desconhecido ou webhook desligado.
413- Corpo acima de 1 MB.
422- O corpo não é JSON quando os caminhos o pedem (
invalid_json), ou nada nele dá um item (unmapped). 429- Acima do limite por minuto do webhook (60 por omissão), com
Retry-After.
Restrições e direitos
Alguns itens levam etiquetas de restrição. Cada etiqueta tem uma política que diz o que recebe uma chave sem o direito correspondente: nada, o item sem alguns campos, ou o item inteiro.
Etiquetas
Uma etiqueta é uma chave hierárquica familia:nome, por exemplo personal:private, personal:public_figures, copyright:full_text, copyright:media ou licence:open_data. As fontes têm etiquetas (as do seu tipo e as que um administrador acrescenta) e os itens herdam-nas; um item pode ter também as suas. Cada item traz as etiquetas efectivas (as dele e as da fonte) em restrictions, e cada fonte as suas no mesmo campo de GET /v1/sources.
Campos no item
restrictionsstring[]- As etiquetas efectivas do item. Vazio num item sem etiquetas.
redacted_fieldsstring[]- Os campos que esta chave não recebeu:
content,media,transcript,summary,metadata,author. Vazio quando nada foi tirado.
{
"id": "Q3W5k3hgVJCc",
"title": "Câmara de Lisboa aprova novo plano de mobilidade",
"content": "A Câmara Municipal de Lisboa aprovou esta segunda-feira...",
"url": "https://24noticias.sapo.pt/...",
"...": "...",
"restrictions": [
"copyright:full_text"
],
"redacted_fields": [
"content",
"media"
]
}O que cada efeito faz
allow: o item chega inteiro a todas as chaves.redact: sem o direito, o item chega sem os campos da política (listados emredacted_fields). O conteúdo pode ficar reduzido a um excerto inicial. O título, a ligação, a fonte e as datas ficam sempre. Em/v1/items/{id}/mediasaem também os URLs dos ficheiros, a transcrição ou o resumo, conforme a política, e a resposta traz os mesmosrestrictionseredacted_fields. Um clip de um item cuja média foi tirada vem com"withheld": truee semurl.hide: sem o direito, o item não aparece em lado nenhum: na lista, em/v1/items/{id}(responde404), na pesquisa, no stream, nos webhooks, na média e nos clips. Para essa chave, é como se o item não existisse.
Quando um item tem várias etiquetas, os efeitos somam-se: os campos tirados juntam-se, e basta uma etiqueta hide sem direito para o item ficar de fora.
Filtrar por etiqueta
O filtro restriction funciona em /v1/items, /v1/search, /v1/stream e nos webhooks, como os outros filtros. Aceita etiquetas (personal:private), famílias inteiras (personal) ou none para os itens sem nenhuma etiqueta, separados por vírgulas. O filtro só escolhe entre os itens que a chave já pode ver.
curl "https://api.osnodata.com/v1/items?restriction=none,licence:open_data" \
-H "Authorization: Bearer $OSNODATA_KEY"Direitos
Uma política pode indicar um direito (por exemplo restricted:personal_private). As chaves que o têm recebem os itens dessa etiqueta como se ela fosse allow. Os direitos de cada chave aparecem em entitlements na lista de chaves do dashboard, e só um administrador os dá ou tira: o dono da chave não os pode pedir pela API nem mudá-los. Para pedir um direito, fala com quem gere o OSNOdata e explica para que precisas dos dados.
Leituras registadas
Algumas etiquetas são auditadas. Cada vez que uma chave lê um item com uma delas (na lista, num item, na pesquisa, no stream, num webhook, na média ou num clip), fica registado quando, por onde, com que chave, que etiqueta e que campos a chave recebeu. Os administradores consultam esse registo, que é guardado durante um período limitado.
Cliente TypeScript
Um cliente sem dependências vive no repositório, em clients/typescript/ (@osnodata/client). Usa só fetch e APIs web standard, por isso corre em Node 20+, Bun, Deno e Cloudflare Workers.
# a partir de um clone do repositório do OSNOdata
bun add file:../osnodata/clients/typescript
# ou gerar um bundle ESM para copiar para outro projecto
cd clients/typescript && bun run build # escreve dist/index.jsO pacote aponta para o código TypeScript (src/index.ts), o que serve directamente em Bun, Deno e bundlers como o do Next.js. Em Node sem passo de compilação, usa o dist/index.js do bun run build.
import { OSNOdata, OSNOdataError } from "@osnodata/client";
const api = new OSNOdata({ apiKey: process.env.OSNODATA_KEY! });
const page = await api.items.list({ kind: "article", q: "lisboa", limit: 20 });
console.log(api.lastRateLimit); // os cabeçalhos X-RateLimit-* do último pedido
// Sincronizar: guarda sync.lastSeq e retoma daí da próxima vez.
const sync = api.items.sync(lastSeq, { kind: "media" });
for await (const item of sync) await store(item);
lastSeq = sync.lastSeq;
// Com os apagados: itens e apagamentos juntos, pela ordem do seq.
for await (const change of api.items.sync(lastSeq).changes()) {
if (change.type === "upsert") await store(change.item);
else await remove(change.deleted.id);
}
// Pesquisa e clips
const results = await api.search("orçamento do estado", { mode: "hybrid" });
const pending = await api.items.clip(itemId, { start: 120, end: 150 }); // ou clip(pieceId), a peça inteira
const clip = await api.clips.wait(pending.id, { intervalMs: 2000, timeoutMs: 120_000 });
// Stream: volta a ligar sozinho com Last-Event-ID
for await (const event of api.stream({ filters: { kind: "article" } })) {
if (event.event === "item.created") console.log(event.data.title);
}items.iteratepercorre as páginas com o cursor;items.syncsincroniza por seq.- Os erros da API são
OSNOdataError, comstatus,code,param,retryAftererateLimit. webhooks.createdevolve osecretuma única vez, tal como a API.
import { parseWebhook } from "@osnodata/client";
// Verifica a assinatura e a idade (300 s) e devolve o corpo já lido.
const payload = await parseWebhook({
secret: process.env.OSNODATA_WEBHOOK_SECRET!,
body: await request.text(),
header: request.headers.get("X-OSNOdata-Signature"),
});O README.md de clients/typescript/ descreve todos os métodos e opções.
Servidor MCP
A API como ferramentas para assistentes de IA (Claude e outros clientes do Model Context Protocol), em https://api.osnodata.com/mcp, por Streamable HTTP.
Leva a mesma chave da API em Authorization: Bearer, em cada pedido. O servidor só mostra as ferramentas que os scopes da chave permitem e faz cada chamada pela API com essa chave: os limites de pedidos, os itens escondidos ou redigidos e o registo das leituras são os mesmos de qualquer outro cliente. Para um assistente de menções e notícias, a chave quer items:read, sources:read e, para transcrições e clips, media:read; com um monitor, monitors:read e find_mentions responde a "as menções da Reconquista desde ontem".
claude mcp add --transport http osnodata https://api.osnodata.com/mcp \
--header "Authorization: Bearer $OSNODATA_KEY"{
"mcpServers": {
"osnodata": {
"type": "http",
"url": "https://api.osnodata.com/mcp",
"headers": { "Authorization": "Bearer osk_live_..." }
}
}
}"mcp_servers": [{
"type": "url",
"url": "https://api.osnodata.com/mcp",
"name": "osnodata",
"authorization_token": "osk_live_..."
}]Ferramentas
search_itemsitems:read- Pesquisa por palavras, por significado ou pelas duas, com os filtros de /v1/items.
list_itemsitems:read- Os itens mais recentes, com filtros, texto completo opcional e cursor.
get_itemitems:read- Um item, com o texto em janelas (offset, max_chars).
get_transcriptmedia:read- A transcrição com tempos, as peças e o resumo; uma peça responde o seu troço.
get_documentmedia:read- As páginas, as partes e, a pedido, as tabelas de um documento.
list_stories, get_storyitems:read- As histórias (recentes ou a crescer) e os itens de uma.
list_sources, get_sourcesources:read- As fontes por nome (sem contar acentos), tipo ou país; uma com os seus números.
create_clipmedia:read- Pede um clip (início e fim, uma peça inteira, ou termos e contexto) e espera pelo URL assinado.
get_clip, list_clipsmedia:read- Um clip, com um URL assinado de novo, e os clips da chave.
create_subscription, list_subscriptions, delete_subscriptionwebhooks:write + items:read- Guarda uma pesquisa cujos itens novos são enviados para um URL (o gatilho de um bot), lista as da chave, apaga uma.
find_mentionsmonitors:read- As menções de um monitor, pelo nome, com datas em linguagem natural (ontem, esta semana, últimas 48 horas), tom e meio em português ou inglês; uma linha por acontecimento.
get_mention, mention_statsmonitors:read- Uma menção, com o caminho das decisões, e as contagens por dia, tom, meio e fonte.
list_monitors, get_monitormonitors:read- Os monitores da conta; um com as contagens, o gasto de hoje e a latência.
create_monitor, update_monitor, mention_feedbackmonitors:write- Cria ou altera um monitor; retira, confirma ou corrige uma menção.
create_mention_clipmonitors:read + media:read- O clip de uma menção, à volta do que se disse.
get_keyqualquer- Os scopes, os direitos e os limites que restam à chave.
- As respostas são texto compacto. Um texto longo vem em janelas e diz como se continua (
offset,from_s,from_page). - Todas as ferramentas são só de leitura (
readOnlyHint), menoscreate_clip, que não apaga nada e dá sempre o mesmo clip para o mesmo pedido,create_subscription, que passa a enviar para um URL,delete_subscription, que apaga, e as que criam ou corrigem monitores e menções. - A média nunca passa pelo servidor: um clip ou um ficheiro é um URL assinado por 15 minutos.
Especificação OpenAPI
Tudo o que está nesta página, em OpenAPI 3.1, para gerar clientes noutras linguagens ou importar no Postman, Insomnia ou Bruno.
A especificação descreve também as entregas dos webhooks, das subscrições e dos monitores (em webhooks.items, webhooks.searchMatch e webhooks.mentions) e os esquemas de cada resposta.