Monitores

Um monitor é uma consulta salva sobre um endpoint da Croma que a Croma avalia com uma frequência e envia por e-mail para até três endereços. Você descreve o que acompanhar do mesmo jeito que consultaria o endpoint; a Croma mantém o agendamento, lembra o que já reportou e envia só o que apareceu desde a última execução.

Monitores fazem parte da API. Crie-os com POST /monitors, pedindo ao Claude ou a qualquer cliente MCP (Monitores pelo Claude) ou pelo console em platform.usecroma.com/monitors, onde você descreve o monitor com suas palavras ou preenche um formulário. Os três administram os mesmos monitores.

Quais endpoints podem ser monitorados?

Todo endpoint de dados, não importa como seja servido: a lista está em Fontes monitoráveis, com o que cada um acompanha, o que cada execução reporta e de quanto em quanto tempo é verificado. GET /catalog marca os mesmos endpoints com monitorable: true. Só ficam de fora as ferramentas de busca na web, extração, geração e pesquisa, os endpoints em lote e as versões aposentadas. Uma fonte nova pode ser monitorada no dia em que entra no ar. O que uma execução reporta depende do endpoint:

Uma busca (pagina seus resultados) reporta os resultados que antes não estavam lá.
A consulta de um registro (um processo por radicado, uma empresa por NIT, um veículo por placa, os antecedentes de uma pessoa) reporta o que mudou nesse registro. Veja Acompanhar um registro.

E quando roda depende de como é servido, que é o que diz o served_from:

served_from: "dataset": a Croma atualiza estes com uma frequência própria, então um monitor pode seguir essa atualização (cadence: "source") e cada execução gasta um crédito.
served_from: "live": consultam a fonte na hora, então o monitor roda pelo relógio, daily ou weekly, e cada execução gasta os créditos de uma consulta ao vivo.

Criar um

curl -X POST https://api.croma.run/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato AD9-111",
    "endpoint": "/co/anm/notices-search/v1",
    "query": { "title_number": "AD9-111" },
    "schedule": { "cadence": "source" },
    "recipients": ["legal@example.com"],
    "notify": "always",
    "language": "es"
  }'

Campo	Significado
`endpoint`	O endpoint a acompanhar, por caminho, id de catálogo ou nome de ferramenta MCP (`anm_notices_search`).
`query`	O corpo que o monitor envia em cada execução, validado exatamente como uma requisição direta. `page` e `per_page` não são permitidos.
`schedule`	Quando roda. Veja abaixo. Padrão `{ "cadence": "source" }`.
`recipients`	De um a três e-mails.
`notify`	`always` (padrão) envia um e-mail a cada execução, mesmo sem novidades; `on_new` só quando há algo a reportar.
`language`	`es` (padrão) ou `en`, para os e-mails.
`relevance`	Opcional. Uma instrução em linguagem natural que filtra os resultados novos antes do envio. Veja abaixo.

A resposta é o monitor com seu agendamento compilado:

{
  "data": {
    "id": "mon_5f1c2c0a-9d1e-4a3b-8c7d-1e2f3a4b5c6d",
    "name": "Contrato AD9-111",
    "endpoint": { "id": "anm-notices-search", "path": "/co/anm/notices-search/v1", "source": "ANM", "name": "Notices Search" },
    "query": { "title_number": "AD9-111" },
    "relevance": null,
    "schedule": { "cadence": "source", "timezone": "America/Bogota", "cron": "30 7 * * *", "next_run_at": "2026-09-22T12:30:00.000Z" },
    "recipients": ["legal@example.com"],
    "notify": "always",
    "language": "es",
    "status": "active",
    "created_at": "2026-09-21T15:04:05.000Z",
    "updated_at": "2026-09-21T15:04:05.000Z",
    "last_run": null
  }
}

A primeira execução

Logo após a criação, o monitor roda uma vez para registrar o que já coincide hoje (até 500 linhas, ou o registro como está) e envia um e-mail de boas-vindas com essa contagem e a próxima execução. Daí em diante, cada execução reporta apenas o que nunca foi visto.

Acompanhar um registro

Um monitor sobre a consulta de um registro lê o registro inteiro a cada execução e o compara com a leitura anterior. Uma execução pode trazer duas coisas:

O registro mudou. A coincidência traz changes: cada valor diferente, pelo seu caminho no registro, com o que era e o que é agora.
Uma lista do registro cresceu. Cada item novo (uma nova movimentação num processo, uma nova multa numa placa, um novo filing de uma empresa) é uma coincidência própria, reportada como um resultado novo de uma busca.

{
  "record_key": "record@8d0c1e5a-…",
  "record": { "found": true, "registration_number": "05001310300120240012300", "primary_case": { "court": "Juzgado 2 Civil del Circuito de Medellín" } },
  "changes": [
    { "path": "primary_case.court", "before": "Juzgado 1 Civil del Circuito de Medellín", "after": "Juzgado 2 Civil del Circuito de Medellín" }
  ]
}

Os valores que mudam a cada leitura sem que o registro mude (a hora da consulta, um certificado emitido para essa consulta) ficam de fora da comparação, então um monitor nunca reporta um horário novo como novidade.

Frequências

`cadence`	Roda
`source`	Logo depois que a atualização do próprio endpoint termina. Em uma fonte diária, uma vez por dia, assim que os dados novos chegam. Só endpoints servidos de dataset.
`hourly`	A cada hora cheia.
`daily`	Todo dia às `at` (HH:MM, padrão 08:00) em `timezone` (padrão a da fonte).
`weekly`	Toda `weekday` (padrão monday) às `at`.

Um monitor nunca pode verificar uma fonte com mais frequência do que ela se atualiza: um dataset daily recusa hourly com schedule_faster_than_source. Um endpoint served_from: "live" não tem atualização própria a seguir, então aceita daily ou weekly e recusa cadence: "source" com invalid_param. Quando uma execução source precisa seguir sem a atualização do dia (a fonte não publicou), a execução e seu e-mail dizem isso: source_stale é true e o e-mail diz “a fonte não publicou dados novos desde…”, nunca um simples “sem novidades”.

O filtro de relevância

Com relevance, cada linha nova é avaliada contra a sua instrução antes do envio. As linhas descartadas nunca se perdem: ficam no monitor com relevant: false e o e-mail diz quantas ficaram de fora. Se o filtro não estiver disponível, as linhas são enviadas marcadas como não revisadas em vez de descartadas.

{ "relevance": "solo avisos sobre suspensión o caducidad del título" }

GET /monitors/{id}/matches?relevant=false lista o que foi descartado, com o motivo de cada linha.

Administrar

Chamada	O que faz
`GET /monitors`	Seus monitores, com a última execução de cada um.
`GET /monitors/{id}`	Um monitor.
`PATCH /monitors/{id}`	Altera tudo menos o endpoint. `{ "status": "paused" }` pausa, `{ "status": "active" }` retoma.
`POST /monitors/{id}/run`	Roda agora, fora do agendamento.
`GET /monitors/{id}/runs`	Cada execução: quando, o que encontrou, se o e-mail saiu.
`GET /monitors/{id}/matches`	Cada linha reportada, com o veredito de relevância.
`DELETE /monitors/{id}`	Remove o monitor, seu agendamento, execuções e resultados.

Todo e-mail traz um link para parar de recebê-lo. Um monitor que fica sem destinatários é pausado.

Créditos e limites

Cada execução gasta os mesmos créditos que uma requisição ao endpoint: um em uma busca servida de dataset, a tarifa ao vivo em uma que consulta a fonte. Criar e administrar monitores é grátis. Quando a organização fica sem créditos, a execução é registrada como skipped_plan_limit, os destinatários são avisados uma vez por dia e o agendamento se mantém. Uma organização pode ter até 20 monitores, cada um com até 3 destinatários. Uma execução reporta até 500 linhas novas; além disso fica marcada como truncated.

Primeiros passos

Tipos de solicitação

Países

Monitores

Quais endpoints podem ser monitorados?

Criar um

A primeira execução

Acompanhar um registro

Frequências

O filtro de relevância

Administrar

Créditos e limites

​Quais endpoints podem ser monitorados?

​Criar um

​A primeira execução

​Acompanhar um registro

​Frequências

​O filtro de relevância

​Administrar

​Créditos e limites

Quais endpoints podem ser monitorados?

Criar um

A primeira execução

Acompanhar um registro

Frequências

O filtro de relevância

Administrar

Créditos e limites