API de uptime e ferramentas MCP do CoreDash: monitores e checks

Monitores de uptime via CoreDash API

Consulte e altere os monitores de uptime dos seus projetos CoreDash via REST, com a chave de API que já usa para os dados de RUM. Um agente de IA lê-os via MCP.

curl https://app.coredash.app/api/uptime/monitors \
  -H "Authorization: Bearer cdk_your_key"

Chaves de API para monitores de uptime

Os endpoints de uptime aceitam as chaves da CoreDash API e da Agency API.

Crie uma chave de projeto na página Connect Your AI, na barra lateral do projeto: dê-lhe um nome e clique em Generate API key. As mesmas chaves estão nas definições do projeto em API Keys (MCP). Apenas os proprietários do projeto as podem criar. A chave master é obtida na página Agency API da barra lateral, em contas de agência. Quando um projeto expirar, a respetiva chave de projeto recebe 401 em todas as chamadas.

Um convidado num projeto lê os respetivos monitores. Adicionar, alterar, mover e eliminar exige um projeto que seja seu.

O token OAuth de uma ligação de IA como o Claude (mcp_at_) apenas lê. POST, PATCH e DELETE com este token recebem 403.

Endpoints de uptime

O IP de origem e os valores dos headers são dados confidenciais. São devolvidos por POST, PATCH e GET /api/uptime/monitors/:id. A listagem e as ferramentas MCP omitem o origin_ip e mostram o valor de cada header como ••••.

O objeto monitor

Os campos summary e rum

Tanto a listagem como o monitor individual incluem um summary: rounds_7d e down_rounds_7d contabilizam as rondas dos últimos 7 dias, uptime_7d é a percentagem dessas rondas sem verificações em estado down e recent guarda as últimas 48 rondas, da mais antiga para a mais recente, cada uma com o pior resultado dessa ronda. Um monitor sem checks nos últimos 7 dias tem summary: null.

O monitor individual inclui também rum: o TTFB a p75 dos visitantes reais nos últimos 7 dias, a partir dos dados de RUM do projeto, para comparar com o ttfb_ms da verificação. Fica a null enquanto o projeto não tiver dados de RUM.

GET /api/uptime/monitors/:id

curl "https://app.coredash.app/api/uptime/monitors/6ad68c7a844fad80b752fd16?limit=2" \
  -H "Authorization: Bearer cdk_your_key"

{
  "monitor": {
    "id": "6ad68c7a844fad80b752fd16",
    "name": "Checkout",
    "url": "https://www.example.com/checkout/",
    "project_id": "655f1f77bcf86cd799439011",
    "paused": false,
    "expect_status": 200,
    "origin_check": true,
    "origin_ip": "203.0.113.10",
    "headers": [{ "name": "X-Staging-Auth", "value": "k7Qp2vX9mR4tL8wZ" }],
    "state": "up",
    "last_check_at": "2026-10-20T08:00:09.000Z",
    "last_up_at": "2026-10-20T08:00:09.000Z",
    "down_since": null,
    "last_down": { "from": "2026-10-18T19:00:11.000Z", "to": "2026-10-18T20:00:10.000Z" },
    "check_requested_at": null,
    "last": {
      "edge": { "at": "2026-10-20T08:00:09.000Z", "server": "scan1", "mode": "edge", "outcome": "up", "status": 200, "ttfb_ms": 212, "total_ms": 388, "connect_ms": 14, "redirects": 0, "final_url": "https://www.example.com/checkout/", "error": null, "error_text": null, "cloudflare": true, "cache_status": "DYNAMIC" },
      "origin": { "at": "2026-10-20T08:00:09.000Z", "server": "scan1", "mode": "origin", "outcome": "up", "status": 200, "ttfb_ms": 640, "total_ms": 702, "connect_ms": 9, "redirects": 0, "final_url": "https://www.example.com/checkout/", "error": null, "error_text": null, "cloudflare": false, "cache_status": null },
      "origin_is_cdn": false
    },
    "cert_expires": "2027-01-02T23:59:59.000Z",
    "created_at": "2026-10-06T09:12:41.000Z"
  },
  "summary": {
    "rounds_7d": 336,
    "down_rounds_7d": 2,
    "uptime_7d": 99.4,
    "recent": [
      { "at": "2026-10-20T07:30:10.000Z", "outcome": "up" },
      { "at": "2026-10-20T08:00:09.000Z", "outcome": "up" }
    ]
  },
  "checks": [
    { "at": "2026-10-20T08:00:09.000Z", "server": "scan1", "mode": "edge", "outcome": "up", "status": 200, "ttfb_ms": 212, "total_ms": 388, "connect_ms": 14, "redirects": 0, "final_url": "https://www.example.com/checkout/", "error": null, "error_text": null, "cloudflare": true, "cache_status": "DYNAMIC" },
    { "at": "2026-10-20T08:00:09.000Z", "server": "scan1", "mode": "origin", "outcome": "up", "status": 200, "ttfb_ms": 640, "total_ms": 702, "connect_ms": 9, "redirects": 0, "final_url": "https://www.example.com/checkout/", "error": null, "error_text": null, "cloudflare": false, "cache_status": null }
  ],
  "rum": { "ttfb_p75": 1920, "rating": "poor", "period": "last 7 days" }
}

Na resposta real, recent contém 48 rondas; este exemplo mostra as duas últimas.

O objeto check e os respetivos resultados

A cada 30 minutos, uma ronda verifica todos os monitores a partir de dois servidores alternados: scan1 às :00, scan2 às :30. Uma ronda verifica sempre o URL tal como os visitantes lhe acedem, via DNS e através da CDN (edge). Com um IP de origem, verifica também o servidor diretamente (origin). A API não disponibiliza nenhuma chamada para verificar um monitor entre rondas. Os checks são guardados durante 30 dias.

Cada check envia o user agent CoreDash/1.0 (uptime; +https://www.coredash.app/bot). Quando o URL do monitor pertence ao site do próprio projeto (o respetivo host, com ou sem www, ou um subdomínio), o check envia também o header X-CoreDash-Bot com o valor secreto do projeto, obtido no separador do token do bot CoreDash nas definições do projeto. Um monitor em qualquer outro site não recebe qualquer token. Num redirect, o token segue a regra definida para os headers: só é mantido enquanto o redirect permanecer no host do monitor. Qualquer header próprio com o nome X-CoreDash-Bot é descartado. A página do bot do CoreDash explica ambos em detalhe.

Como é determinado o resultado de um check

O pior resultado dos checks de uma ronda determina o estado do monitor, do pior para o melhor: down, blocked, warn, up.

Estados do monitor

Um monitor num projeto cuja subscrição tenha terminado mantém as suas definições e o seu último estado. Não volta a ser verificado até o projeto ser pago novamente.

Adicionar, alterar e eliminar um monitor

POST /api/uptime/monitors

curl -X POST https://app.coredash.app/api/uptime/monitors \
  -H "Authorization: Bearer cdk_master_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/checkout/",
    "name": "Checkout",
    "project_id": "655f1f77bcf86cd799439011",
    "origin_ip": "203.0.113.10",
    "headers": [{ "name": "X-Staging-Auth", "value": "k7Qp2vX9mR4tL8wZ" }],
    "expect_status": 200
  }'

A resposta é 201 com o novo monitor, incluindo o IP de origem e os valores dos headers:

{
  "monitor": {
    "id": "6ad68c7a844fad80b752fd16",
    "name": "Checkout",
    "url": "https://www.example.com/checkout/",
    "project_id": "655f1f77bcf86cd799439011",
    "paused": false,
    "expect_status": 200,
    "origin_check": true,
    "origin_ip": "203.0.113.10",
    "headers": [{ "name": "X-Staging-Auth", "value": "k7Qp2vX9mR4tL8wZ" }],
    "state": "pending",
    "last_check_at": null,
    "last_up_at": null,
    "down_since": null,
    "last_down": null,
    "check_requested_at": "2026-10-20T09:12:41.000Z",
    "last": {},
    "cert_expires": null,
    "created_at": "2026-10-20T09:12:41.000Z"
  }
}

PATCH /api/uptime/monitors/:id

Envie apenas os campos a alterar. headers substitui a lista completa, pelo que deve enviar todos os headers que pretende manter. Este pedido coloca um monitor em pausa:

curl -X PATCH https://app.coredash.app/api/uptime/monitors/6ad68c7a844fad80b752fd16 \
  -H "Authorization: Bearer cdk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "paused": true }'

Com uma chave master, project_id move o monitor, segundo as mesmas regras do POST.

DELETE /api/uptime/monitors/:id

curl -X DELETE https://app.coredash.app/api/uptime/monitors/6ad68c7a844fad80b752fd16 \
  -H "Authorization: Bearer cdk_your_key"

Esta operação é irreversível. Para interromper os checks e manter o histórico, envie { "paused": true } com PATCH.

Erros e limites da API de uptime

Os erros são devolvidos como { "error": "..." } com um destes status:

Limites: 25 monitores por projeto, 5 headers adicionais por monitor, 2100 checks por GET de um monitor e 30 dias de histórico de checks.

Ferramentas MCP de uptime

O servidor MCP do CoreDash em https://app.coredash.app/api/mcp disponibiliza duas ferramentas de uptime a par das ferramentas de RUM, além de list_projects para os projetos acessíveis pela sua chave. As três são apenas de leitura. Para adicionar, alterar ou eliminar um monitor, use a app ou os endpoints REST acima com uma chave de API CoreDash. As ferramentas não precisam de project_id: uma chave de projeto lê o próprio projeto; uma chave master ou uma ligação OAuth como o Claude lê todos os projetos seus ou para os quais tenha sido convidado.

curl -X POST https://app.coredash.app/api/mcp \
  -H "Authorization: Bearer cdk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_uptime_monitor",
      "arguments": { "monitor_id": "6ad68c7a844fad80b752fd16", "limit": 48 }
    }
  }'

A resposta é o wrapper JSON-RPC da CoreDash API, com o resultado como string JSON em result.content[0].text. Um monitor desconhecido devolve { "error": "Monitor not found" } nesse campo, com result.isError a true.

Mais sobre uptime e a CoreDash API

• Monitorização de uptime: o que o CoreDash verifica e o que vê na app.
• CoreDash API: chaves de projeto, o formato JSON-RPC e as ferramentas de RUM.
• Agency API: chaves master e projetos via REST.
• Bot do CoreDash: o user agent, o header X-CoreDash-Bot e os respetivos endereços.
• Autorize o CoreDash na sua firewall: para um monitor que indique Bloqueado.