API di uptime e tool MCP di CoreDash: monitor e check

Monitor di uptime tramite l'API di CoreDash

Leggi e modifica i monitor di uptime dei progetti CoreDash via REST, con la chiave API che già usi per i dati RUM. Un agente AI li legge tramite MCP.

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

Chiavi API per i monitor di uptime

Gli endpoint di uptime accettano le chiavi dell'API di CoreDash e dell'Agency API.

Crea una chiave di progetto nella pagina Connect Your AI nella barra laterale del progetto: assegna un nome e fai clic su Generate API key. Le stesse chiavi si trovano nelle impostazioni del progetto sotto API Keys (MCP). Solo i proprietari del progetto possono crearle. Una master key si genera dalla pagina Agency API nella barra laterale, negli account agency. Quando un progetto scade, la sua chiave di progetto riceve 401 a ogni chiamata.

Un guest in un progetto ne legge i monitor. Per aggiungerli, modificarli, spostarli ed eliminarli serve un progetto di tua proprietà.

Il token OAuth di una connessione AI come Claude (mcp_at_) è di sola lettura. Le chiamate POST, PATCH e DELETE con questo token restituiscono 403.

Endpoint di uptime

L'IP di origine e i valori degli header sono segreti. Vengono restituiti da POST, PATCH e GET /api/uptime/monitors/:id. L'elenco e i tool MCP omettono origin_ip e mostrano ogni valore degli header come ••••.

L'oggetto monitor

I campi summary e rum

Sia l'elenco sia il singolo monitor contengono un summary: rounds_7d e down_rounds_7d contano i round degli ultimi 7 giorni, uptime_7d è la percentuale di quei round privi di check down, e recent raccoglie gli ultimi 48 round, dal più vecchio, ciascuno con l'esito peggiore del round. Un monitor senza check negli ultimi 7 giorni ha summary: null.

Il singolo monitor include anche rum: il TTFB al p75 registrato dai visitatori reali negli ultimi 7 giorni, ricavato dai dati RUM del progetto, da confrontare con il ttfb_ms del checker. Vale null finché il progetto non ha dati 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" }
}

Nella risposta reale recent contiene 48 round; questo esempio mostra gli ultimi due.

L'oggetto check e i suoi esiti

Ogni 30 minuti un round controlla tutti i monitor, a turno da due server: scan1 a :00, scan2 a :30. Un round verifica sempre l'URL così come lo raggiungono i visitatori, tramite DNS e CDN (edge). Con un IP di origine controlla anche direttamente il server (origin). L'API non prevede chiamate per eseguire check tra un round e l'altro. I check vengono conservati per 30 giorni.

Ogni check invia lo user agent CoreDash/1.0 (uptime; +https://www.coredash.app/bot). Se l'URL del monitor si trova sul sito stesso del progetto (il suo host, con o senza www, o un sottodominio), il check invia anche l'header X-CoreDash-Bot con il valore segreto del progetto, ricavato dalla scheda CoreDash bot token nelle impostazioni del progetto. Un monitor su qualsiasi altro sito non riceve alcun token. In caso di redirect, il token segue la regola degli headers configurati: viene inoltrato solo finché il redirect rimane sull'host del monitor. Un tuo header chiamato X-CoreDash-Bot viene scartato. La pagina del bot di CoreDash contiene maggiori dettagli su entrambi.

Come viene determinato l'esito di un check

L'esito peggiore tra i check di un round determina lo stato del monitor, in ordine dal peggiore al migliore: down, blocked, warn, up.

Stati del monitor

Un monitor in un progetto con abbonamento scaduto conserva le impostazioni e l'ultimo stato. Non viene controllato finché il progetto non viene pagato di nuovo.

Aggiungi, modifica ed elimina un 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
  }'

La risposta è 201 con il nuovo monitor, inclusi IP di origine e valori degli header:

{
  "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

Invia solo i campi da modificare. headers sostituisce l'intero elenco, quindi invia tutti gli header che intendi mantenere. Questo comando mette in pausa un monitor:

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 }'

Con una master key, project_id sposta il monitor seguendo le stesse regole di POST.

DELETE /api/uptime/monitors/:id

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

L'operazione non si può annullare. Per interrompere i check e mantenere la cronologia, invia { "paused": true } con PATCH.

Errori e limiti dell'API di uptime

Gli errori vengono restituiti come { "error": "..." } con uno di questi codici di stato:

Limiti: 25 monitor per progetto, 5 header aggiuntivi per monitor, 2100 check per ogni GET di un singolo monitor e 30 giorni di storico dei check.

Tool MCP per l'uptime

Il server MCP di CoreDash su https://app.coredash.app/api/mcp include due tool di uptime oltre ai tool RUM, più list_projects per i progetti accessibili dalla tua chiave. Tutti e tre sono di sola lettura. Per aggiungere, modificare o eliminare un monitor, usa l'app o gli endpoint REST descritti sopra con una chiave API di CoreDash. I tool non richiedono project_id: una chiave di progetto legge il proprio progetto, mentre una master key o una connessione OAuth come Claude legge tutti i progetti di tua proprietà o a cui hai ricevuto un invito.

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 }
    }
  }'

La risposta è il wrapper JSON-RPC dell'API di CoreDash, con il risultato come stringa JSON in result.content[0].text. Un monitor sconosciuto restituisce { "error": "Monitor not found" } in quel campo e result.isError vale true.

Approfondimenti su uptime e API di CoreDash

• Monitoraggio dell'uptime: cosa controlla CoreDash e cosa vedi nell'app.
• API di CoreDash: chiavi di progetto, formato JSON-RPC e tool RUM.
• Agency API: master key e progetti via REST.
• Bot di CoreDash: lo user agent, l'header X-CoreDash-Bot e gli indirizzi.
• Autorizza CoreDash nel firewall: per un monitor che segnala Blocked.