Documentazione

API REST v1

Gestisci monitor, leggi uptime e incidenti e integra UptimeAnchor nei tuoi strumenti. Tutte le richieste e risposte sono in JSON.

URL di base

https://uptimeanchor.com/api/v1

Specifica OpenAPI/api/v1/openapi.json

Autenticazione

Ogni richiesta deve includere una chiave API nell'header Authorization con lo schema Bearer. Le chiavi appartengono a un'organizzazione e non scadono finché non le revochi.

Authorization: Bearer vg_live_xxxxxxxxxxxxxxxxxxxxxxxx

Puoi creare e revocare le chiavi in Impostazioni → API

READ
Sola lettura di tutte le risorse dell'organizzazione.
WRITE
Lettura e scrittura: creare, modificare, mettere in pausa ed eliminare monitor.
MONITOR
Sola lettura limitata a un singolo monitor, ideale per dashboard esterne.

Errori

In caso di errore la risposta ha un codice HTTP 4xx o 5xx e un corpo JSON con un oggetto error che contiene code (stabile, da usare nel codice), message (leggibile) ed eventualmente details.

{
  "error": {
    "code": "invalid_parameter",
    "message": "'limit' must be between 1 and 100."
  }
}

HTTP	code	Descrizione
400	invalid_parameter	Parametro di query non valido.
400	invalid_json	Il corpo della richiesta non è un oggetto JSON valido.
422	validation_error	Dati non validi; details elenca i campi con errori.
401	unauthorized	Chiave API mancante o non valida.
403	insufficient_scope	La chiave non ha i permessi richiesti (ad es. serve WRITE).
403	plan_limit	L'operazione supera i limiti del piano.
404	not_found	Risorsa inesistente o non accessibile.
429	rate_limited	Limite di richieste superato; attendi Retry-After secondi.
500	internal_error	Errore interno; riprova più tardi.

I limiti si applicano per chiave API su finestre di 60 secondi: 60 richieste al minuto nel piano Free e 300 nei piani a pagamento. Ogni risposta include gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; oltre il limite ricevi un 429 con l'header Retry-After.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 30

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (60 requests per minute)." } }

Paginazione

Gli endpoint che restituiscono liste usano la paginazione a cursore. Passa limit (1–100, predefinito 50) e, per le pagine successive, il valore pagination.nextCursor della risposta precedente come cursor. Quando nextCursor è null hai raggiunto la fine.

curl "https://uptimeanchor.com/api/v1/monitors?limit=100&cursor=cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Monitor

Elenca i monitor

GET/api/v1/monitors

Restituisce i monitor dell'organizzazione, ordinati per ID. Le credenziali salvate nella configurazione vengono sempre oscurate.

Parametri

Nome	Posizione	Tipo	Descrizione
limit	query	integer	Elementi per pagina, da 1 a 100 (predefinito 50).
cursor	query	string	Valore di pagination.nextCursor della pagina precedente.
status	query	enum	Filtra per stato: UP, DOWN, PAUSED, MAINTENANCE, PENDING (anche più valori separati da virgola).
type	query	enum	Filtra per tipo, ad es. HTTP,PORT.
search	query	string	Cerca nel nome e nel target.

Richiesta

curl "https://uptimeanchor.com/api/v1/monitors?status=DOWN&limit=50" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{
  "data": [
    {
      "id": "cm2x8f1k30001qz0v",
      "name": "Checkout",
      "type": "HTTP",
      "status": "UP",
      "target": "https://shop.example.com/checkout",
      "port": null,
      "interval": 60,
      "timeout": 30,
      "regions": ["eu-south", "eu-central"],
      "config": { "method": "GET", "expectedStatus": "200-299" },
      "sslCheck": true,
      "sslExpiryReminders": true,
      "heartbeatUrl": null,
      "tags": ["produzione"],
      "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 1, "recurrence": 0 }],
      "lastCheckedAt": "2026-10-18T09:41:00.000Z",
      "lastResponseMs": 182,
      "lastError": null,
      "sslExpiresAt": "2027-01-12T23:59:59.000Z",
      "sslIssuer": "R11",
      "pausedAt": null,
      "createdAt": "2026-03-02T10:15:22.000Z",
      "updatedAt": "2026-10-18T09:41:00.000Z"
    }
  ],
  "pagination": { "limit": 50, "nextCursor": null }
}

Crea un monitor

POST/api/v1/monitors

Crea un nuovo monitor e pianifica subito il primo controllo. Richiede una chiave WRITE. Risponde 201 con il monitor creato; per i monitor HEARTBEAT la risposta include heartbeatUrl.

Parametri

Nome	Posizione	Tipo	Descrizione
name*	body	string	Nome del monitor (max 120 caratteri).
type*	body	enum	HTTP, KEYWORD, PING, PORT, UDP, HEARTBEAT, DNS o DOMAIN.
target	body	string	URL (HTTP/KEYWORD) oppure host o dominio. Non richiesto per HEARTBEAT.
port	body	integer	Porta, obbligatoria per PORT e UDP.
interval	body	integer	Intervallo in secondi, da 30 a 86400 (predefinito 300). Il minimo dipende dal piano.
timeout	body	integer	Timeout in secondi, da 1 a 60 (predefinito 30).
regions	body	string[]	Id dei POP di controllo (es. eu-south). L'elenco aggiornato è restituito da GET /api/v1/regions.
config	body	object	Opzioni per tipo: method, headers, body, expectedStatus, keyword, keywordMode, dnsRecordType, dnsExpected, udpPayload… (vedi la specifica OpenAPI).
gracePeriod	body	integer	Solo HEARTBEAT: tolleranza in secondi (predefinito 60).
sslExpiryReminders	body	boolean	Promemoria di scadenza del certificato (predefinito true).
alertContacts	body	object[]	Contatti da avvisare: alertContactId, threshold (minuti di attesa prima dell'avviso) e recurrence (ripetizione in minuti, 0 = mai).
tags	body	string[]	Fino a 20 tag.

Richiesta

curl -X POST "https://uptimeanchor.com/api/v1/monitors" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout",
    "type": "HTTP",
    "target": "https://shop.example.com/checkout",
    "interval": 60,
    "regions": ["eu-south", "eu-central"],
    "config": { "method": "GET", "expectedStatus": "200-299" },
    "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 0, "recurrence": 0 }],
    "tags": ["produzione"]
  }'

Risposta

{
  "data": {
    "id": "cm2x8f1k30001qz0v",
    "name": "Checkout",
    "type": "HTTP",
    "status": "UP",
    "target": "https://shop.example.com/checkout",
    "port": null,
    "interval": 60,
    "timeout": 30,
    "regions": ["eu-south", "eu-central"],
    "config": { "method": "GET", "expectedStatus": "200-299" },
    "sslCheck": true,
    "sslExpiryReminders": true,
    "heartbeatUrl": null,
    "tags": ["produzione"],
    "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 1, "recurrence": 0 }],
    "lastCheckedAt": "2026-10-18T09:41:00.000Z",
    "lastResponseMs": 182,
    "lastError": null,
    "sslExpiresAt": "2027-01-12T23:59:59.000Z",
    "sslIssuer": "R11",
    "pausedAt": null,
    "createdAt": "2026-03-02T10:15:22.000Z",
    "updatedAt": "2026-10-18T09:41:00.000Z"
  }
}

Dettaglio di un monitor

GET/api/v1/monitors/{id}

Restituisce un singolo monitor con stato attuale, ultimo controllo, dati SSL e contatti associati.

Parametri

Nome	Posizione	Tipo	Descrizione
id*	path	string	ID del monitor.

Richiesta

curl "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{
  "data": {
    "id": "cm2x8f1k30001qz0v",
    "name": "Checkout",
    "type": "HTTP",
    "status": "UP",
    "target": "https://shop.example.com/checkout",
    "port": null,
    "interval": 60,
    "timeout": 30,
    "regions": ["eu-south", "eu-central"],
    "config": { "method": "GET", "expectedStatus": "200-299" },
    "sslCheck": true,
    "sslExpiryReminders": true,
    "heartbeatUrl": null,
    "tags": ["produzione"],
    "alertContacts": [{ "alertContactId": "cm2x9a0b10004qz0v", "threshold": 1, "recurrence": 0 }],
    "lastCheckedAt": "2026-10-18T09:41:00.000Z",
    "lastResponseMs": 182,
    "lastError": null,
    "sslExpiresAt": "2027-01-12T23:59:59.000Z",
    "sslIssuer": "R11",
    "pausedAt": null,
    "createdAt": "2026-03-02T10:15:22.000Z",
    "updatedAt": "2026-10-18T09:41:00.000Z"
  }
}

Modifica un monitor

PATCH/api/v1/monitors/{id}

Aggiorna solo i campi inviati; gli altri restano invariati. Accetta gli stessi campi della creazione. Richiede una chiave WRITE.

Parametri

Nome	Posizione	Tipo	Descrizione
id*	path	string	ID del monitor.

Richiesta

curl -X PATCH "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "interval": 120, "name": "Checkout (EU)" }'

Risposta

{
  "data": { "id": "cm2x8f1k30001qz0v", "name": "Checkout (EU)", "interval": 120, "…": "…" }
}

Elimina un monitor

DELETE/api/v1/monitors/{id}

Elimina definitivamente il monitor con i suoi controlli e incidenti. Richiede una chiave WRITE.

Parametri

Nome	Posizione	Tipo	Descrizione
id*	path	string	ID del monitor.

Richiesta

curl -X DELETE "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{ "data": { "id": "cm2x8f1k30001qz0v", "deleted": true } }

Metti in pausa

POST/api/v1/monitors/{id}/pause

Sospende i controlli e gli avvisi del monitor, ad esempio durante un rilascio. Richiede una chiave WRITE.

Parametri

Nome	Posizione	Tipo	Descrizione
id*	path	string	ID del monitor.

Richiesta

curl -X POST "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v/pause" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{ "data": { "id": "cm2x8f1k30001qz0v", "status": "PAUSED", "pausedAt": "2026-10-18T10:00:00.000Z", "…": "…" } }

Riprendi

POST/api/v1/monitors/{id}/resume

Riattiva un monitor in pausa e pianifica subito un controllo. Richiede una chiave WRITE.

Parametri

Nome	Posizione	Tipo	Descrizione
id*	path	string	ID del monitor.

Richiesta

curl -X POST "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v/resume" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{ "data": { "id": "cm2x8f1k30001qz0v", "status": "PENDING", "pausedAt": null, "…": "…" } }

Uptime di un monitor

GET/api/v1/monitors/{id}/uptime

Percentuale di uptime sul periodo richiesto, rapporti a 1, 7 e 30 giorni, tempo di inattività e dettaglio giornaliero.

Parametri

Nome	Posizione	Tipo	Descrizione
id*	path	string	ID del monitor.
days	query	integer	Numero di giorni, da 1 a 90 (predefinito 30).

Richiesta

curl "https://uptimeanchor.com/api/v1/monitors/cm2x8f1k30001qz0v/uptime?days=30" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{
  "data": {
    "monitorId": "cm2x8f1k30001qz0v",
    "days": 30,
    "uptime": 99.982,
    "ratios": { "1d": 99.46, "7d": 99.92, "30d": 99.982 },
    "downtimeSeconds": 466,
    "daily": [
      { "date": "2026-10-17", "total": 1440, "up": 1440, "uptime": 100, "avgResponseMs": 179, "downtimeSeconds": 0 },
      { "date": "2026-10-18", "total": 1440, "up": 1432, "uptime": 99.46, "avgResponseMs": 201, "downtimeSeconds": 466 }
    ]
  }
}

Incidenti

Elenca gli incidenti

GET/api/v1/incidents

Restituisce gli incidenti dal più recente, con causa, durata e stato.

Parametri

Nome	Posizione	Tipo	Descrizione
limit	query	integer	Elementi per pagina, da 1 a 100 (predefinito 50).
cursor	query	string	Valore di pagination.nextCursor della pagina precedente.
status	query	enum	OPEN o RESOLVED.
monitorId	query	string	Solo gli incidenti di un monitor.

Richiesta

curl "https://uptimeanchor.com/api/v1/incidents?status=OPEN" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{
  "data": [
    {
      "id": "cm2y0c7d20009qz0v",
      "monitorId": "cm2x8f1k30001qz0v",
      "monitorName": "Checkout",
      "status": "OPEN",
      "cause": "HTTP 503 Service Unavailable",
      "details": null,
      "rootCause": null,
      "startedAt": "2026-10-18T09:42:11.000Z",
      "resolvedAt": null,
      "acknowledgedAt": null,
      "durationSeconds": 312
    }
  ],
  "pagination": { "limit": 50, "nextCursor": null }
}

Status page

Elenca le status page

GET/api/v1/status-pages

Restituisce le status page dell'organizzazione con URL pubblico, dominio personalizzato e monitor inclusi.

Richiesta

curl "https://uptimeanchor.com/api/v1/status-pages" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{
  "data": [
    {
      "id": "cm2x7e4q00002qz0v",
      "name": "Status",
      "slug": "example",
      "url": "https://status.example.com",
      "customDomain": "status.example.com",
      "published": true,
      "passwordProtected": false,
      "language": "it",
      "theme": "AUTO",
      "accentColor": "#14b8a6",
      "monitors": [ "…" ]
    }
  ]
}

Contatti di avviso

Elenca i contatti di avviso

GET/api/v1/alert-contacts

Restituisce i contatti di avviso. Per motivi di sicurezza la configurazione non viene esposta: solo la destinazione per email, SMS e chiamate.

Richiesta

curl "https://uptimeanchor.com/api/v1/alert-contacts" \
  -H "Authorization: Bearer $UPTIMEANCHOR_API_KEY"

Risposta

{
  "data": [
    { "id": "cm2x9a0b10004qz0v", "type": "SLACK", "name": "On-call Slack", "enabled": true, "destination": null, "monitors": 12, "createdAt": "2026-03-02T10:20:00.000Z" },
    { "id": "cm2x9a0b10005qz0v", "type": "EMAIL", "name": "Ops", "enabled": true, "destination": "ops@example.com", "monitors": 30, "createdAt": "2026-03-02T10:21:00.000Z" }
  ]
}

URL heartbeat

Ogni monitor HEARTBEAT ha un URL segreto. Chiamalo al termine di ogni esecuzione del job: se il ping non arriva entro intervallo più tolleranza, il monitor va in DOWN. Non serve la chiave API.

GETPOST/api/heartbeat/{token}

Accetta GET, POST e HEAD e risponde 200 OK in testo semplice (404 se il token non esiste). Massimo 60 ping al minuto per token.

# crontab: esegue il backup e, solo se ha successo, invia il ping
0 3 * * *  /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://uptimeanchor.com/api/heartbeat/hb_7Qm2xK9pLr4s

# oppure da codice (Node.js)
await fetch("https://uptimeanchor.com/api/heartbeat/hb_7Qm2xK9pLr4s", { method: "POST" });

Badge di stato

Immagini SVG con lo stato o l'uptime di un monitor, da inserire in README, wiki e siti. Sono pubbliche per i monitor presenti su una status page pubblicata e non protetta; per gli altri aggiungi il parametro key con una chiave API.

GET/api/badge/{monitorId}

Nome	Posizione	Tipo	Descrizione
type	query	enum	status (predefinito) oppure uptime.
days	query	integer	Periodo per l'uptime, da 1 a 90 (predefinito 30).
label	query	string	Testo personalizzato a sinistra (max 40 caratteri).
lang	query	enum	it o en (predefinito en).
key	query	string	Chiave API, necessaria per i monitor non pubblici.

<!-- Markdown / README -->
![uptime](https://uptimeanchor.com/api/badge/cm2x8f1k30001qz0v?type=uptime&days=30)
![status](https://uptimeanchor.com/api/badge/cm2x8f1k30001qz0v?type=status&lang=it)

Specifica OpenAPI

La specifica OpenAPI 3 completa è disponibile in formato JSON: importala in Postman o Insomnia oppure usala per generare un client nel tuo linguaggio.

https://uptimeanchor.com/api/v1/openapi.json