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."
]
}
}
}
Model Context Protocol (MCP)
NEWConnect URLGoose directly to your AI assistants (Cursor, Claude Desktop, Claude Code, Antigravity) to query uptime, health, and incidents in real time.
Client Configuration
Replace YOUR_API_TOKEN with your personal API token created in API Tokens Settings.
Available Read-Only Tools
| Tool | Description | Arguments |
|---|---|---|
| list_sites | Discover monitored sites, domains, and counts of monitors and heartbeats. | search?, limit? |
| get_site_health | Operational health status (operational, outage, maintenance), failing checks with error details, active incidents, and maintenance windows. | site_id |
| list_monitors | Inspect uptime monitors with response times, 24h/30d uptime percentages, and status. (Secrets & request bodies are never exposed). | site_id?, status?, enabled?, search?, limit? |
| list_incidents | List outage incidents with duration, root-cause error diagnosis, and resolved status. | site_id?, status?, monitor_id?, heartbeat_id?, limit? |
| get_heartbeat_history | Retrieve heartbeat status, typical runtime (median), and execution duration history over 24h, 7d, or 30d. (Ping URLs & UUIDs strictly omitted). | 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).