{ "openapi": "3.1.0", "info": { "title": "API pública do Fôlego", "version": "1.0.0", "description": "API anônima e somente de leitura para clientes e agentes. Não é preciso API key.\n\nEscolhendo o endpoint: responder à pergunta de alguém dentro de um agente de IA -> leia /api/v1/agent, que lista endereços em Markdown feitos para agentes. Mostrar itens recentes ou de hoje -> /api/v1/items. Mostrar o que está em alta agora -> /api/v1/hot-topics. Mostrar o briefing diário -> /api/v1/dailies/latest; os briefings semanal e mensal -> /api/v1/weeklies/latest e /api/v1/monthlies/latest. Manter uma cópia local completa da seleção -> /api/v1/selected/snapshot uma vez, depois /api/v1/selected/changes para sempre.\n\nFrequência de consulta: use o s-maxage do Cache-Control de cada resposta como intervalo mínimo e sempre envie If-None-Match: um recurso que não mudou responde 304 com corpo vazio. Em 429 ou 503, respeite o Retry-After. Não há canal de push (nem SSE, webhooks ou streaming): consulte em intervalos.\n\nMantenha as respostas pequenas: envie Accept-Encoding: gzip ou br (curl --compressed). Para acompanhar itens novos, volte páginas só até encontrar um id que você já tem, em vez de reler a janela inteira de 7 dias a cada consulta; para guardar todos os itens selecionados, leia /api/v1/selected/snapshot uma vez e depois apenas /api/v1/selected/changes.\n\nDatas, semanas e meses dos briefings identificam edições fixas, mas correções e citações retiradas podem mudar seu conteúdo público. Revalide as cópias guardadas com If-None-Match depois que o Cache-Control expirar; não trate um briefing datado como imutável.\n\nTítulos e resumos são gerados a partir de fontes de terceiros; o original está sempre em links.original.", "termsOfService": "https://ofolego.com/terms" }, "servers": [ { "url": "https://ofolego.com" } ], "externalDocs": { "description": "Documento OpenAPI legível por máquina", "url": "https://ofolego.com/openapi-v1.json" }, "paths": { "/api/v1/items": { "get": { "operationId": "items", "summary": "Listar itens públicos recentes de IA em medicina", "description": "Comece por aqui para feeds, widgets e telas de \"o que há de novo\". Cobre apenas os últimos 7 dias. Envie If-None-Match e receba 304 com corpo vazio sempre que nada mudou. Para acompanhar itens novos, volte páginas com cursor só até encontrar um id que você já tem. Não use este endpoint para manter uma cópia local completa da seleção: ele tem janela, então tudo o que tiver mais de 7 dias sai sem aviso. Para isso, use /api/v1/selected/snapshot mais /api/v1/selected/changes.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "selected", "all" ], "default": "selected" } }, { "name": "category", "in": "query", "schema": { "type": "string", "examples": [ "evidence", "guidelines", "technique", "cases", "reviews", "opinion", "industry" ], "description": "Valores atuais: evidence, guidelines, technique, cases, reviews, opinion, industry." } }, { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d" ], "default": "7d" } }, { "name": "by", "in": "query", "schema": { "type": "string", "enum": [ "timeline", "published" ], "default": "timeline" }, "description": "Qual horário define a janela e a ordenação. 'timeline' (padrão) segue a linha do tempo publicada no site: itens históricos ou importados depois podem manter o horário de publicação da fonte, inclusive itens encontrados mais de 72h após a publicação; itens novos comuns usam o horário de descoberta, e os representantes selecionados seguem a primeira aparição do seu grupo de leitura. 'published' usa o horário de publicação da fonte e, quando ele é desconhecido, o de descoberta. publishedAt pode ser null quando o horário original é desconhecido; discoveredAt é o horário em que o site recebeu o item. Esses campos não servem como cursor nem como chave de ordenação no cliente; repasse o cursor retornado sem alterá-lo." }, { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "description": "Espaços no início e no fim são removidos antes da validação; o valor restante deve ter de 2 a 200 code points Unicode." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor opaco de paginação por chave, ligado à consulta, para a janela móvel. Não carrega horário de emissão e não expira com o tempo, mas a janela continua andando: quando a âncora do próprio cursor sai da janela pedida de 24h ou 7d, ele é rejeitado com invalid_cursor; nesse caso recomece a consulta pela primeira página em vez de guardar um cursor de um dia para o outro. Linhas mais antigas também podem sair naturalmente da janela entre uma chamada e outra. Para uma cópia exata, use selected snapshot + changes." } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/hot-topics": { "get": { "operationId": "hotTopics", "summary": "Listar os assuntos em alta, cobertos por várias fontes", "description": "O Top 10 atual do Fôlego, ordenado pela cobertura em várias fontes e pela repercussão. Cada item traz a posição (a partir de 1); os valores internos e exibidos de repercussão não são devolvidos. Usa o último ranking publicado com sucesso, normalmente atualizado a cada cinco minutos. Caches compartilhados usam janela de validade de 60s; não consulte mais rápido que o s-maxage e use If-None-Match. Se um item tiver links.story, trata-se de uma URL HTML para pessoas: extraia o último segmento do caminho (publicId) e chame /api/v1/stories/{publicId} para obter a linha do tempo em JSON. Nunca peça links.story como API. Quando ausente, não invente um id de evento.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotTopicsResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/stories/{publicId}": { "get": { "operationId": "storyByPublicId", "summary": "Obter um evento com a linha do tempo da cobertura e o panorama gerado por IA", "description": "Um evento = um fato do mundo real reunido a partir de todas as fontes que o cobriram: uma linha do tempo da cobertura em ordem cronológica inversa, um panorama gerado por IA reescrito aos poucos conforme o fato evolui (contradições com notícias anteriores são apontadas explicitamente) e links para eventos da mesma história e relacionados. Extraia os ids do último segmento do caminho da URL HTML em links.story dos assuntos em alta, ou use os ids das referências storyline/related de outro evento; nunca peça links.story como JSON. Eventos fundidos respondem com 308 para o id que permaneceu. Chame este endpoint apenas com um id realmente devolvido pela API; um 404 significa que a camada pública de eventos ou aquele evento não está disponível.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoryResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "308": { "description": "O evento foi fundido com outro; siga o Location até o id que permaneceu." }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/dailies": { "get": { "operationId": "dailies", "summary": "Listar o arquivo de briefings diários", "description": "Índice de datas dos briefings diários anteriores, do mais recente para o mais antigo. Os briefings saem uma vez por dia às 07:00 (horário de Brasília), então consultar mais do que algumas vezes por dia é trabalho desperdiçado.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 180, "default": 30 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailiesResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/dailies/latest": { "get": { "operationId": "latestDaily", "summary": "Obter o briefing diário mais recente", "description": "O briefing diário mais recente, publicado uma vez por dia às 07:00 (horário de Brasília). Um cliente que só quer o briefing diário deve acordar logo depois das 07:00 em vez de consultar o dia inteiro. Agentes ou ferramentas que guardam uma URL estável além dos cabeçalhos de cache HTTP devem primeiro pedir /api/v1/dailies?limit=1 e depois buscar /api/v1/dailies/{data-retornada}; nunca adivinhe uma data.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/dailies/{date}": { "get": { "operationId": "dailyByDate", "summary": "Obter um briefing diário pela data (horário de Brasília)", "description": "Um briefing diário anterior pela data no horário de Brasília (AAAA-MM-DD). Cada data identifica uma edição fixa, mas correções e citações retiradas podem mudar seu conteúdo público. Respeite o Cache-Control e revalide com If-None-Match antes de reutilizar uma cópia expirada; não guarde um briefing em cache indefinidamente.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/weeklies": { "get": { "operationId": "weeklies", "summary": "Listar os briefings semanais", "description": "Índice dos briefings semanais publicados, do mais recente para o mais antigo: semana ISO, seus dias de segunda a domingo, manchete e link no Fôlego. O semanal sai toda segunda-feira às 07:00 (horário de Brasília), montado a partir dos briefings diários daquela semana, então consultar mais de uma vez por dia é trabalho desperdiçado.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 60, "default": 12 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeekliesResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/weeklies/latest": { "get": { "operationId": "latestWeekly", "summary": "Obter o briefing semanal mais recente", "description": "O briefing semanal mais recente: manchete, panorama e os itens mais importantes da semana agrupados por seção, escolhidos entre os briefings diários daquela semana. Publicado toda segunda-feira às 07:00 (horário de Brasília); um cliente que quer o briefing semanal deve buscá-lo logo depois disso em vez de consultar o tempo todo. Agentes ou ferramentas que guardam uma URL estável além dos cabeçalhos de cache HTTP devem primeiro pedir /api/v1/weeklies?limit=1 e depois /api/v1/weeklies/{semana-retornada}; nunca adivinhe uma semana.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeeklyResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/weeklies/{week}": { "get": { "operationId": "weeklyByWeek", "summary": "Obter um briefing semanal pela semana ISO", "description": "Um briefing semanal pela semana ISO (AAAA-Wss, por exemplo 2026-W39). Correções e citações retiradas podem mudar o conteúdo público desta edição. Respeite o Cache-Control e revalide com If-None-Match antes de reutilizar uma cópia expirada; não guarde um briefing em cache indefinidamente.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "week", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-W\\d{2}$" }, "description": "Semana ISO, por exemplo 2026-W39." } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeeklyResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/monthlies": { "get": { "operationId": "monthlies", "summary": "Listar os briefings mensais", "description": "Índice dos briefings mensais publicados, do mais recente para o mais antigo: mês, primeiro e último dia, manchete e link no Fôlego. O mensal sai todo dia 1º às 07:30 (horário de Brasília), montado a partir dos briefings diários daquele mês.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 60, "default": 12 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthliesResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/monthlies/latest": { "get": { "operationId": "latestMonthly", "summary": "Obter o briefing mensal mais recente", "description": "O briefing mensal mais recente: manchete, panorama e os itens mais importantes do mês agrupados por seção, escolhidos entre os briefings diários daquele mês. Publicado todo dia 1º às 07:30 (horário de Brasília). Ferramentas que guardam uma URL estável devem primeiro pedir /api/v1/monthlies?limit=1 e depois /api/v1/monthlies/{mes-retornado}; nunca adivinhe um mês.", "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ] } }, "/api/v1/monthlies/{month}": { "get": { "operationId": "monthlyByMonth", "summary": "Obter um briefing mensal pelo mês", "description": "Um briefing mensal pelo mês do calendário (AAAA-MM, por exemplo 2026-09). Correções e citações retiradas podem mudar o conteúdo público desta edição. Respeite o Cache-Control e revalide com If-None-Match antes de reutilizar uma cópia expirada.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "month", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "description": "Mês do calendário, por exemplo 2026-09." } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyResponse" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/selected/snapshot": { "get": { "operationId": "selectedSnapshot", "summary": "Buscar o retrato atual da seleção, uma página por vez", "description": "Carga inicial, feita uma única vez, para clientes que mantêm uma cópia local completa da seleção. Não é um endpoint de navegação nem algo para consultar periodicamente: percorra as páginas uma vez com limit (padrão 500, máximo 1000) até hasMore ser false, guarde o cursor da PRIMEIRA página e depois mantenha-se atualizado com /api/v1/selected/changes. O conjunto completo chega a vários milhares de itens e só cresce; fields=minimal mantém a carga inicial pequena. Um widget que só mostra os destaques de hoje não precisa disso — use /api/v1/items.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "fields", "in": "query", "schema": { "type": "string", "enum": [ "default", "minimal" ], "default": "default" }, "description": "'minimal' remove o resumo e o link do original, reduzindo a resposta em cerca de 4 vezes. Prefira quando só precisa saber quais itens estão selecionados no momento. Nas páginas seguintes o valor fica travado pelo cursor da página, então uma cópia nunca termina metade no padrão e metade em minimal." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 } }, { "name": "page", "in": "query", "schema": { "type": "string" }, "description": "Cursor opaco de continuação vindo do nextPage da resposta anterior. Continue pedindo páginas enquanto hasMore for true; só depois da última página use o cursor em /api/v1/selected/changes. O cursor de sincronização é igual em todas as páginas e sempre se refere à marca d'água tirada na primeira página, então itens alterados durante a paginação são acertados na primeira chamada de changes." } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedSnapshot" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/selected/changes": { "get": { "operationId": "selectedChanges", "summary": "Buscar as mudanças atômicas da seleção", "description": "Inclusões, edições e remoções desde o seu cursor, para que uma cópia local continue correta sem baixar tudo de novo. Aplique a página e só depois salve o cursor retornado — nunca o contrário. O cursor é uma marca d'água do registro de mudanças, não uma sessão: não expira com o tempo, então um cliente pode ficar dias offline e retomar exatamente de onde parou. Ao receber 409 snapshot_required, refaça a carga inicial por /api/v1/selected/snapshot; essa resposta é o único sinal de que retomar deixou de ser seguro.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "cursor", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectedChanges" } } } }, "304": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/agent": { "get": { "operationId": "agentGuide", "summary": "Guia de uso para agentes de IA", "description": "Markdown que diz a um agente de IA qual endereço de /api/v1/agent responde a cada tipo de pergunta, como apresentar os resultados e quais são as regras de uso. Os agentes leem esses endereços e não precisam ser atualizados: novos recursos entram aqui como novos endereços.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/latest": { "get": { "operationId": "agentLatest", "summary": "Itens mais recentes, como resposta para agente", "description": "Os mesmos itens de /api/v1/items (na ordem da linha do tempo), formatados para um agente repassar: títulos com link para O Fôlego, fonte, horário de Brasília, resumo e \"Por que ler\". Por padrão, a seleção editorial das últimas 24 horas, 10 itens.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d" ], "default": "24h" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "selected", "all" ], "default": "selected" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "evidence", "guidelines", "technique", "cases", "reviews", "opinion", "industry" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/search": { "get": { "operationId": "agentSearch", "summary": "Busca, como resposta para agente", "description": "Busca primeiro na seleção editorial e, só quando não há resultado, em todos os itens públicos, informando qual dos dois usou. Por padrão, últimos 7 dias.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } }, { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d" ], "default": "7d" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "evidence", "guidelines", "technique", "cases", "reviews", "opinion", "industry" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/hot": { "get": { "operationId": "agentHot", "summary": "Os assuntos em alta agora, como resposta para agente", "description": "O Top 10 atual por posição, cada um com o endereço da resposta do seu evento. Sem valores de repercussão.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 } } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/stories/{publicId}": { "get": { "operationId": "agentStory", "summary": "A linha do tempo de um evento, como resposta para agente", "description": "Último desdobramento, panorama gerado por IA, notícias da mais recente para a mais antiga e eventos relacionados. Use apenas endereços fornecidos por /api/v1/agent/hot ou por outra resposta de evento.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/daily": { "get": { "operationId": "agentLatestDaily", "summary": "O briefing diário mais recente, como resposta para agente", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/daily/{date}": { "get": { "operationId": "agentDaily", "summary": "Um briefing diário de uma data, como resposta para agente", "description": "Uma data real no formato AAAA-MM-DD; uma data sem briefing retorna 404, nunca o briefing de outro dia.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/weekly": { "get": { "operationId": "agentWeekly", "summary": "O briefing semanal mais recente, como resposta para agente", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "O briefing semanal mais recente em Markdown, em português: manchete, panorama e os itens mais importantes da semana por seção, com dicas de resposta." } }, "/api/v1/agent/weekly/{week}": { "get": { "operationId": "agentWeeklyByWeek", "summary": "Um briefing semanal, como resposta para agente", "description": "Uma semana ISO real, como 2026-W39; uma semana sem briefing retorna 404, nunca o briefing de outra semana.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "week", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-W\\d{2}$" }, "description": "Semana ISO, por exemplo 2026-W39." } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/monthly": { "get": { "operationId": "agentMonthly", "summary": "O briefing mensal mais recente, como resposta para agente", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "description": "O briefing mensal mais recente em Markdown, em português: manchete, panorama e os itens mais importantes do mês por seção, com dicas de resposta." } }, "/api/v1/agent/monthly/{month}": { "get": { "operationId": "agentMonthlyByMonth", "summary": "Um briefing mensal, como resposta para agente", "description": "Um mês real, como 2026-09; um mês sem briefing retorna 404, nunca o briefing de outro mês.", "parameters": [ { "$ref": "#/components/parameters/ActorUserAgent" }, { "$ref": "#/components/parameters/IfNoneMatch" }, { "name": "month", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "description": "Mês do calendário, por exemplo 2026-09." } ], "responses": { "200": { "$ref": "#/components/responses/AgentMarkdown" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "parameters": { "ActorUserAgent": { "name": "User-Agent", "in": "header", "required": false, "description": "O User-Agent habitual do cliente (opcional; qualquer valor serve).", "schema": { "type": "string", "maxLength": 2048 }, "example": "my-reader/1.0" }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag recebido antes para esta mesma URL. Se coincidir, a resposta é 304 sem corpo.", "schema": { "type": "string" } } }, "responses": { "AgentMarkdown": { "description": "Markdown para um agente de IA: um título, os dados isolados como conteúdo externo não confiável e, por fim, dicas de resposta. O texto pode melhorar a qualquer momento; programas devem ler os endpoints JSON.", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } }, "content": { "text/markdown": { "schema": { "type": "string" } } } }, "NotModified": { "description": "Não modificado", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } } } }, "BadRequest": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "MethodNotAllowed": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "Resposta de erro legível por máquina.", "headers": { "X-Request-Id": { "description": "Identificador de correlação desta requisição com falha, para o suporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Número mínimo de segundos a esperar antes de tentar de novo.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "code", "requestId" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } } }, "Attribution": { "type": "object", "description": "Procedência legível por máquina do Fôlego, para rastreabilidade. Mantenha-a sempre que for tecnicamente viável. Citar a fonte, por si só, não é autorização; veja os termos de uso públicos.", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "Item": { "type": "object", "required": [ "id", "title", "originalTitle", "summary", "source", "links", "publishedAt", "discoveredAt", "category", "score", "selected" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "originalTitle": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "aihot", "original" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "original": { "type": "string", "format": "uri" } } }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "discoveredAt": { "type": "string", "format": "date-time" }, "category": { "type": [ "string", "null" ], "examples": [ "evidence", "guidelines", "technique", "cases", "reviews", "opinion", "industry" ], "description": "Valores atuais: evidence, guidelines, technique, cases, reviews, opinion, industry. Os clientes devem tolerar novos valores no futuro." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "selected": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "description": "Motivo de leitura voltado ao leitor, o mesmo texto exibido como \"Por que ler\" no site. Sempre presente em /api/v1/items; null quando o item não está selecionado ou não tem esse texto. O snapshot e o changes da seleção ainda não incluem este campo." }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "ItemMinimal": { "type": "object", "required": [ "id", "title", "source", "links", "publishedAt", "discoveredAt", "category", "score", "selected" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "discoveredAt": { "type": "string", "format": "date-time" }, "category": { "type": [ "string", "null" ], "examples": [ "evidence", "guidelines", "technique", "cases", "reviews", "opinion", "industry" ], "description": "Valores atuais: evidence, guidelines, technique, cases, reviews, opinion, industry. Os clientes devem tolerar novos valores no futuro." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "selected": { "type": "boolean" } } }, "Page": { "type": "object", "required": [ "count", "hasMore", "nextCursor" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Número de registros nesta página." }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaco; reutilize apenas com a mesma consulta." } } }, "ItemsResponse": { "type": "object", "required": [ "schemaVersion", "query", "items", "page" ], "properties": { "schemaVersion": { "const": 1 }, "query": { "type": "object", "required": [ "mode", "category", "window", "q", "by", "ordering" ], "properties": { "mode": { "type": "string", "enum": [ "selected", "all" ] }, "category": { "type": [ "string", "null" ], "examples": [ "evidence", "guidelines", "technique", "cases", "reviews", "opinion", "industry" ], "description": "Valores atuais: evidence, guidelines, technique, cases, reviews, opinion, industry. Os clientes devem tolerar novos valores no futuro." }, "window": { "type": "string", "enum": [ "24h", "7d" ] }, "q": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 200 }, "by": { "type": "string", "enum": [ "timeline", "published" ] }, "ordering": { "type": "string", "enum": [ "timelineDesc", "publishedAtDesc" ] } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "HotTopic": { "type": "object", "required": [ "rank", "id", "title", "source", "links", "sourceCount", "signalCount", "sourceNames", "latestAt" ], "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Posição (a partir de 1) no Top 10 atual do Fôlego." }, "id": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "aihot", "original" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "original": { "type": "string", "format": "uri" }, "story": { "type": "string", "format": "uri", "description": "URL HTML opcional, para pessoas. Extraia o último segmento do caminho (publicId) e chame /api/v1/stories/{publicId} para obter JSON; nunca peça esta URL como API. Quando ausente, não invente ids de evento." } } }, "sourceCount": { "type": "integer", "minimum": 0 }, "signalCount": { "type": "integer", "minimum": 0 }, "participantCount": { "type": "integer", "minimum": 0, "description": "Participantes distintos observados, somando fontes editoriais e de repercussão; não é uma estimativa de público em toda a internet." }, "sourceNames": { "type": "array", "items": { "type": "string" } }, "latestAt": { "type": "string", "format": "date-time" } } }, "HotTopicsResponse": { "type": "object", "required": [ "schemaVersion", "count", "items" ], "properties": { "schemaVersion": { "const": 1 }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/HotTopic" } } } }, "StoryReport": { "type": "object", "required": [ "id", "title", "summary", "source", "publishedAt", "links" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "source": { "type": "object", "required": [ "name", "firstParty" ], "properties": { "name": { "type": "string" }, "firstParty": { "type": "boolean" } } }, "publishedAt": { "type": "string", "format": "date-time", "description": "Quando o original foi publicado; se o original não tiver data de publicação confiável, quando foi coletado." }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "original": { "type": "string", "format": "uri" } } } } }, "StoryNeighbor": { "type": "object", "required": [ "publicId", "title", "relation", "links" ], "properties": { "publicId": { "type": "string" }, "title": { "type": "string" }, "relation": { "type": "string" }, "links": { "type": "object", "required": [ "aihot", "api" ], "properties": { "aihot": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" } } } } }, "Story": { "type": "object", "required": [ "publicId", "title", "status", "sourceCount", "reportCount", "firstReportAt", "latestAt", "latest", "digest", "digestUpdatedAt", "links", "reports", "storyline", "related" ], "properties": { "publicId": { "type": "string" }, "title": { "type": "string" }, "status": { "enum": [ "active", "settled" ] }, "sourceCount": { "type": "integer", "minimum": 0 }, "reportCount": { "type": "integer", "minimum": 0 }, "firstReportAt": { "type": "string", "format": "date-time" }, "latestAt": { "type": "string", "format": "date-time" }, "latest": { "type": "string" }, "digest": { "type": [ "string", "null" ] }, "digestUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/StoryReport" } }, "storyline": { "type": "array", "items": { "$ref": "#/components/schemas/StoryNeighbor" } }, "related": { "type": "array", "items": { "$ref": "#/components/schemas/StoryNeighbor" } } } }, "StoryResponse": { "type": "object", "required": [ "schemaVersion", "story" ], "properties": { "schemaVersion": { "const": 1 }, "story": { "$ref": "#/components/schemas/Story" } } }, "DailiesResponse": { "type": "object", "required": [ "schemaVersion", "count", "items" ], "properties": { "schemaVersion": { "const": 1 }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DailyEntry" } } } }, "DailyEntry": { "type": "object", "required": [ "date", "generatedAt", "leadTitle", "leadParagraph", "links" ], "properties": { "date": { "type": "string", "format": "date" }, "generatedAt": { "type": "string", "format": "date-time" }, "leadTitle": { "type": [ "string", "null" ] }, "leadParagraph": { "type": [ "string", "null" ] }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "DailyContentLinks": { "type": "object", "required": [ "aihot", "original" ], "properties": { "aihot": { "type": [ "string", "null" ], "format": "uri" }, "original": { "type": "string", "format": "uri" } } }, "DailyReport": { "type": "object", "required": [ "date", "generatedAt", "windowStart", "windowEnd", "links", "lead", "sections", "flashes" ], "properties": { "date": { "type": "string", "format": "date" }, "generatedAt": { "type": "string", "format": "date-time" }, "windowStart": { "type": "string", "format": "date-time" }, "windowEnd": { "type": "string", "format": "date-time" }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "lead": { "anyOf": [ { "type": "object", "required": [ "title", "leadParagraph" ], "properties": { "title": { "type": "string" }, "leadParagraph": { "type": "string" } } }, { "type": "null" } ] }, "sections": { "type": "array", "items": { "type": "object", "required": [ "label", "items" ], "properties": { "label": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "title", "summary", "source", "links" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "$ref": "#/components/schemas/DailyContentLinks" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } } }, "flashes": { "type": "array", "items": { "type": "object", "required": [ "title", "source", "links", "publishedAt" ], "properties": { "title": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "$ref": "#/components/schemas/DailyContentLinks" }, "publishedAt": { "type": "string", "format": "date-time", "description": "Quando o original foi publicado; se o original não tiver data de publicação confiável, quando foi coletado." }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } }, "DailyResponse": { "type": "object", "required": [ "schemaVersion", "report" ], "properties": { "schemaVersion": { "const": 1 }, "report": { "$ref": "#/components/schemas/DailyReport" } } }, "SelectedSnapshot": { "type": "object", "required": [ "schemaVersion", "asOf", "fields", "cursor", "count", "hasMore", "nextPage", "items" ], "properties": { "schemaVersion": { "const": 1 }, "asOf": { "type": "string", "format": "date-time" }, "fields": { "type": "string", "enum": [ "default", "minimal" ] }, "cursor": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "nextPage": { "type": [ "string", "null" ] }, "items": { "type": "array" } }, "oneOf": [ { "properties": { "fields": { "const": "default" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } }, { "properties": { "fields": { "const": "minimal" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ItemMinimal" } } } } ] }, "SelectedRemove": { "type": "object", "required": [ "op", "changedAt", "id" ], "properties": { "op": { "const": "remove" }, "changedAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" } } }, "SelectedUpsert": { "type": "object", "required": [ "op", "changedAt", "item" ], "properties": { "op": { "const": "upsert" }, "changedAt": { "type": "string", "format": "date-time" }, "item": { "$ref": "#/components/schemas/Item" } } }, "SelectedUpsertMinimal": { "type": "object", "required": [ "op", "changedAt", "item" ], "properties": { "op": { "const": "upsert" }, "changedAt": { "type": "string", "format": "date-time" }, "item": { "$ref": "#/components/schemas/ItemMinimal" } } }, "SelectedChanges": { "type": "object", "required": [ "schemaVersion", "fields", "cursor", "count", "hasMore", "changes" ], "properties": { "schemaVersion": { "const": 1 }, "fields": { "type": "string", "enum": [ "default", "minimal" ] }, "cursor": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "changes": { "type": "array" } }, "oneOf": [ { "properties": { "fields": { "const": "default" }, "changes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SelectedUpsert" }, { "$ref": "#/components/schemas/SelectedRemove" } ] } } } }, { "properties": { "fields": { "const": "minimal" }, "changes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SelectedUpsertMinimal" }, { "$ref": "#/components/schemas/SelectedRemove" } ] } } } } ] }, "PeriodEntry": { "type": "object", "required": [ "periodStart", "periodEnd", "generatedAt", "headline", "links" ], "properties": { "periodStart": { "type": [ "string", "null" ], "format": "date", "description": "Primeiro dia do calendário coberto pela edição (horário de Brasília)." }, "periodEnd": { "type": [ "string", "null" ], "format": "date", "description": "Último dia do calendário coberto pela edição (horário de Brasília)." }, "generatedAt": { "type": "string", "format": "date-time" }, "headline": { "type": [ "string", "null" ], "description": "A manchete da edição: o título do item mais importante ou, se ele for retirado, o do próximo ainda público (edições antigas podem ter manchete própria)." }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "WeeklyEntry": { "allOf": [ { "$ref": "#/components/schemas/PeriodEntry" }, { "type": "object", "required": [ "week" ], "properties": { "week": { "type": "string", "pattern": "^\\d{4}-W\\d{2}$", "description": "Semana ISO, por exemplo 2026-W39." } } } ] }, "MonthlyEntry": { "allOf": [ { "$ref": "#/components/schemas/PeriodEntry" }, { "type": "object", "required": [ "month" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Mês do calendário, por exemplo 2026-09." } } } ] }, "WeekliesResponse": { "type": "object", "required": [ "schemaVersion", "count", "items" ], "properties": { "schemaVersion": { "const": 1 }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WeeklyEntry" } } } }, "MonthliesResponse": { "type": "object", "required": [ "schemaVersion", "count", "items" ], "properties": { "schemaVersion": { "const": 1 }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyEntry" } } } }, "PeriodReport": { "type": "object", "required": [ "periodStart", "periodEnd", "generatedAt", "windowStart", "windowEnd", "links", "headline", "overview", "sections" ], "properties": { "periodStart": { "type": [ "string", "null" ], "format": "date" }, "periodEnd": { "type": [ "string", "null" ], "format": "date" }, "generatedAt": { "type": "string", "format": "date-time" }, "windowStart": { "type": "string", "format": "date-time", "description": "Início das janelas dos briefings diários usados para montar a edição." }, "windowEnd": { "type": "string", "format": "date-time" }, "links": { "type": "object", "required": [ "aihot" ], "properties": { "aihot": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "headline": { "type": [ "string", "null" ], "description": "O título do item mais importante ou, se ele for retirado, o do próximo ainda público (edições antigas podem ter manchete própria)." }, "overview": { "type": [ "string", "null" ], "description": "Um panorama curto dos principais temas do período, escrito apenas a partir dos itens listados." }, "sections": { "type": "array", "description": "Seções na ordem de leitura, cada uma com seus itens em ordem de importância. Itens retirados ficam de fora.", "items": { "type": "object", "required": [ "label", "summary", "items" ], "properties": { "label": { "type": "string" }, "summary": { "type": [ "string", "null" ], "description": "Uma ou duas frases de introdução da seção, quando houver." }, "items": { "type": "array", "items": { "type": "object", "required": [ "title", "summary", "source", "links", "publishedAt" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "source": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "links": { "$ref": "#/components/schemas/DailyContentLinks" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } } } } } } } }, "WeeklyReport": { "allOf": [ { "$ref": "#/components/schemas/PeriodReport" }, { "type": "object", "required": [ "week" ], "properties": { "week": { "type": "string", "pattern": "^\\d{4}-W\\d{2}$" } } } ] }, "MonthlyReport": { "allOf": [ { "$ref": "#/components/schemas/PeriodReport" }, { "type": "object", "required": [ "month" ], "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } } } ] }, "WeeklyResponse": { "type": "object", "required": [ "schemaVersion", "report" ], "properties": { "schemaVersion": { "const": 1 }, "report": { "$ref": "#/components/schemas/WeeklyReport" } } }, "MonthlyResponse": { "type": "object", "required": [ "schemaVersion", "report" ], "properties": { "schemaVersion": { "const": 1 }, "report": { "$ref": "#/components/schemas/MonthlyReport" } } } } } }