Developer REST API (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: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."
      ]
    }
  }
}

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