API REST

A maioria dos monitores entrega um diff da página e deixa a interpretação com você. A BriefPanel resolve a página nos itens que se repetem nela — um anúncio, uma moeda, uma vaga, um plano — e registra cada mudança como uma atualização tipada: qual campo mudou, de quanto para quanto, e o quanto isso importa.

Esta API é o lado de leitura desse histórico. Todo endpoint é um GET, devolve JSON e pagina do mesmo jeito.

URL base

https://actions.briefpanel.com/v1

Autenticação

Envie uma chave pessoal de API como token Bearer:

Authorization: Bearer YOUR_BRIEFPANEL_API_KEY

Crie uma chave em Configurações → Conectar seu agente no app (https://app.briefpanel.com/connect-agent). As chaves começam com bp_mcp_ e a mesma chave vale para o servidor MCP — uma credencial para as duas superfícies.

Tokens de acesso OAuth (bp_oat_) não são aceitos aqui. Eles são vinculados ao público (audience) do recurso MCP, então autenticam apenas chamadas MCP.

Uma chave ausente ou inválida devolve 401 com o cabeçalho WWW-Authenticate.

Início rápido

Liste o que você monitora. Se vierem linhas, sua chave está funcionando:

curl https://actions.briefpanel.com/v1/sources \
  -H "Authorization: Bearer YOUR_BRIEFPANEL_API_KEY"

Depois leia o que mudou. É este o endpoint que a maioria das integrações consulta:

curl "https://actions.briefpanel.com/v1/updates?importance=material&limit=50" \
  -H "Authorization: Bearer YOUR_BRIEFPANEL_API_KEY"

Uma resposta reduzida — o formato completo está no documento OpenAPI:

{
  "data": [
    {
      "id": "j57e...",
      "at": 1750000000000,
      "updateType": "modified",
      "importance": "material",
      "field": "price",
      "valueChange": {
        "type": "number",
        "previous": 149.9,
        "current": 129.9,
        "unit": "BRL"
      },
      "entry": { "id": "k17c...", "title": "Plano Pro", "kind": "pricing plan" },
      "source": { "id": "m92a...", "url": "https://example.com/pricing" }
    }
  ],
  "pagination": { "nextCursor": "eyJ...", "hasMore": true }
}

Endpoints

Um id que pertence a outra conta devolve 404, não 403 — a API não confirma a existência de um id que ela não vai servir.

Paginação

Toda coleção aceita limit e cursor e responde com um objeto pagination:

{ "pagination": { "nextCursor": "eyJ...", "hasMore": true } }

Passe nextCursor de volta como cursor para pegar a próxima página, e siga até hasMore ser false.

Trate hasMore como o único sinal de fim da coleção. Uma página pode voltar vazia, ou menor que o seu limit, e ainda haver mais para ler — parar em uma página curta trunca sua sincronização em silêncio.

Consultando o feed

GET /v1/updates vem das mudanças mais recentes para as mais antigas. Leia o at do item mais novo e devolva esse valor como since na próxima consulta para receber só o que mudou desde então:

curl "https://actions.briefpanel.com/v1/updates?since=1750000000000" \
  -H "Authorization: Bearer YOUR_BRIEFPANEL_API_KEY"

since aceita milissegundos desde a época (o formato que at devolve) ou um instante ISO-8601. importance aceita critical, material ou minor.

Cada item carrega o entry e o source de origem embutidos, então uma atualização já é acionável sem uma segunda chamada.

Tipos de item

Cada item carrega um kind — pricing plan, job posting, cryptocurrency. Os nomes são aprendidos por fonte, então compare apenas dentro de uma mesma fonte; o vocabulário de cada página é publicado como entryKinds na fonte, junto com hasPrice para você saber quando a ausência de um preço é significativa.

entryKinds só aparece depois que a fonte foi analisada.

Saúde da fonte

GET /v1/sources devolve um status derivado:

lastFetchOutcome, lastFetchErrorReason, consecutiveFetchFailures e nextFetchTime trazem o detalhe por trás disso.

Evidência

GET /v1/changes/{id}/snapshot serve o estado bruto da página de onde a mudança veio, para você mostrar a origem de um valor em vez de pedir que confiem nele.

Snapshots são deduplicados entre contas e não têm dono próprio, então são endereçados pela mudança a que pertencem, e não por um id próprio. Pegue o changeId de um cartão da linha do tempo e verifique hasCurrentSnapshot / hasPreviousSnapshot antes de pedir um estado.

• state — current (padrão) ou previous. previous devolve 404 na primeira mudança, que não tem estado anterior.
• format — markdown (padrão), html ou screenshot. screenshot responde com um 302 para uma URL de imagem assinada e de vida curta.

Erros

Falhas devolvem um objeto de erro:

{ "error": { "code": "not_found", "message": "No source with that id." } }

Trate pelo code em vez do status HTTP — os códigos são um conjunto fixo e não mudam sob você.

Limites de uso

As leituras são limitadas por chave de API, em uma janela fixa de 300 requisições por minuto. Acima do limite você recebe 429 com o cabeçalho Retry-After em segundos — respeite-o em vez de tentar de novo imediatamente.

OpenAPI

A especificação completa é servida como documento OpenAPI 3.0 vivo:

https://actions.briefpanel.com/v1/openapi.json

Importe no Postman, aponte um gerador de SDK para ela ou entregue a URL para um agente. Ela descreve cada endpoint, o esquema de autenticação, o contrato de paginação e todos os formatos de resposta.

É servida sem autenticação de propósito — uma ferramenta precisa conseguir ler a descrição da API antes de ter uma chave.