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/items para navegar ou sincronizar, e GET /v1/search para pesquisar.
  • Manter um stream aberto: GET /v1/stream envia 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:

GET/v1/key

A chave que faz o pedido, os seus scopes e os seus limites. Não precisa de scope.

Pedido
curl "https://api.osnodata.com/v1/key" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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:

429 Too Many Requests
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
}
Espera os segundos de 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_clips e daily_clip_limit. Traz Retry-After.
503
Pesquisa semântica sem vectores disponíveis de momento.
422 Unprocessable Entity
{
  "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.

GET/v1/itemsitems:read

Uma 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 400 com reason: "too_many_values", nunca uma lista cortada. Numa query string cabem cerca de 700: para mais, usa POST /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]=Reconquista dá uma pasta inteira do omelhorsite sem listar ids (também as fontes que absorveram uma dessa pasta). Cada valor é exacto; vários com source_meta[oms_feed][]=A&source_meta[oms_feed][]=B. Até 5 chaves.
importedboolean
true: só os itens que vieram do histórico do omelhorsite (com imported: true); false: só os que o OSNOdata recolheu.
kindstring
article, 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 none para 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: include junta-os, only responde 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) ou none para 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_cursor da página anterior.
since_seqinteger
Sincronizar a partir deste seq (ver abaixo).
Pedido
curl "https://api.osnodata.com/v1/items?kind=article&q=lisboa&limit=20" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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_seq e has_more. Repete com since_seq=<next_since_seq> enquanto has_more for true.
  • Guarda o último next_since_seq e continua a partir dele da próxima vez. Um item alterado volta a aparecer com um seq novo: deduplica pelo id.
Pedido
curl "https://api.osnodata.com/v1/items?since_seq=1800&limit=200" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
}
Os itens escritos nos últimos 5 segundos ficam para o pedido seguinte, para nenhum item ficar para trás de um seq que já passaste.

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.

  • reason diz 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) ou deleted (à 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, category e restriction. 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ó /media muda.
Os apagados guardam-se durante 30 dias. Se o teu cliente ficar parado mais tempo do que isso, perde apagamentos: volta a sincronizar tudo desde 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 400 com reason: "too_many_values", nunca uma lista cortada. Numa query string cabem cerca de 700: para mais, usa POST /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]=Reconquista dá uma pasta inteira do omelhorsite sem listar ids (também as fontes que absorveram uma dessa pasta). Cada valor é exacto; vários com source_meta[oms_feed][]=A&source_meta[oms_feed][]=B. Até 5 chaves.
importedboolean
true: só os itens que vieram do histórico do omelhorsite (com imported: true); false: só os que o OSNOdata recolheu.
kindstring
article, 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 none para 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: include junta-os, only responde 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) ou none para 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

GET/v1/items/{id}items:read

Um item, com a mesma forma da lista.

Pedido
curl "https://api.osnodata.com/v1/items/Q3W5k3hgVJCc" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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

POST/v1/items/queryitems:read

O mesmo que GET /v1/items, com os parâmetros num corpo JSON; as listas podem ir como arrays.

Pedido
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}'
Resposta
{
  "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. O score é o ts_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. O score é a semelhança.
  • hybrid (por omissão): as duas listas fundidas por Reciprocal Rank Fusion. O score é 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)).

GET/v1/searchitems:read

Os resultados, melhores primeiro.

Parâmetros

qstring
Obrigatório. A pergunta, até 500 caracteres.
modestring
hybrid (por omissão), semantic ou keyword.
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.
Pedido
curl "https://api.osnodata.com/v1/search?q=greve%20dos%20professores&mode=hybrid&limit=10" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
      }
    }
  ]
}
Se os vectores não estiverem disponíveis, o modo híbrido responde só pelo texto e diz "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.

GET/v1/storiesitems:read

As histórias, as mais recentes ou as que estão a crescer.

Parâmetros

orderstring
recent (por omissão), as vistas mais recentemente primeiro; growing, as contadas por mais fontes nas últimas hours horas primeiro, com recent_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.
Pedido
curl "https://api.osnodata.com/v1/stories?order=growing&hours=6&min_sources=2" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
}
GET/v1/stories/{id}items:read

Uma história com os seus itens, pela ordem em que aconteceram.

Pedido
curl "https://api.osnodata.com/v1/stories/b7Tq2LmX9aKe" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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).

GET/v1/spendingitems:read

Os 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.
Pedido
curl "https://api.osnodata.com/v1/spending?q=plantação%20de%20árvores&level=freguesia&sort=amount" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
      }
    }
  ]
}
GET/v1/spending/summaryitems:read

Quanto somam: o total, por ano, por nível de quem pagou, por conjunto, e quem pagou e recebeu mais.

Pedido
curl "https://api.osnodata.com/v1/spending/summary?q=reflorestação&from=2020-01-01" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
  }
}
GET/v1/spending/{id}items:read

Um registo.

Pedido
curl "https://api.osnodata.com/v1/spending/1048576" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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).

GET/v1/sourcessources:read

Todas 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.
statsboolean
true junta a cada fonte stats: 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.
Pedido
curl "https://api.osnodata.com/v1/sources?enabled=true&country=PT" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
    }
  ]
}
GET/v1/sources/{id}sources:read

Uma fonte, com a mesma forma.

Pedido
curl "https://api.osnodata.com/v1/sources/M4Viu41U6RY7" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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.

GET/v1/items/{item_id}/mediamedia:read

A 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.

Pedido
curl "https://api.osnodata.com/v1/items/VqXKLaXkkn8I/media" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
}
Os URLs são assinados e duram 15 minutos (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}/clip com start e end em segundos do episódio responde 202 com o clip em pending. Um pedido igual a um clip ainda guardado responde 200 com esse clip.
  • Numa peça, sem start nem end, 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). Com terms (as palavras de uma menção) e context (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. O decision do 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é o status ser done, com o url assinado, ou failed, com o error.
  • O url dura 15 minutos; pede o clip outra vez para um novo. Os clips ficam guardados 7 dias.
Um clip dura entre 1 e 600 segundos, dentro do episódio (uma peça responde pelo seu episódio). No máximo 3 clips em curso e 100 por dia por chave (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.
POST/v1/items/{item_id}/clipmedia:read

Pede 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.
Pedido
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}'
Resposta (202)
{
  "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
}
GET/v1/clips/{id}media:read

Um clip; quando está pronto, com o URL assinado.

Pedido
curl "https://api.osnodata.com/v1/clips/c7Lq2VnX9aBd" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
}
GET/v1/clipsmedia:read

Os clips pedidos com esta chave, mais recentes primeiro.

Parâmetros

limitinteger
De 1 a 200, 50 por omissão.
Pedido
curl "https://api.osnodata.com/v1/clips?limit=20" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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.

GET/v1/items/{item_id}/documentmedia:read

As 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.
Pedido
curl "https://api.osnodata.com/v1/items/Tq3LmN8vKc2P/document" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
}
O texto (as páginas, as tabelas, as partes, o OCR) fica sempre inteiro. O ficheiro e as imagens das páginas passam pelas fases dos ficheiros (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.

POST/v1/ingestingest:write

Um 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), sections ou none.
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.
Pedido
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"}'
Resposta (202)
{
  "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"
}
Um ficheiro
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.

Um ensaio
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}'
Resposta (200)
{
  "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
  }
}
GET/v1/ingest/previews/{token}ingest:write

Um 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.

Pedido
curl "https://api.osnodata.com/v1/ingest/previews/Hq2vX9mTc4LpR7sKd3NwYb8e" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Confirmar um ensaio
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.

GET/v1/streamstream:read

Um 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.
Pedido
curl "https://api.osnodata.com/v1/stream?kind=article" \
  -H "Authorization: Bearer $OSNODATA_KEY" \
  -N \
  -H "Accept: text/event-stream"
Resposta (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 id do último evento. Ao voltar a ligar, manda-o em Last-Event-ID (ou em since_seq) e o stream continua daí sem perder nada, incluindo o que chegou enquanto estavas desligado. Os clientes EventSource fazem-no sozinhos.
  • O servidor fecha o stream ao fim de 30 minutos. É normal: volta a ligar ao fim de 3 segundos (o retry: 3000 do 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 EventSource dos browsers não envia cabeçalhos, e uma chave não deve ir parar a um browser: lê o stream num servidor, com fetch ou com uma biblioteca de SSE que aceite cabeçalhos.
TypeScript, sem dependências
// 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_streams com Retry-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 com fetch.

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.

POST/v1/channels/{id}/ticketlive:read

Um bilhete e o playlist_url para dar ao leitor HLS.

Pedido
curl -X POST "https://api.osnodata.com/v1/channels/JeVYy6JEZVlM/ticket" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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.

POST/v1/webhookswebhooks:write

Cria 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.updated e/ou item.deleted; por omissão, os três.
filtersobject
source, kind, parent, q, published_after...
since_seqinteger
Começar depois deste seq.
Pedido
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"}}'
Resposta (201)
{
  "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..."
}
GET/v1/webhookswebhooks:write

Os webhooks desta chave.

Pedido
curl "https://api.osnodata.com/v1/webhooks" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
    }
  ]
}
GET/v1/webhooks/{id}webhooks:write

Um webhook. last_seq é o seq até onde as entregas foram aceites.

Pedido
curl "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
}
PATCH/v1/webhooks/{id}webhooks:write

Altera url, description, events, filters ou enabled. enabled: false pára as entregas; enabled: true reactiva um webhook desactivado a partir de onde parou.

Pedido
curl -X PATCH "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa" \
  -H "Authorization: Bearer $OSNODATA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
Resposta
{
  "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",
  "...": "..."
}
POST/v1/webhooks/{id}/rotate_secretwebhooks:write

Troca o segredo. O anterior deixa logo de assinar: actualiza o receptor antes.

Pedido
curl -X POST "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa/rotate_secret" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "id": "wh3Kd9sLq2Xa",
  "...": "...",
  "secret": "whsec_Xy7..."
}
DELETE/v1/webhooks/{id}webhooks:write

Apaga o webhook e o seu registo de entregas.

Pedido
curl -X DELETE "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
HTTP/1.1 204 No Content

Entregas 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-Event
items ou ping.
X-OSNOdata-Delivery
O id da entrega.
X-OSNOdata-Webhook
O id do webhook.
X-OSNOdata-Signature
t=<unix>,v1=<hex>, ver abaixo.
User-Agent
OSNOdata-Webhooks/1
POST https://exemplo.pt/osnodata
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"
    }
  ]
}
Qualquer resposta 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, com disabled_at e disabled_reason) e o dono da chave é avisado por email. Corrigido o receptor, reactiva-o com PATCH {"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.

GET/v1/webhooks/{id}/deliverieswebhooks:write

O 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_cursor da página anterior.
Pedido
curl "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa/deliveries?status=failed,retrying" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
}
POST/v1/webhooks/{id}/pingwebhooks:write

Envia 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.

Pedido
curl -X POST "https://api.osnodata.com/v1/webhooks/wh3Kd9sLq2Xa/ping" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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.

POST/v1/subscriptionswebhooks:write + items:read

Cria 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.
modestring
keyword, semantic ou hybrid.
min_similaritynumber
De 0,3 a 0,95, nos modos semânticos.
filtersobject
source, kind, language, country, blocks... (sem q).
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.
Pedido
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"}}'
Resposta (201)
{
  "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..."
}
GET/v1/subscriptionswebhooks:write + items:read

As subscrições desta chave; /v1/subscriptions/{id} dá uma.

Pedido
curl "https://api.osnodata.com/v1/subscriptions" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
    }
  ]
}
PATCH/v1/subscriptions/{id}webhooks:write + items:read

Altera query, mode, filters, url, batch_size ou enabled. enabled: true reactiva uma subscrição desactivada, com o que ficou por enviar.

Pedido
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"}'
Resposta
{
  "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",
  "...": "..."
}
POST/v1/subscriptions/{id}/rotate_secretwebhooks:write + items:read

Troca o segredo, por um novo ou pelo secret que mandares. O anterior deixa logo de assinar.

Pedido
curl -X POST "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/rotate_secret" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "id": "Sb4Tq8Lm2Wx0",
  "...": "...",
  "secret": "whsec_Xy7..."
}
DELETE/v1/subscriptions/{id}webhooks:write + items:read

Apaga a subscrição, as correspondências e o registo de entregas.

Pedido
curl -X DELETE "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
HTTP/1.1 204 No Content

Quando 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-Event
search.match ou ping.
X-OSNOdata-Delivery
O id da entrega, o mesmo nas repetições.
X-OSNOdata-Subscription
O id da subscrição.
X-OSNOdata-Signature
t=<unix>,v1=<hex>, como nos webhooks, assinado de novo em cada tentativa.
POST https://exemplo.pt/osnodata/mencoes
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"
    }
  ]
}
Verifica a assinatura, recusa um 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

GET/v1/subscriptions/{id}/deliverieswebhooks:write + items:read

O registo de entregas (30 dias), mais recentes primeiro, com status, limit e cursor como nos webhooks.

Pedido
curl "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/deliveries" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
}
GET/v1/subscriptions/{id}/matcheswebhooks:write + items:read

Os itens que corresponderam (90 dias), os repetidos também (duplicate), com a entrega que os levou.

Pedido
curl "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/matches" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
}
POST/v1/subscriptions/{id}/pingwebhooks:write + items:read

Envia já uma entrega ping assinada e responde como correu.

Pedido
curl -X POST "https://api.osnodata.com/v1/subscriptions/Sb4Tq8Lm2Wx0/ping" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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).

POST/v1/monitorsmonitors:write

Cria 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) ou all.
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).
Pedido
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"]}'
Resposta (201)
{
  "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"
}
GET/v1/monitors/{id}monitors:read

Um 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.

Pedido
curl "https://api.osnodata.com/v1/monitors/Reconquista" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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 que max_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 also com a razão a 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 com mention.updated, nunca um segundo mention.created. Uma menção que já existia e se descobre cópia de outra fica status: copy com copy_of_id e é enviada como mention.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 quote nem excerpt.
GET/v1/monitors/{id}/candidatesmonitors:read

O 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.

Pedido
curl "https://api.osnodata.com/v1/monitors/Reconquista/candidates?status=rejected,gated_out" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
}
POST/v1/monitors/{id}/rejudgemonitors:write

Volta a julgar os candidatos recusados desde since (no máximo 200); com dry_run diz só quantos e quanto custaria.

Pedido
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}'
Resposta
{
  "candidates": 41,
  "estimated_usd": 0.0172,
  "dry_run": true,
  "queued": 0
}

Menções

GET/v1/mentionsmonitors:read

As 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; em until, o fim desse dia) ou relativo: today, yesterday, -24h, -7d, -30m, -2w.
date_fieldstring
found (quando o OSNOdata a aceitou, por omissão) ou published.
tonestring
favourable, neutral, hostile, mixed (vírgulas).
kindstring
news, opinion, interview, video, social, blog, other.
mediumstring
press, 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).
collapsestring
group: uma linha por acontecimento, com os outros órgãos em group.
statusstring
active (por omissão), retracted, copy (as que eram menções e afinal são cópias de outra) ou all.
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).
Pedido
curl "https://api.osnodata.com/v1/mentions?monitor=Reconquista&since=yesterday&tone=hostile&collapse=group" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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
}
GET/v1/mentions/{id}monitors:read

Uma 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.

Pedido
curl "https://api.osnodata.com/v1/mentions/Me4Kp9Vb1Tz2?include=decisions" \
  -H "Authorization: Bearer $OSNODATA_KEY"
Resposta
{
  "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"
    }
  ]
}
POST/v1/mentions/{id}/feedbackmonitors:write

wrong 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.

Pedido
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"}'
Resposta
{
  "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"
}
POST/v1/mentions/{id}/clipmonitors:read + media:read

O 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.

Pedido
curl -X POST "https://api.osnodata.com/v1/mentions/Me4Kp9Vb1Tz2/clip" \
  -H "Authorization: Bearer $OSNODATA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output":"video"}'
Resposta (202)
{
  "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-Event
mentions ou ping.
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.
POST https://exemplo.pt/osnodata/mencoes
{
  "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": []
      }
    }
  ]
}
As falhas repetem-se como nos webhooks; à 8.ª as entregas param (o monitor continua a julgar e a guardar) e o dono é avisado. 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.

POST/inbound/{token}

Recebe o corpo (até 1 MB), verifica-o e transforma-o em itens da fonte do webhook.

Pedido
curl -X POST "https://api.osnodata.com/inbound/in_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Novo pedido","text":"Mensagem do formulário"}'
Resposta (202)
{
  "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-Signature por omissão) com o HMAC do corpo, SHA-256 ou SHA-1, em hex ou base64, com um prefixo opcional (sha256=).
github
X-Hub-Signature-256: sha256=<hex>, o HMAC-SHA256 do corpo.
slack
X-Slack-Signature: v0=<hex> de v0:<timestamp>:<corpo>, com X-Slack-Request-Timestamp; um timestamp com mais de 5 minutos é recusado.
stripe
Stripe-Signature: t=..,v1=.. sobre <t>.<corpo> (basta um dos v1), 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].url ou $.title dizem 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 (truncated diz se havia mais).
  • O mesmo URL, id externo ou conteúdo é o mesmo item: um envio repetido responde 200 com duplicates.

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.
Cada pedido fica no registo do webhook durante 30 dias, com o estado, o motivo, os cabeçalhos (sem segredos nem assinaturas) e os primeiros 8 KB do corpo. No painel, "Enviar exemplo" assina um pedido de exemplo como a verificação pede e passa-o pelo mesmo caminho.

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.
Um item redigido
{
  "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 em redacted_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}/media saem também os URLs dos ficheiros, a transcrição ou o resumo, conforme a política, e a resposta traz os mesmos restrictions e redacted_fields. Um clip de um item cuja média foi tirada vem com "withheld": true e sem url.
  • hide: sem o direito, o item não aparece em lado nenhum: na lista, em /v1/items/{id} (responde 404), 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.

Pedido
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.

As etiquetas descrevem o conteúdo e a política aplicada pelo OSNOdata; não dizem se um uso concreto dos dados é permitido. Essa avaliação fica com quem os usa.

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.

O pacote não está publicado no npm. Usa-se a partir de um clone do repositório, como dependência local, ou copiando o bundle gerado.
Instalar
# 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.js

O 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.

Usar
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.iterate percorre as páginas com o cursor; items.sync sincroniza por seq.
  • Os erros da API são OSNOdataError, com status, code, param, retryAfter e rateLimit.
  • webhooks.create devolve o secret uma única vez, tal como a API.
Receber um webhook
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 Code
claude mcp add --transport http osnodata https://api.osnodata.com/mcp \
  --header "Authorization: Bearer $OSNODATA_KEY"
Configuração JSON de um cliente
{
  "mcpServers": {
    "osnodata": {
      "type": "http",
      "url": "https://api.osnodata.com/mcp",
      "headers": { "Authorization": "Bearer osk_live_..." }
    }
  }
}
API de Mensagens da Anthropic (conector MCP)
"mcp_servers": [{
  "type": "url",
  "url": "https://api.osnodata.com/mcp",
  "name": "osnodata",
  "authorization_token": "osk_live_..."
}]
Não há OAuth: os clientes que só aceitam OAuth (os conectores personalizados do claude.ai) ainda não se ligam.

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), menos create_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.