watcher

Getting Started

The Watcher API provides REST endpoints for programmatic access to uptime monitoring functionality. Before you can use the API, you'll need to:

Have an active Watcher account
Be assigned to an organisation
Generate an API key from your account settings

Creating an API Key

To create an API key through the web interface:

Log in to your Watcher account
Navigate to Settings → API Keys or visit the API Keys page
Click the "Create API Key" button
Enter a descriptive name for your API key (e.g., "Production Server", "CI/CD Pipeline")
Click "Create"

Important Security Notice

The API key will be displayed only once. Make sure to copy and store it securely. If you lose the key, you'll need to create a new one.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN_HERE

Replace YOUR_API_TOKEN_HERE with the actual token you received when creating your API key.

API Endpoints

POST /api/urls

Create a new monitored URL for uptime monitoring.

Request Body

{
  "name": "My Website",
  "url": "https://example.com",
  "description": "Main company website",
  "check_interval_minutes": 5,
  "is_active": true,
  "webhook_url": "https://flashboard.example.com/webhook/abc123"
}

Parameters

name required

String (1-255 characters) - A descriptive name for the monitored URL

url required

String (max 2048 characters) - HTTPS URL to monitor. HTTP URLs are only allowed for localhost and 127.0.0.1.

description optional

String (max 1000 characters) - Additional details about this monitored URL

check_interval_minutes required

Integer (1-60) - How often to check the URL, in minutes

is_active optional

Boolean - Whether monitoring is active. Defaults to true.

webhook_url optional

String (max 2048 characters) - HTTPS webhook URL to receive notifications on downtime events (status: down, timeout, error) and recovery. HTTP URLs are only allowed for localhost and 127.0.0.1.

Success Response (201 Created)

{
  "message": "URL created successfully.",
  "data": {
    "id": 123,
    "name": "My Website",
    "url": "https://example.com",
    "description": "Main company website",
    "check_interval_minutes": 5,
    "is_active": true,
    "webhook_url": "https://flashboard.example.com/webhook/abc123",
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

Business Rules

Maximum 50 monitored URLs per organisation
Production URLs must use HTTPS; HTTP is only allowed for localhost and 127.0.0.1 in local development
URLs are automatically assigned to your organisation
Activity is logged for audit purposes

GET /api/urls/{id}/status

Get the current monitoring status of a specific URL.

URL Parameters

id

The ID of the monitored URL (returned when creating a URL)

Authorization

All users can only access URLs that belong to their own organisation.
Users without the manage uptime monitoring permission can only access URLs they created (where created_by matches their user ID).
Users with the manage uptime monitoring permission can access all monitored URLs within their organisation.

Success Response (200 OK)

{
  "data": {
    "id": 123,
    "name": "My Website",
    "url": "https://example.com",
    "last_status": "up",
    "last_checked_at": "2024-01-15T10:25:00.000000Z",
    "last_response_time_ms": 245,
    "last_error_message": null,
    "is_active": true,
    "uptime_percentage_30_days": 99.8
  }
}

Status Values

up

Site is responding normally (HTTP 2xx/3xx)

down

Site returned an error (HTTP 4xx/5xx)

timeout

Connection timed out after retries

error

Network or other technical error

Usage Examples

Creating a Monitored URL (cURL)

curl -X POST https://your-domain.com/api/urls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Site",
    "url": "https://example.com",
    "check_interval_minutes": 5
  }'

Checking URL Status (cURL)

curl -X GET https://your-domain.com/api/urls/123/status \
  -H "Authorization: Bearer YOUR_TOKEN"

PHP Example

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_TOKEN')
    ->post('https://your-domain.com/api/urls', [
        'name' => 'My Site',
        'url' => 'https://example.com',
        'check_interval_minutes' => 5,
    ]);

$data = $response->json();

JavaScript Example

const response = await fetch('https://your-domain.com/api/urls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Site',
    url: 'https://example.com',
    check_interval_minutes: 5
  })
});

const data = await response.json();

Rate Limiting

All API endpoints are rate-limited to 60 requests per minute per user to prevent abuse and ensure fair usage.

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait for the rate limit window to reset before making additional requests.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK

Request was successful

201 Created

Resource was created successfully

401 Unauthorized

Invalid or missing API token

403 Forbidden

You don't have permission to access this resource

404 Not Found

Resource not found

422 Unprocessable Entity

Validation error - check the error response for details

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error - please try again later

Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "url": ["Only HTTPS URLs are allowed for monitoring."],
    "check_interval_minutes": ["Check interval must be at least 1 minute."]
  }
}

Ready to Get Started?

Start using the Watcher API today to integrate uptime monitoring into your applications and workflows.

Get Started Free Log In

API Documentation

Table of Contents