Skip to main content
Tudo na API é um de poucos recursos. Entender como se relacionam deixa a referência fácil de navegar.

​
Items

Um item é uma fonte monitorada. O type é youtube_channel, youtube_video, twitter ou rss. Você cria a partir de uma URL ou handle:
Um item youtube_channel contém vídeos (veja Monitorar uma fonte). Items são a unidade atômica — coleções os agrupam, reporters os processam, transcripts e documents são produzidos a partir deles.

​
Coleções

Uma coleção agrupa items. Tem visibility (private | public) e flags expose_* que controlam quais seções não-donos veem quando é pública. Uma coleção também pode ser paga (price_coins > 0) — fãs assinam pra liberar o conteúdo. Veja Coleções e Coleções pagas.

​
Reporters, workflows, steps

Um reporter é um agente. Ele tem um ou mais workflows; um workflow é uma lista ordenada de steps, cada um um tool_id mais um prompt inline e params. Um workflow tem um target_kind (youtube_video, youtube_channel ou collection) que decide contra o quê você roda.
Rodar um workflow sobre uma fonte produz documents (ex.: resumos). Veja Montar um reporter.

​
Schedules

Um schedule pertence a um reporter e roda um dos workflows dele numa cadência (interval_hours) sobre um conjunto de collection_ids. Vídeos novos nessas coleções são processados automaticamente. Veja Agendar execuções.

​
Executions

Qualquer execução — um transcript, um workflow manual, uma rodada agendada — cria uma execution com status (pending → running → done | error). Os endpoints de escrita retornam 202 com a execution; você acompanha até concluir. Isso é central o bastante pra ter página própria: Operações assíncronas.

​
Transcripts & documents

  • Transcripts — texto de um vídeo, um por idioma. Gerados de forma assíncrona (chama um transcriber externo); leia com GET /v1/items/{id}/transcript.
  • Documents — saída de workflow (resumos, análises). Liste com GET /v1/documents, filtre por item_id, reporter_id, kind.

​
Search, discover, events

  • Search — busca semântica nos seus transcripts e documents (GET /v1/search?q=…).
  • Discover — o catálogo público (/v1/discover/*): coleções, reporters e perfis de usuário públicos.
  • Events — seu feed de atividade (GET /v1/events), também transmitido pelo WebSocket de realtime.

​
Convenções

Leia uma vez — valem pra API inteira.

​
Erros

Respostas não-2xx têm um único shape:
Falha de rede (o request nem chegou ao servidor) é sinalizada pelos clientes como status 0 — distinto de qualquer erro HTTP.

​
Paginação

Endpoints de lista aceitam limit e offset na query (ex.: GET /v1/items?limit=50&offset=100). Defaults e tetos variam por rota — veja a referência.

​
IDs e idioma

IDs de recurso são strings opacas (UUIDs). Onde há conteúdo multilíngue, language é pt ou en; muitos endpoints de lista aceitam ?lang= pra filtrar.