How do I update to the latest version of the Oh Dear API

On 26 August 2025, we shipped a breaking change: "sites" were renamed "monitors" across the Oh Dear app and API. This is the only breaking change we've made to the API in the platform's history, and we plan to keep it that way. We wrote up the reasoning in this post.

If you're already on our latest SDKs and packages, you don't need to do anything. If you're still on the pre-August 2025 versions, this page walks you through the upgrade.

What changed in the API

• /api/sites/* endpoints were renamed to /api/monitors/*
• Every field or parameter named site_id was renamed to monitor_id
• /api/performance-records was replaced by three focused endpoints: /api/http-uptime-metrics, /api/ping-uptime-metrics, and /api/tcp-uptime-metrics
• Monitors now return grouped settings objects (uptime_check_settings, broken_links_check_settings, dns_check_settings, ...), which you can also send on create/update to configure those checks

The full response schema lives in our API reference documentation.

Scheduled task endpoints (grace period)

We kept the legacy cron endpoints working to give people time to migrate:

• GET /api/sites/<site_id>/cron-checks
• POST /api/sites/<site_id>/cron-checks
• POST /api/sites/<site_id>/cron-checks/sync

These will stop working on 1 August 2026. After that date, use the /api/monitors/<monitor_id> equivalents.

If you use spatie/laravel-schedule-monitor, v3 will sync fine against the legacy endpoints until 1 August 2026. After that, you need v4.

The ping URLs at ping.ohdear.app are unchanged. Your cron jobs don't need to do anything.

Updating your packages

Upgrade to these major versions:

• ohdearapp/ohdear-php-sdk: v4. The SDK was rewritten on top of Saloon, which makes it easier to customize.
• ohdearapp/ohdear-pulse: v2
• ohdearapp/laravel-ohdear-webhooks: v2
• spatie/laravel-schedule-monitor: v4

Each repository has an UPGRADE.md with step-by-step instructions.

composer require ohdearapp/ohdear-php-sdk:^4.0
composer require ohdearapp/laravel-ohdear-webhooks:^2.0
composer require spatie/laravel-schedule-monitor:^4.0

Quick example

Listing your monitors with a plain curl:

$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/monitors \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json'

Fetching a single monitor by ID:

$ curl https://ohdear.app/api/monitors/99 \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json'

For the full list of fields, filters, and actions, head to our API reference.

Need help with a specific migration? Get in touch and we'll walk through it with you.