WebGuard API Reference

Postman collection → OpenAPI spec →

Introduction

Programmatic access to monitoring status, uptime history, incidents, SSL metadata, and server health reports.

Base URL: https://webguard.marcel-breuer.dev

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Monitoring API

This controller is responsible for handling all API requests related to monitoring data. It provides endpoints for retrieving uptime/downtime, response times, incidents, and other monitoring statistics. The controller makes extensive use of caching to ensure optimal performance.

Retrieves all data for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Body Parameters

days

integer

Example:

start_date

string

required

Must be a valid date.

Example:

2026-06-02T06:56:29

end_date

string

required

Must be a valid date. Must be a date after or equal to start_date.

Example:

2052-06-25

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"days\": 16,
    \"start_date\": \"2026-06-02T06:56:29\",
    \"end_date\": \"2052-06-25\"
}"

Example response:

{
    "status_since": {
        "status": "UP",
        "time": "2021-01-01 00:00:00"
    },
    "status_now": {
        "status": "UP"
    },
    "uptime_downtime": [
        {
            "date": "2021-01-01",
            "uptime": 100,
            "downtime": 0
        }
    ],
    "response_times": [
        {
            "datetime": "2021-01-01 00:00:00",
            "response_time": 123
        }
    ],
    "incidents": [
        {
            "started_at": "2021-01-01 00:00:00",
            "finished_at": "2021-01-01 00:05:00",
            "type": "DOWN",
            "reason": "HTTP status code 500"
        }
    ],
    "heatmap": [
        {
            "hour": "00:00",
            "uptime": 100
        }
    ],
    "ssl": {
        "valid": true,
        "expiration": "2022-01-01T00:00:00.000000Z",
        "issuer": "Let's Encrypt",
        "issue_date": "2021-10-01T00:00:00.000000Z"
    },
    "uptime_calendar": {
        "2021-01": [
            {
                "date": "2021-01-01",
                "uptime": "100.00"
            }
        ]
    }
}

Retrieves the combined status of a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/status

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/status" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "status": "UP",
    "since": "2021-01-01 00:00:00",
    "checked_at": "2021-01-01 00:00:00",
    "next": "2021-01-01 00:05:00",
    "interval": 300
}

Retrieves the uptime and downtime data for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/uptime-downtime

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Query Parameters

days

integer

The number of days to retrieve data for. Defaults to 30.

Example:

Body Parameters

days

integer

Example:

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/uptime-downtime?days=30" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"days\": 16
}"

Example response:

[
    {
        "date": "2021-01-01",
        "uptime": 100,
        "downtime": 0
    }
]

Retrieves uptime and downtime data for multiple day ranges in one request.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/uptime-downtime-summary

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Query Parameters

days[]

integer[]

The day ranges to retrieve.

Example:

[7,30,90]

Body Parameters

days

integer[]

required

Must be at least 1. Must not be greater than 3650.

Example:

[1]

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/uptime-downtime-summary?days%5B%5D[]=7&days%5B%5D[]=30&days%5B%5D[]=90" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"days\": [
        1
    ]
}"

Example response:

{
    "data": {
        "7": {
            "has_data": true
        },
        "30": {
            "has_data": true
        }
    }
}

Retrieves the response times for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/response-times

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Query Parameters

days

integer

The number of days to retrieve data for. Defaults to 30.

Example:

Body Parameters

days

integer

Example:

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/response-times?days=30" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"days\": 16
}"

Example response:

[
    {
        "datetime": "2021-01-01 00:00:00",
        "response_time": 123
    }
]

Retrieves historical monitoring checks including status code details.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/checks

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Query Parameters

days

integer

Optional number of past days to include. If omitted, all available history is considered.

Example:

limit

integer

Optional maximum number of entries returned. Defaults to 100.

Example:

offset

integer

Optional number of entries to skip for pagination. Defaults to 0.

Example:

Body Parameters

days

integer

Must be at least 1. Must not be greater than 3650.

Example:

limit

integer

Must be at least 1. Must not be greater than 1000.

Example:

offset

integer

Must be at least 0. Must not be greater than 100000.

Example:

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/checks?days=16&limit=16&offset=16" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"days\": 1,
    \"limit\": 22,
    \"offset\": 7
}"

Example response:

{
    "data": [
        {
            "id": "01H...",
            "checked_at": "2026-03-24T12:00:00Z",
            "status": "down",
            "http_status_code": 503,
            "response_time": 210.5,
            "status_identifier": "status.server_error",
            "status_key": "notifications.status.server_error",
            "source": "live"
        }
    ],
    "meta": {
        "count": 1,
        "limit": 100,
        "offset": 0,
        "days": 7,
        "has_more": false,
        "next_offset": null
    }
}

Retrieves the incidents for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/incidents

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Query Parameters

days

integer

The number of days to retrieve data for. Defaults to 30.

Example:

Body Parameters

days

integer

Example:

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/incidents?days=30" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"days\": 16
}"

Example response:

[
    {
        "started_at": "2021-01-01 00:00:00",
        "finished_at": "2021-01-01 00:05:00",
        "type": "DOWN",
        "reason": "HTTP status code 500"
    }
]

Retrieves the uptime heatmap data for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/heatmap

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/heatmap" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[
    {
        "hour": "00:00",
        "uptime": 100
    }
]

Retrieves the SSL status for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/ssl

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/ssl" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "valid": true,
    "expiration": "2022-01-01T00:00:00.000000Z",
    "issuer": "Let's Encrypt",
    "issue_date": "2021-10-01T00:00:00.000000Z"
}

Retrieves the uptime calendar data for a given monitoring instance.

GET

https://webguard.marcel-breuer.dev

/api/v1/monitorings/{monitoring_id}/uptime-calendar

requires authentication

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

monitoring_id

string

required

The ID of the monitoring.

Example:

01k0rqs3gmz6esfrmgsre03yd6

Query Parameters

start_date

string

required

date The start date to retrieve data for.

Example:

2021-01-01

end_date

string

required

date The end date to retrieve data for.

Example:

2021-01-31

Body Parameters

start_date

string

required

Must be a valid date.

Example:

2026-06-02T06:56:29

end_date

string

required

Must be a valid date. Must be a date after or equal to start_date.

Example:

2052-06-25

Example request:

curl --request GET \
    --get "https://webguard.marcel-breuer.dev/api/v1/monitorings/01k0rqs3gmz6esfrmgsre03yd6/uptime-calendar?start_date=2021-01-01&end_date=2021-01-31" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"start_date\": \"2026-06-02T06:56:29\",
    \"end_date\": \"2052-06-25\"
}"

Example response:

{
    "2021-01": [
        {
            "date": "2021-01-01",
            "uptime": "100.00"
        }
    ]
}

Server Health

Store a server health report.

POST

https://webguard.marcel-breuer.dev

/api/v1/server-health/{token}

Use the private endpoint generated for a Server Health monitoring. Send CPU, RAM, and storage percentages from your server agent or cron script. If no explicit status is supplied, WebGuard marks the report down when any percentage metric reaches that monitor's configured threshold.

Headers

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

token

string

required

The private server health token generated when the monitoring is created.

Example:

01HXZ7Q92W3K7VY9E6JQFM4XPC

Body Parameters

status

string

Optional explicit status. One of up, down, unknown.

Example:

cpu_usage_percent

number

CPU usage as a percentage from 0 to 100.

Example:

42.5

ram_usage_percent

number

RAM usage as a percentage from 0 to 100.

Example:

68.2

storage_usage_percent

number

Storage usage as a percentage from 0 to 100.

Example:

74.1

load_average

number

Optional system load average.

Example:

1.42

uptime_seconds

integer

Optional server uptime in seconds.

Example:

86400

extra_metrics

object

Optional additional numeric or string metrics.

Example:

{"swap_usage_percent":12.4}

Example request:

curl --request POST \
    "https://webguard.marcel-breuer.dev/api/v1/server-health/01HXZ7Q92W3K7VY9E6JQFM4XPC" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"status\": \"up\",
    \"cpu_usage_percent\": 42.5,
    \"ram_usage_percent\": 68.2,
    \"storage_usage_percent\": 74.1,
    \"load_average\": 1.42,
    \"uptime_seconds\": 86400,
    \"extra_metrics\": {
        \"swap_usage_percent\": 12.4
    }
}"

Example response:

{
    "message": "Server health report accepted.",
    "status": "up",
    "metrics": {
        "cpu_usage_percent": 42.5,
        "ram_usage_percent": 68.2,
        "storage_usage_percent": 74.1
    }
}