Developer REST API & MCP (v1)
The URLGoose Developer API allows Pro subscribers to programmatically manage sites, monitors, heartbeats, incidents, and scheduled maintenance windows. Integrate monitoring directly into your CI/CD deployment pipelines, Terraform infrastructure-as-code, and internal status tooling.
Authentication
Authenticate API requests by passing your personal API token in the HTTP Authorization header using the Bearer scheme. Tokens begin with ug_live_.
Rate Limiting & Headers
The API enforces a rate limit of 120 requests per minute per personal API token. Rate limit metrics are returned in the response headers:
- X-RateLimit-Limit: 120
- X-RateLimit-Remaining: 119
- X-RateLimit-Reset: 1758999600
Granular Scopes
| Scope | Description |
|---|---|
| * | Full access to all API resources. |
| sites:read | List and inspect registered sites. |
| sites:write | Create, update, and delete sites and default monitors. |
| monitors:read | List and inspect monitors and uptime metrics. |
| monitors:write | Create, update, and delete monitors. |
| heartbeats:read | List and inspect heartbeat cron monitors. |
| heartbeats:write | Create, update, and delete heartbeat monitors. |
| incidents:read | View downtime incidents and diagnostic history. |
| maintenance:read | List active and scheduled maintenance windows. |
| maintenance:write | Create, update, and delete maintenance windows. |
Error Handling
All error responses follow a consistent JSON format:
{
"error": {
"code": "validation_error",
"message": "The request could not be processed.",
"details": {
"url": [
"The URL field is required."
]
}
}
}
Protocole Model Context (MCP)
NEWConnectez URLGoose directement à vos assistants IA (Cursor, Claude Desktop, Claude Code, Antigravity) pour interroger la disponibilité, l'état de santé et les incidents en temps réel.
Configuration du client
Remplacer YOUR_API_TOKEN with your personal API token created in API Tokens Settings.
Outils en lecture seule disponibles
| Tool | Description | Arguments |
|---|---|---|
| list_sites | Découvrez les sites surveillés, les domaines et le décompte des moniteurs et des pulsations. | search?, limit? |
| get_site_health | État de santé opérationnel (opérationnel, panne, maintenance), vérifications échouées avec détails d'erreur, incidents actifs et fenêtres de maintenance. | site_id |
| list_monitors | Inspectez les moniteurs avec délais de réponse, pourcentages de disponibilité 24 h/30 j et état. (Les secrets et corps de requête ne sont jamais exposés). | site_id?, status?, enabled?, search?, limit? |
| list_incidents | Consultez les incidents de panne avec durée, diagnostic de la cause racine et état de résolution. | site_id?, status?, monitor_id?, heartbeat_id?, limit? |
| get_heartbeat_history | Obtenez l'état de la pulsation, le temps d'exécution médian et l'historique de durée sur 24 h, 7 j ou 30 j. (URL de ping et UUID strictement omis). | heartbeat_id, range? |
- "Check the health of my production site on URLGoose."
- "Are there any open downtime incidents right now?"
- "What is the average response time for our checkout API monitor over the last 24 hours?"
- "Is our daily sync worker heartbeat taking longer than its typical runtime?"
Sites Endpoints
Sites are the top-level organizational and security boundary for all monitoring resources. A Site represents an application or web service (e.g. example.com).