openapi: 3.0.3
info:
title: 'WebGuard API Reference'
description: 'Programmatic access to monitoring status, uptime history, incidents, SSL metadata, and server health reports.'
version: 1.0.0
servers:
- url: 'https://webguard.marcel-breuer.dev'
tags:
- name: 'Monitoring API'
description: "\nThis controller is responsible for handling all API requests related to monitoring data.\nIt provides endpoints for retrieving uptime/downtime, response times, incidents, and other monitoring statistics.\nThe controller makes extensive use of caching to ensure optimal performance."
- name: 'Server Health'
description: ''
components:
securitySchemes:
default:
type: http
scheme: bearer
description: 'You can retrieve your token by visiting your dashboard and clicking Generate API token.'
security:
-
default: []
paths:
'/api/v1/monitorings/{monitoring_id}':
get:
summary: 'Retrieves all data for a given monitoring instance.'
operationId: retrievesAllDataForAGivenMonitoringInstance
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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'
properties:
status_since:
type: object
properties:
status:
type: string
example: UP
time:
type: string
example: '2021-01-01 00:00:00'
status_now:
type: object
properties:
status:
type: string
example: UP
uptime_downtime:
type: array
example:
- date: '2021-01-01'
uptime: 100
downtime: 0
items:
type: object
properties:
date:
type: string
example: '2021-01-01'
uptime:
type: integer
example: 100
downtime:
type: integer
example: 0
response_times:
type: array
example:
- datetime: '2021-01-01 00:00:00'
response_time: 123
items:
type: object
properties:
datetime:
type: string
example: '2021-01-01 00:00:00'
response_time:
type: integer
example: 123
incidents:
type: array
example:
- started_at: '2021-01-01 00:00:00'
finished_at: '2021-01-01 00:05:00'
type: DOWN
reason: 'HTTP status code 500'
items:
type: object
properties:
started_at:
type: string
example: '2021-01-01 00:00:00'
finished_at:
type: string
example: '2021-01-01 00:05:00'
type:
type: string
example: DOWN
reason:
type: string
example: 'HTTP status code 500'
heatmap:
type: array
example:
- hour: '00:00'
uptime: 100
items:
type: object
properties:
hour:
type: string
example: '00:00'
uptime:
type: integer
example: 100
ssl:
type: object
properties:
valid:
type: boolean
example: true
expiration:
type: string
example: '2022-01-01T00:00:00.000000Z'
issuer:
type: string
example: "Let's Encrypt"
issue_date:
type: string
example: '2021-10-01T00:00:00.000000Z'
uptime_calendar:
type: object
properties:
2021-01:
type: array
example:
- date: '2021-01-01'
uptime: '100.00'
items:
type: object
properties:
date:
type: string
example: '2021-01-01'
uptime:
type: string
example: '100.00'
tags:
- 'Monitoring API'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
days:
type: integer
description: ''
example: 16
nullable: true
start_date:
type: string
description: 'Must be a valid date.'
example: '2026-06-02T06:56:29'
end_date:
type: string
description: 'Must be a valid date. Must be a date after or equal to start_date.'
example: '2052-06-25'
required:
- start_date
- end_date
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/status':
get:
summary: 'Retrieves the combined status of a given monitoring instance.'
operationId: retrievesTheCombinedStatusOfAGivenMonitoringInstance
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
status:
type: string
example: UP
since:
type: string
example: '2021-01-01 00:00:00'
checked_at:
type: string
example: '2021-01-01 00:00:00'
next:
type: string
example: '2021-01-01 00:05:00'
interval:
type: integer
example: 300
tags:
- 'Monitoring API'
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/uptime-downtime':
get:
summary: 'Retrieves the uptime and downtime data for a given monitoring instance.'
operationId: retrievesTheUptimeAndDowntimeDataForAGivenMonitoringInstance
description: ''
parameters:
-
in: query
name: days
description: 'The number of days to retrieve data for. Defaults to 30.'
example: 30
required: false
schema:
type: integer
description: 'The number of days to retrieve data for. Defaults to 30.'
example: 30
responses:
200:
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
example: '2021-01-01'
uptime:
type: integer
example: 100
downtime:
type: integer
example: 0
example:
-
date: '2021-01-01'
uptime: 100
downtime: 0
tags:
- 'Monitoring API'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
days:
type: integer
description: ''
example: 16
nullable: true
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/uptime-downtime-summary':
get:
summary: 'Retrieves uptime and downtime data for multiple day ranges in one request.'
operationId: retrievesUptimeAndDowntimeDataForMultipleDayRangesInOneRequest
description: ''
parameters:
-
in: query
name: 'days[]'
description: 'The day ranges to retrieve.'
example:
- 7
- 30
- 90
required: false
schema:
type: array
description: 'The day ranges to retrieve.'
example:
- 7
- 30
- 90
items:
type: integer
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
data:
'7':
has_data: true
'30':
has_data: true
properties:
data:
type: object
properties:
7:
type: object
properties:
has_data:
type: boolean
example: true
30:
type: object
properties:
has_data:
type: boolean
example: true
tags:
- 'Monitoring API'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
days:
type: array
description: 'Must be at least 1. Must not be greater than 3650.'
example:
- 1
items:
type: integer
required:
- days
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/response-times':
get:
summary: 'Retrieves the response times for a given monitoring instance.'
operationId: retrievesTheResponseTimesForAGivenMonitoringInstance
description: ''
parameters:
-
in: query
name: days
description: 'The number of days to retrieve data for. Defaults to 30.'
example: 30
required: false
schema:
type: integer
description: 'The number of days to retrieve data for. Defaults to 30.'
example: 30
responses:
200:
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
datetime:
type: string
example: '2021-01-01 00:00:00'
response_time:
type: integer
example: 123
example:
-
datetime: '2021-01-01 00:00:00'
response_time: 123
tags:
- 'Monitoring API'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
days:
type: integer
description: ''
example: 16
nullable: true
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/checks':
get:
summary: 'Retrieves historical monitoring checks including status code details.'
operationId: retrievesHistoricalMonitoringChecksIncludingStatusCodeDetails
description: ''
parameters:
-
in: query
name: days
description: 'Optional number of past days to include. If omitted, all available history is considered.'
example: 16
required: false
schema:
type: integer
description: 'Optional number of past days to include. If omitted, all available history is considered.'
example: 16
-
in: query
name: limit
description: 'Optional maximum number of entries returned. Defaults to 100.'
example: 16
required: false
schema:
type: integer
description: 'Optional maximum number of entries returned. Defaults to 100.'
example: 16
-
in: query
name: offset
description: 'Optional number of entries to skip for pagination. Defaults to 0.'
example: 16
required: false
schema:
type: integer
description: 'Optional number of entries to skip for pagination. Defaults to 0.'
example: 16
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
data:
type: array
example:
- 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
items:
type: object
properties:
id:
type: string
example: 01H...
checked_at:
type: string
example: '2026-03-24T12:00:00Z'
status:
type: string
example: down
http_status_code:
type: integer
example: 503
response_time:
type: number
example: 210.5
status_identifier:
type: string
example: status.server_error
status_key:
type: string
example: notifications.status.server_error
source:
type: string
example: live
meta:
type: object
properties:
count:
type: integer
example: 1
limit:
type: integer
example: 100
offset:
type: integer
example: 0
days:
type: integer
example: 7
has_more:
type: boolean
example: false
next_offset:
type: string
example: null
nullable: true
tags:
- 'Monitoring API'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
days:
type: integer
description: 'Must be at least 1. Must not be greater than 3650.'
example: 1
nullable: true
limit:
type: integer
description: 'Must be at least 1. Must not be greater than 1000.'
example: 22
nullable: true
offset:
type: integer
description: 'Must be at least 0. Must not be greater than 100000.'
example: 7
nullable: true
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/incidents':
get:
summary: 'Retrieves the incidents for a given monitoring instance.'
operationId: retrievesTheIncidentsForAGivenMonitoringInstance
description: ''
parameters:
-
in: query
name: days
description: 'The number of days to retrieve data for. Defaults to 30.'
example: 30
required: false
schema:
type: integer
description: 'The number of days to retrieve data for. Defaults to 30.'
example: 30
responses:
200:
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
started_at:
type: string
example: '2021-01-01 00:00:00'
finished_at:
type: string
example: '2021-01-01 00:05:00'
type:
type: string
example: DOWN
reason:
type: string
example: 'HTTP status code 500'
example:
-
started_at: '2021-01-01 00:00:00'
finished_at: '2021-01-01 00:05:00'
type: DOWN
reason: 'HTTP status code 500'
tags:
- 'Monitoring API'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
days:
type: integer
description: ''
example: 16
nullable: true
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/heatmap':
get:
summary: 'Retrieves the uptime heatmap data for a given monitoring instance.'
operationId: retrievesTheUptimeHeatmapDataForAGivenMonitoringInstance
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
hour:
type: string
example: '00:00'
uptime:
type: integer
example: 100
example:
-
hour: '00:00'
uptime: 100
tags:
- 'Monitoring API'
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/ssl':
get:
summary: 'Retrieves the SSL status for a given monitoring instance.'
operationId: retrievesTheSSLStatusForAGivenMonitoringInstance
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
valid: true
expiration: '2022-01-01T00:00:00.000000Z'
issuer: "Let's Encrypt"
issue_date: '2021-10-01T00:00:00.000000Z'
properties:
valid:
type: boolean
example: true
expiration:
type: string
example: '2022-01-01T00:00:00.000000Z'
issuer:
type: string
example: "Let's Encrypt"
issue_date:
type: string
example: '2021-10-01T00:00:00.000000Z'
tags:
- 'Monitoring API'
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/monitorings/{monitoring_id}/uptime-calendar':
get:
summary: 'Retrieves the uptime calendar data for a given monitoring instance.'
operationId: retrievesTheUptimeCalendarDataForAGivenMonitoringInstance
description: ''
parameters:
-
in: query
name: start_date
description: 'date The start date to retrieve data for.'
example: '2021-01-01'
required: true
schema:
type: string
description: 'date The start date to retrieve data for.'
example: '2021-01-01'
-
in: query
name: end_date
description: 'date The end date to retrieve data for.'
example: '2021-01-31'
required: true
schema:
type: string
description: 'date The end date to retrieve data for.'
example: '2021-01-31'
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
2021-01:
-
date: '2021-01-01'
uptime: '100.00'
properties:
2021-01:
type: array
example:
- date: '2021-01-01'
uptime: '100.00'
items:
type: object
properties:
date:
type: string
example: '2021-01-01'
uptime:
type: string
example: '100.00'
tags:
- 'Monitoring API'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
start_date:
type: string
description: 'Must be a valid date.'
example: '2026-06-02T06:56:29'
end_date:
type: string
description: 'Must be a valid date. Must be a date after or equal to start_date.'
example: '2052-06-25'
required:
- start_date
- end_date
parameters:
-
in: path
name: monitoring_id
description: 'The ID of the monitoring.'
example: 01k0rqs3gmz6esfrmgsre03yd6
required: true
schema:
type: string
'/api/v1/server-health/{token}':
post:
summary: 'Store a server health report.'
operationId: storeAServerHealthReport
description: "Use the private endpoint generated for a Server Health monitoring. Send\nCPU, RAM, and storage percentages from your server agent or cron script.\nIf no explicit status is supplied, WebGuard marks the report down when\nany percentage metric reaches that monitor's configured threshold."
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
message: 'Server health report accepted.'
status: up
metrics:
cpu_usage_percent: 42.5
ram_usage_percent: 68.2
storage_usage_percent: 74.1
properties:
message:
type: string
example: 'Server health report accepted.'
status:
type: string
example: up
metrics:
type: object
properties:
cpu_usage_percent:
type: number
example: 42.5
ram_usage_percent:
type: number
example: 68.2
storage_usage_percent:
type: number
example: 74.1
tags:
- 'Server Health'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: 'Optional explicit status. One of up, down, unknown.'
example: up
nullable: true
cpu_usage_percent:
type: number
description: 'CPU usage as a percentage from 0 to 100.'
example: 42.5
nullable: true
ram_usage_percent:
type: number
description: 'RAM usage as a percentage from 0 to 100.'
example: 68.2
nullable: true
storage_usage_percent:
type: number
description: 'Storage usage as a percentage from 0 to 100.'
example: 74.1
nullable: true
load_average:
type: number
description: 'Optional system load average.'
example: 1.42
nullable: true
uptime_seconds:
type: integer
description: 'Optional server uptime in seconds.'
example: 86400
nullable: true
extra_metrics:
type: object
description: 'Optional additional numeric or string metrics.'
example:
swap_usage_percent: 12.4
properties: {}
nullable: true
security: []
parameters:
-
in: path
name: token
description: 'The private server health token generated when the monitoring is created.'
example: 01HXZ7Q92W3K7VY9E6JQFM4XPC
required: true
schema:
type: string