Status Pages API

Status pages provide a public-facing view of your service health. You can customize the appearance, add custom domains, and manage announcements.

Public Endpoints

These endpoints are publicly accessible and do not require authentication.

Get Public Status

GET/api/status

Get public status page data including monitors, incidents, and settings

Query Parameters:

Parameter	Type	Required	Description
`domain`	string	No	Custom domain to look up status page

Success Response (200 OK):

{
  "monitors": [
    {
      "id": "monitor-uuid",
      "name": "Production API",
      "status": "UP",
      "response_time": 145,
      "last_check": "2024-01-15T10:30:00Z",
      "type": "HTTPS",
      "component_id": "component-uuid",
      "component_name": "API Services",
      "group_id": "group-uuid",
      "uptime": 99.95,
      "avgResponseTime": 142,
      "dailyUptime": [
        {
          "date": "2024-01-15",
          "uptime": 100,
          "totalChecks": 1440,
          "upChecks": 1440,
          "avgResponseTime": 142
        }
      ]
    }
  ],
  "components": [
    {
      "id": "component-uuid",
      "name": "API Services",
      "description": "Core API endpoints",
      "position": 1,
      "status": "OPERATIONAL",
      "group_id": "group-uuid",
      "group_name": "Backend"
    }
  ],
  "groups": [
    {
      "id": "group-uuid",
      "name": "Backend",
      "description": "Backend services",
      "position": 1,
      "components": [ ... ]
    }
  ],
  "ungroupedComponents": [],
  "activeIncidents": [
    {
      "id": "incident-uuid",
      "monitor_id": "monitor-uuid",
      "monitor_name": "Database",
      "title": "Database Performance Degradation",
      "status": "INVESTIGATING",
      "severity": "HIGH",
      "started_at": "2024-01-15T09:00:00Z"
    }
  ],
  "recentIncidents": [],
  "customCss": "",
  "statusPageSettings": {
    "title": "Acme Status",
    "logo_url": "/uploads/logo.png",
    "homepage_url": "https://acme.com",
    "layout_density": "wide",
    "layout_alignment": "left",
    "password_protected": false,
    "robots_meta": "index",
    "google_analytics_id": "G-XXXXXXXXXX",
    "show_bar_charts": true,
    "show_outage_details": true,
    "show_uptime_percentage": true,
    "enable_details_page": true,
    "enable_floating_status_bar": false,
    "show_monitor_url": false,
    "show_overall_percentage": true,
    "hide_paused_monitors": false,
    "show_footer_branding": true,
    "theme": "auto"
  },
  "activeAnnouncements": [
    {
      "id": "announcement-uuid",
      "title": "Scheduled Maintenance",
      "content": "We will be performing maintenance on Jan 20th.",
      "type": "maintenance",
      "status": "active",
      "starts_at": "2024-01-20T00:00:00Z",
      "ends_at": "2024-01-20T04:00:00Z",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Monitor URLs and sensitive configuration data are not exposed in public status page responses.

Verify Password (Protected Status Page)

POST/api/status/verify-password

Verify password for a password-protected status page

Request Body:

Field	Type	Required	Description
`password`	string	Yes	Status page password
`userId`	UUID	No	Specific user's status page

Request Example:

{
  "password": "statuspage-secret"
}

Success Response (200 OK):

{
  "success": true
}

Error Responses:

Status	Error	Description
400	`Password is required`	Missing password
400	`Status page is not password protected`	No password set
401	`Invalid password`	Wrong password

Get Public Postmortems

GET/api/status/postmortems

Get published postmortems for resolved incidents

Success Response (200 OK):

{
  "postmortems": [
    {
      "id": "postmortem-uuid",
      "incident_id": "incident-uuid",
      "title": "January 14 Database Outage",
      "summary": "Root cause analysis and prevention measures",
      "timeline": "...",
      "root_cause": "...",
      "impact": "...",
      "action_items": "...",
      "published": true,
      "incident_title": "Database Connection Issues",
      "incident_status": "RESOLVED",
      "incident_severity": "CRITICAL",
      "incident_started_at": "2024-01-14T08:00:00Z",
      "incident_resolved_at": "2024-01-14T09:30:00Z",
      "monitor_name": "Database Server",
      "created_at": "2024-01-15T12:00:00Z"
    }
  ]
}

GET/api/status/widget

Get embeddable status widget HTML

Query Parameters:

Parameter	Type	Default	Options
`mode`	string	`badge`	`badge`, `full`
`theme`	string	`dark`	`dark`, `light`

Badge Mode Response:

Returns a compact status badge (200x40 pixels) showing overall status.

Full Mode Response:

Returns a full status widget (400x300 pixels) showing all components and their status.

The widget auto-refreshes every 60 seconds.

GET/api/status/widget/embed-code

Get embed code snippets for widgets (authenticated)

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "badge": {
    "iframe": "<iframe src=\"https://app.pixomonitor.com/api/status/widget?mode=badge\" width=\"200\" height=\"40\" frameborder=\"0\"></iframe>",
    "iframeDark": "...",
    "iframeLight": "..."
  },
  "full": {
    "iframe": "<iframe src=\"https://app.pixomonitor.com/api/status/widget?mode=full\" width=\"400\" height=\"300\" frameborder=\"0\"></iframe>",
    "iframeDark": "...",
    "iframeLight": "..."
  },
  "javascript": "<script>...</script>",
  "statusPageUrl": "https://app.pixomonitor.com/status"
}

Status Page Settings

All settings endpoints require authentication.

Get Settings

GET/api/status-page-settings

Get current user's status page settings

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "settings": {
    "id": "settings-uuid",
    "user_id": "user-uuid",
    "title": "Acme Status",
    "homepage_url": "https://acme.com",
    "custom_domain": "status.acme.com",
    "domain_verified": true,
    "domain_verified_at": "2024-01-10T15:00:00Z",
    "logo_url": "/uploads/logo.png",
    "layout_density": "wide",
    "layout_alignment": "left",
    "password_protected": false,
    "robots_meta": "index",
    "google_analytics_id": "G-XXXXXXXXXX",
    "show_bar_charts": true,
    "show_outage_details": true,
    "show_uptime_percentage": true,
    "enable_details_page": true,
    "enable_floating_status_bar": false,
    "show_monitor_url": false,
    "show_overall_percentage": true,
    "hide_paused_monitors": false,
    "show_footer_branding": true,
    "custom_css": "",
    "theme": "auto",
    "accent_color": "#5b8def",
    "custom_header": "",
    "custom_footer": "",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Update Settings

PUT/api/status-page-settings

Create or update status page settings

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Default	Validation
`title`	string	-	Status page title
`homepage_url`	string	-	Link to your main website
`custom_domain`	string	-	Custom domain (e.g., status.acme.com)
`logo_url`	string	-	URL to logo image
`layout_density`	string	`wide`	`wide` or `compact`
`layout_alignment`	string	`left`	`left` or `center`
`password_protected`	boolean	false	Enable password protection
`password`	string	-	Status page password (required if enabling protection)
`robots_meta`	string	`index`	SEO robots directive
`google_analytics_id`	string	-	GA4 measurement ID
`show_bar_charts`	boolean	true	Show uptime bar charts
`show_outage_details`	boolean	true	Show outage details
`show_uptime_percentage`	boolean	true	Show uptime percentage
`enable_details_page`	boolean	true	Enable individual monitor pages
`enable_floating_status_bar`	boolean	false	Show floating status bar
`show_monitor_url`	boolean	false	Display monitor URLs publicly
`show_overall_percentage`	boolean	true	Show overall uptime
`hide_paused_monitors`	boolean	false	Hide paused monitors
`show_footer_branding`	boolean	true	Show PixoMonitor branding
`custom_css`	string	-	Custom CSS (sanitized)
`theme`	string	`auto`	`light`, `dark`, or `auto`
`accent_color`	string	`#5b8def`	Accent color hex code
`custom_header`	string	-	Custom header HTML
`custom_footer`	string	-	Custom footer HTML

Request Example:

{
  "title": "Acme Status",
  "homepage_url": "https://acme.com",
  "theme": "dark",
  "show_bar_charts": true,
  "show_uptime_percentage": true
}

Success Response (200 OK):

{
  "settings": {
    "id": "settings-uuid",
    "title": "Acme Status",
    ...
  }
}

Error Responses:

Status	Error	Description
400	`Invalid layout_density`	Must be "wide" or "compact"
400	`Invalid layout_alignment`	Must be "left" or "center"
400	`Invalid theme`	Must be "light", "dark", or "auto"
400	`Custom CSS contains disallowed content`	Dangerous CSS patterns detected

Custom CSS is sanitized to prevent XSS attacks. Dangerous patterns like javascript:, @import, and expression() are blocked.

Upload Logo

POST/api/status-page-settings/logo

Upload a logo image for the status page

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	image/*

Request:

Send raw image data in the request body (max 5MB).

Success Response (200 OK):

{
  "logo_url": "/uploads/logo_user-uuid_1705312200000.png"
}

Custom Domain

Verify Domain

POST/api/status-page-settings/verify-domain

Verify DNS CNAME record for custom domain

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

{
  "domain": "status.acme.com"
}

Setup Instructions:

Add a CNAME record for your subdomain pointing to pixomonitor.com
Call this endpoint to verify the DNS configuration

Success Response (200 OK) - Verified:

{
  "verified": true,
  "domain": "status.acme.com",
  "records": ["pixomonitor.com."],
  "message": "Domain verified successfully! Your status page is now accessible at https://status.acme.com"
}

Response - Not Verified:

{
  "verified": false,
  "domain": "status.acme.com",
  "error": "CNAME record not found. Please add a CNAME record pointing to pixomonitor.com",
  "message": "CNAME record found but does not point to pixomonitor.com"
}

Error Responses:

Status	Error	Description
400	`Domain is required`	Missing domain
400	`Invalid domain format`	Not a valid hostname
400	`This domain is already in use`	Domain registered to another user

Remove Custom Domain

DELETE/api/status-page-settings/custom-domain

Remove custom domain from status page

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "success": true,
  "message": "Custom domain removed"
}

Announcements

List Announcements

GET/api/status-page-settings/announcements

Get all announcements for the current user

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "announcements": [
    {
      "id": "announcement-uuid",
      "user_id": "user-uuid",
      "title": "Scheduled Maintenance",
      "content": "We will be performing maintenance on Jan 20th from 12am-4am UTC.",
      "type": "maintenance",
      "status": "active",
      "starts_at": "2024-01-20T00:00:00Z",
      "ends_at": "2024-01-20T04:00:00Z",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Announcement

POST/api/status-page-settings/announcements

Create a new announcement

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Required	Default	Validation
`title`	string	Yes	-	Announcement title
`content`	string	Yes	-	Announcement content
`type`	string	No	`info`	`info`, `warning`, `critical`, `maintenance`
`status`	string	No	`active`	`active`, `archived`
`starts_at`	ISO 8601	No	null	When to start showing
`ends_at`	ISO 8601	No	null	When to stop showing

Request Example:

{
  "title": "Scheduled Maintenance",
  "content": "We will be performing database maintenance on Jan 20th from 12am-4am UTC. Expect brief service interruptions.",
  "type": "maintenance",
  "starts_at": "2024-01-19T00:00:00Z",
  "ends_at": "2024-01-20T05:00:00Z"
}

Success Response (201 Created):

{
  "announcement": {
    "id": "announcement-uuid",
    "user_id": "user-uuid",
    "title": "Scheduled Maintenance",
    "content": "...",
    "type": "maintenance",
    "status": "active",
    "starts_at": "2024-01-19T00:00:00Z",
    "ends_at": "2024-01-20T05:00:00Z",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Update Announcement

PUT/api/status-page-settings/announcements/:id

Update an existing announcement

Path Parameters:

Parameter	Type	Description
`id`	UUID	Announcement ID

Request Body:

Same fields as create, all optional.

Request Example:

{
  "status": "archived"
}

Delete Announcement

DELETE/api/status-page-settings/announcements/:id

Delete an announcement

Path Parameters:

Parameter	Type	Description
`id`	UUID	Announcement ID

Success Response (200 OK):

{
  "success": true
}

Announcement Types

Type	Display	Use Case
`info`	Blue/neutral	General information
`warning`	Yellow/amber	Potential issues or degradation
`critical`	Red	Active incidents or outages
`maintenance`	Purple/special	Planned maintenance windows

Announcements automatically appear on your status page when starts_at is in the past and ends_at is in the future (or both are null for always-visible announcements).

Status Pages API

Public Endpoints

Get Public Status

Verify Password (Protected Status Page)

Get Public Postmortems

Widget Endpoints

Get Status Widget

Get Widget Embed Code

Status Page Settings

Get Settings

Update Settings

Upload Logo

Custom Domain

Verify Domain

Remove Custom Domain

Announcements

List Announcements

Create Announcement

Update Announcement

Delete Announcement

Announcement Types