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.

Base URL: https://www.urlgoose.ca/api/v1

Authentication

Authenticate API requests by passing your personal API token in the HTTP Authorization header using the Bearer scheme. Tokens begin with ug_live_.

⚠️ Security Notice: Never pass tokens via query parameters or commit them to public version control. Tokens can be scoped to All Sites or Selected Sites, and revoked at any time in API Tokens Settings.
Quick Start Example
curl https://www.urlgoose.ca/api/v1/monitors \ -H "Authorization: Bearer ug_live_YOUR_TOKEN" \ -H "Accept: application/json"
<?php $client = new \GuzzleHttp\Client(); $response = $client->request('GET', 'https://www.urlgoose.ca/api/v1/monitors', [ 'headers' => [ 'Authorization' => 'Bearer ug_live_YOUR_TOKEN', 'Accept' => 'application/json', ], ]); $monitors = json_decode($response->getBody(), true);
const response = await fetch('https://www.urlgoose.ca/api/v1/monitors', { headers: { 'Authorization': 'Bearer ug_live_YOUR_TOKEN', 'Accept': 'application/json' } }); const data = await response.json();
import requests response = requests.get( 'https://www.urlgoose.ca/api/v1/monitors', headers={ 'Authorization': 'Bearer ug_live_YOUR_TOKEN', 'Accept': 'application/json' } ) data = response.json()

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:readList and inspect registered sites.
sites:writeCreate, update, and delete sites and default monitors.
monitors:readList and inspect monitors and uptime metrics.
monitors:writeCreate, update, and delete monitors.
heartbeats:readList and inspect heartbeat cron monitors.
heartbeats:writeCreate, update, and delete heartbeat monitors.
incidents:readView downtime incidents and diagnostic history.
maintenance:readList active and scheduled maintenance windows.
maintenance:writeCreate, 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)

NEW

Connect URLGoose directly to your AI assistants (Cursor, Claude Desktop, Claude Code, Antigravity) to query uptime, health, and incidents in real time.

Streamable HTTP
Endpoint URL https://urlgoose.ca/mcp
Authentication Bearer ug_live_...
Permissions Strictly Read-Only (Safe)

Client Configuration

{ "mcpServers": { "urlgoose": { "url": "https://urlgoose.ca/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } }
{ "mcpServers": { "urlgoose": { "url": "https://urlgoose.ca/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } }
claude mcp add urlgoose -- https://urlgoose.ca/mcp \ --header "Authorization: Bearer YOUR_API_TOKEN"
agy mcp add urlgoose https://urlgoose.ca/mcp \ --header "Authorization: Bearer YOUR_API_TOKEN"

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?
Example Prompts for Your AI Agent
  • "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).

GET /api/v1/sites Scope: sites:read
POST /api/v1/sites Scope: sites:write
GET /api/v1/sites/{id} Scope: sites:read
PATCH /api/v1/sites/{id} Scope: sites:write
DELETE /api/v1/sites/{id} Scope: sites:write
GET /api/v1/sites/{id}/monitors Scope: monitors:read
GET /api/v1/sites/{id}/heartbeats Scope: heartbeats:read
GET /api/v1/sites/{id}/incidents Scope: incidents:read
GET /api/v1/sites/{id}/maintenance-windows Scope: maintenance:read

Monitors Endpoints

GET /api/v1/monitors Scope: monitors:read
POST /api/v1/monitors Scope: monitors:write
GET /api/v1/monitors/{id} Scope: monitors:read
PATCH /api/v1/monitors/{id} Scope: monitors:write
DELETE /api/v1/monitors/{id} Scope: monitors:write

Heartbeats Endpoints

GET /api/v1/heartbeats Scope: heartbeats:read
POST /api/v1/heartbeats Scope: heartbeats:write
GET /api/v1/heartbeats/{id} Scope: heartbeats:read
PATCH /api/v1/heartbeats/{id} Scope: heartbeats:write
DELETE /api/v1/heartbeats/{id} Scope: heartbeats:write

Incidents Endpoints

GET /api/v1/incidents Scope: incidents:read
GET /api/v1/incidents/{id} Scope: incidents:read

Maintenance Windows Endpoints

GET /api/v1/maintenance-windows Scope: maintenance:read
POST /api/v1/maintenance-windows Scope: maintenance:write
GET /api/v1/maintenance-windows/{id} Scope: maintenance:read
PATCH /api/v1/maintenance-windows/{id} Scope: maintenance:write
DELETE /api/v1/maintenance-windows/{id} Scope: maintenance:write