Update Status Page Design
Updates the visual design configuration of a status page. Only the fields you provide are changed. All other settings keep their current values. Requires the role `admin` or `editor`; `readonly` can read the design but not change it.
PATCH /api/status-pages/:id/design
Path Parameter
| Parameter | Description |
|---|---|
id | Status page ID or publicId (UUID) |
Request Body (all optional)
Layout
| Field | Type | Values | Default | Description |
|---|---|---|---|---|
layout | string | statusboard classic cards minimal sleek board split timeline compact | statusboard | Visual layout template. statusboard is the default for status pages created from 7 September 2026; pages created before that keep the layout they had. |
pageWidth | string | sm md lg xl | lg | Max content width: sm = 672 px, md = 896 px, lg = 1024 px, xl = 1280 px |
Colors
| Field | Type | Values | Default | Description |
|---|---|---|---|---|
colorScheme | string | light dark auto | auto | Color mode. auto follows the visitor's system preference. |
accentColor | string | hex, e.g. #6366f1 | #6366f1 | Brand accent color used for highlights, borders, and gradients |
Typography & Style
| Field | Type | Values | Default | Description |
|---|---|---|---|---|
fontFamily | string | system mono | system | system = default sans-serif, mono = monospace |
cardRadius | string | none md xl | md | Card corner radius: none = sharp, md = rounded, xl = pill |
Header
| Field | Type | Values | Default | Description |
|---|---|---|---|---|
headerStyle | string | simple centered hero | simple | simple = left-aligned, centered = centered, hero = full gradient banner |
customTitle | string | max 120 chars | "" | Overrides the status page name in the header. Leave empty to use the page name. |
customSubtitle | string | max 200 chars | "" | Optional tagline below the title |
Display options
| Field | Type | Default | Description |
|---|---|---|---|
showUptimeStats | boolean | true | Show uptime percentage and service counts |
showServiceUrls | boolean | false | Show the monitored URL below each service name |
showLastChecked | boolean | false | Show the last check timestamp per service |
showHistory | boolean | true | Master switch for the incidents and maintenance area |
historyDays | integer | 30 | Window of the uptime bars, in days (1-3650). Incidents and maintenance have their own windows, see below. |
Incidents and maintenance
Incidents and maintenance are two separate sections, each with its own switch, its own item count and its own window.
| Field | Type | Default | Description |
|---|---|---|---|
showIncidents | boolean | true | Show the incidents section |
incidentLimit | integer | 5 | How many incidents are listed (1-50) |
incidentDays | integer | 30 | How far back resolved incidents are listed, in days (1-3650). An open incident is always shown, however old it is. |
showMaintenance | boolean | true | Show the maintenance section |
maintenanceLimit | integer | 5 | How many maintenance windows are listed (1-50) |
maintenanceDays | integer | 30 | How far back completed maintenance is listed, in days (1-3650). Announced maintenance is always shown, however far off it is. |
showIncidents and showMaintenance are the same setting as showRecentIncidents and showRecentMaintenance on the status page itself: writing either of those two through POST /api/status-pages or PATCH /api/status-pages/:id also updates the design config, so both stay in step.
| showPoweredBy | boolean | true | Show a "Powered by <your product name>" line in the footer. It names your organization's product name and never Uptimeify; with no product name set, nothing is rendered. |
Custom CSS
| Field | Type | Default | Description |
|---|---|---|---|
customCss | string | "" | Your own CSS for the public status page, at most 20000 bytes (UTF-8). An empty string removes it. |
The server parses the CSS and stores a normalized copy (comments removed, whitespace collapsed); the response and GET .../design return that copy. The rules:
- At-rules: only
@mediaand@supports.@import,@font-face,@keyframes,@layer,@scopeand all others are rejected. - No resource loads:
url()is rejected, and so is every function outside an allowlist (colors, gradients,var(),calc()and the other math functions, transforms, filters,repeat()/minmax(), shapes).image-set(),image(),cross-fade(),element(),src()andexpression()are not on it. behavior,-moz-binding,javascript:,</and<!are rejected.- Escapes are decoded before the check (
\75 rl(counts asurl(), case does not matter. - Scope: the CSS only reaches the page content (
@scope). The footer with the legal links and the subscribe dialog are outside it, and it is not applied in the dashboard preview or the embed widget. A browser without@scopeignores the whole block. Styles of the page that sit outside a cascade layer win over normal declarations;!importantoverrides them.
State labels
| Field | Type | Default | Description |
|---|---|---|---|
statusLabels | object | {} | Your own public texts for the states, keys operational, degraded, partialOutage, majorOutage, maintenance, at most 40 characters each. |
A state without its own text shows the default text in the visitor's language ("Operational", "Degraded performance", "Partial outage", "Major outage", "Maintenance"); your own text is shown as written, in every language. It applies to the rows, the overall status, the badge and the embed widget. statusLabels is merged per state: a request with { "statusLabels": { "majorOutage": "Disruption" } } changes only that one, null or "" restores the default text, other keys answer 400. Your own degraded text also replaces the "Warning" a monitor shows for a certificate notice.
curl -X PATCH "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/design" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "statusLabels": { "majorOutage": "Disruption", "maintenance": "Planned work" } }'Badge and widget of the page: /status/:slug/badge.svg and /status/:slug/embed, see Design & Branding.
Example: custom CSS
curl -X PATCH "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/design" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "customCss": "h1 { letter-spacing: -0.02em; } @media (max-width: 640px) { h1 { font-size: 1.5rem; } }" }'Example: switch to dark timeline layout
curl -X PATCH "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/design" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"layout": "timeline",
"colorScheme": "dark",
"accentColor": "#f59e0b",
"pageWidth": "lg"
}'Example: minimal, no branding, full width
curl -X PATCH "$BASE_URL/api/status-pages/db58058e-4b58-4d97-a314-3bb8e279a182/design" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"layout": "minimal",
"colorScheme": "light",
"pageWidth": "xl",
"showPoweredBy": false,
"showUptimeStats": false,
"customTitle": "System Status",
"customSubtitle": "Live overview of all services"
}'Response
{
"designConfig": {
"layout": "timeline",
"colorScheme": "dark",
"accentColor": "#f59e0b",
"headerStyle": "simple",
"fontFamily": "system",
"cardRadius": "md",
"pageWidth": "lg",
"customTitle": "",
"customSubtitle": "",
"showPoweredBy": true,
"showUptimeStats": true,
"showServiceUrls": false,
"showLastChecked": false,
"showHistory": true,
"historyDays": 30,
"showIncidents": true,
"incidentLimit": 5,
"incidentDays": 30,
"showMaintenance": true,
"maintenanceLimit": 5,
"maintenanceDays": 30,
"customCss": "",
"statusLabels": {}
}
}Common errors
400 Bad Request: invalid field value (e.g. unknown layout name or malformed hex color)400 Bad RequestcustomCssTooLarge:customCssis larger than 20000 bytes;data.maxcarries the limit400 Bad RequestcustomCssInvalid:customCsswas rejected;data.reasonissyntax,atRuleNotAllowed,functionNotAllowed,urlNotAllowed,propertyNotAllowed,escapeNotAllowed,htmlNotAllowedorcontrolCharacter401 Unauthorized: not authenticated403 Forbidden(forbidden): role is notadminoreditor(also a customer-boundreadonlyuser and a token issued by one), or a global supporter403 Forbidden(managed_by_organization): a customer-bound user or token changes the design of amanagedpage without the customer'scanEditManagedexception404 Not found: status page does not exist
Update Status Page
Updates a status page. At least one field must be provided. Requires the role `admin` or `editor`; customer-bound users and tokens (also `readonly`) update self-service pages of their customers.
Verify Status Page Domain
Verifies DNS TXT records for a custom status page domain. Organization-wide: admin only; customer-bound: by the page's ownership class.