Documentation

Everything you need to know about Livstat.

Introduction

Livstat is a hosted status page and uptime monitoring service. It lets you communicate system health to your users and team in real time — without any infrastructure to manage.

What Livstat does

Feature Description
Public status pages Each project gets a page at yourproject.livstat.com or your own custom domain
Uptime monitoring Automated HTTP, TCP, SSL, and Heartbeat checks from up to 5 global regions
Incident management Auto-create and resolve incidents based on monitor state changes
Subscriber notifications Visitors can subscribe to email updates directly from the status page
Team notifications Alert your team via email, Slack, Discord, webhooks, or PagerDuty
Maintenance windows Pre-announce scheduled downtime to reduce inbound support

How it works

Your services  →  Livstat monitors  →  Status page
                       ↓
              Incident created / resolved
                       ↓
           Team & subscriber notifications sent
  1. You create components — logical parts of your product (e.g. "API", "Website", "Database")
  2. You attach monitors that ping those services automatically
  3. When a monitor detects a problem, Livstat creates an incident and marks the affected component as degraded or down
  4. Your status page updates instantly and notifications go out to your team and subscribers
  5. When the monitor recovers, the incident is resolved automatically

Key concepts

  • Project — one status page and its associated components, monitors, and settings
  • Component — a service or feature displayed on the status page (e.g. "Payment API")
  • Monitor — an automated check that measures whether a component is healthy
  • Incident — a public record of an outage or degradation, with a timeline of updates
  • Subscriber — a visitor who opted in to email notifications from your status page

Getting Started

Get your status page live in under 10 minutes.

Step 1 — Sign up

Go to livstat.com and sign up with your email, GitHub, or Google account. No credit card required for the Free plan.

Step 2 — Create a project

A project is one status page. After signing up you'll be guided through the setup wizard:

  1. Enter a project name (e.g. Acme Corp Status)
  2. Choose a slug — your page will be live at livstat.com/[slug] immediately
  3. Set your timezone (used for maintenance window scheduling)

Tip: Your slug cannot be changed later, so pick something stable like your company name.

Step 3 — Add components

Components are the services you want to display on the status page.

  1. Go to Components in the sidebar
  2. Click Add Component
  3. Enter a name (e.g. API, Website, Database, CDN)
  4. Optionally add a description
  5. Drag to reorder — the order on the status page matches what you set here

Step 4 — Add monitors

Monitors run automated checks and keep component status up to date.

  1. Go to Monitors in the sidebar
  2. Click Add Monitor
  3. Configure:
Field Description
Name Display name for this monitor
Type HTTP, TCP, or SSL — see Monitors for details
Target URL, host:port, or hostname
Component Which component this monitor tracks
Regions Where to run checks from
Interval How often to check (depends on your plan)

Step 5 — Configure notifications

Go to Settings → Notifications → Add Channel to receive alerts when a monitor changes status. Supported channels:

  • Email — any email address (all plans)
  • Slack — incoming webhook (Pro+)
  • Discord — channel webhook (Pro+)
  • Webhook — any HTTP endpoint (Pro+)
  • PagerDuty — events API v2 (Business)

Step 6 — Share your status page

Your status page is immediately live. Share it with customers or embed the URL in your app or support docs:

https://livstat.com/[your-slug]

On the Pro and Business plans you can use a custom domain like status.yourcompany.com — see Status Pages for setup instructions.

Status Pages

Your status page is a public-facing website that communicates the health of your services in real time.

Public URL

Every project has a page at:

https://livstat.com/[your-slug]

The page is live the moment you create a project — no additional setup required.

What visitors see

Section Description
Overall status A banner showing the worst current component status
Components Each component with its current status, 90-day uptime bar, and response time graph
Active incidents Live incidents with a timeline of status updates
Resolved incidents Incident history for the last 14 days, with post-mortem reports if published
Maintenance windows Upcoming or in-progress scheduled maintenance
Subscribe button Lets visitors sign up for email notifications

Component statuses

Status Color Meaning
Operational Green Everything working normally
Degraded Performance Yellow Service is slower than usual
Partial Outage Orange Some requests are failing
Major Outage Red Service is down
Under Maintenance Blue Scheduled maintenance in progress

Component groups

You can organize components into collapsible groups (e.g. "Infrastructure", "Frontend", "APIs") for a cleaner status page.

Managing groups

  1. Go to the Components page in your project dashboard
  2. Click New Group to create a group — give it a name like "Infrastructure"
  3. Edit any component and select a group from the Group dropdown
  4. Drag group headers to reorder groups; drag components to reorder within a group

How groups appear on the public page

  • Each group renders as a collapsible section with a header showing the group name and an aggregated status dot
  • The status dot reflects the worst status of any component in the group
  • Visitors can click the group header to expand or collapse the section (expanded by default)
  • Components that aren't assigned to any group appear below the groups in a flat list, just like before

API

Groups are also available through the REST API:

  • GET /api/v1/component-groups — list all groups
  • POST /api/v1/component-groups — create a group ({ "name": "Infrastructure" })
  • PATCH /api/v1/component-groups/:id — update name or sort order
  • DELETE /api/v1/component-groups/:id — delete a group (components become ungrouped)

Components include a groupId field that you can set when creating or updating via the API.

Custom domain

On the Pro and Business plans you can serve your status page from your own domain (e.g. status.yourcompany.com):

  1. Go to Settings → Domain in your project
  2. Enter your domain name (e.g. status.yourcompany.com)
  3. Add a CNAME record at your DNS provider:
status.yourcompany.com  →  CNAME  →  custom.livstat.com
  1. Click Verify — Livstat will automatically provision a TLS certificate (usually within a few minutes)

Note: DNS changes can take up to 24 hours to propagate, though most providers apply them within minutes.

90-day uptime bars

Each component with a linked monitor displays a 90-day uptime bar — a row of colored squares, one per day (oldest on the left, today on the right). Hover over any square to see the date and uptime percentage.

Color Meaning
Green 95%+ uptime
Yellow 80–95% uptime
Red Below 80% uptime
Gray No data

Response time graph

Components with HTTP monitors also show a 30-day response time graph — an area chart displaying the average response time trend. This helps visitors quickly see if performance has been degrading over time.

Open Graph preview

Every status page has a dynamic Open Graph image (used when sharing the link on social media, Slack, etc.). The image shows the project name, current overall status, and the top components with their statuses.

Branding

  • Free & Pro: Livstat badge appears at the bottom of the page
  • Business: Remove the Livstat badge, set a custom brand color and logo, and inject custom CSS to fully match your brand

Configure branding in Settings → Appearance.

Embedding a status badge

You can embed a dynamic status badge in your own website or documentation — see the Badges & Embeds section for details.

Monitors

Monitors run automated checks from multiple global regions and automatically update component status when something goes wrong.

Monitor types

Type What it checks Example target
HTTP Sends a GET/HEAD request and checks the response code https://api.example.com/health
TCP Opens a TCP connection to a host and port db.example.com:5432
SSL Verifies certificate validity and checks expiry date example.com
Heartbeat Waits for your service to ping a unique URL within a grace period https://livstat.com/api/v1/heartbeat/TOKEN

HTTP monitor options

Option Default Description
Expected status 2xx Any HTTP status code you expect (e.g. 200, 301)
Keyword match — Optional string to check in the response body
Timeout 10 s Request timeout in seconds
Follow redirects Yes Whether to follow HTTP redirects

Keyword check

You can verify the response body contains (or does not contain) a specific string:

  • Must contain — the monitor reports down if the keyword is missing from the response body
  • Must not contain — the monitor reports down if the keyword is found in the response body

This is useful for catching soft errors — for example, if your health endpoint returns 200 OK but the body says "status":"error".

Heartbeat monitors (dead man's switch)

Heartbeat monitors work in reverse — instead of Livstat pinging your service, your service pings Livstat at a regular interval. If Livstat doesn't receive a ping within the grace period, the monitor is marked as down.

This is ideal for:

  • Cron jobs — verify that scheduled tasks actually run
  • Background workers — confirm queue processors are alive
  • Batch processes — ensure nightly imports complete on time

Setup

  1. Create a monitor and select type Heartbeat
  2. Set a grace period (e.g. 5 minutes) — how long to wait before marking as down
  3. Copy the unique ping URL shown after creation
  4. Add a call to that URL at the end of your job:
# Example: at the end of a cron job
curl -s https://livstat.com/api/v1/heartbeat/YOUR_TOKEN

The endpoint accepts both GET and POST requests. No authentication header is needed — the token in the URL is the credential.

Advanced settings

Click Advanced Settings on the monitor form to access additional options. A green dot on the button indicates that advanced settings have been configured.

Response time thresholds

Configure per-monitor thresholds to detect slow responses:

Threshold Effect Example
Warn Status becomes degraded when response time exceeds this value 1000 ms
Fail Status becomes down when response time exceeds this value 5000 ms

If no warn threshold is set, a default of 2000 ms is used for the degraded threshold.

Custom request headers

Add custom HTTP headers to the request — useful for API endpoints that require authentication tokens, custom User-Agent strings, or specific Accept types. Headers are sent as key-value pairs.

Custom request body

For POST and PUT monitors, you can provide a custom request body. This is useful for health-check endpoints that expect a specific JSON payload.

Monitoring regions

Checks run from up to 5 global locations:

Region Location Available on
EU Central Frankfurt, Germany All plans
US East Miami, USA Pro + Business
US West Los Angeles, USA Pro + Business
Asia Singapore Singapore Business
Australia Sydney Sydney, Australia Business

More regions = higher accuracy. A failure is only declared when a majority of active regions report the same result, which eliminates false positives from regional network hiccups.

Check intervals

Plan Minimum interval
Free 5 minutes
Pro 1 minute
Business 30 seconds

Consensus logic

When multiple regions monitor the same target, Livstat uses majority consensus:

  • A component is marked down only when more than half of the active regions report failure
  • A component is marked recovered when more than half report success

This means a single region having a network issue will not trigger a false incident.

Monitor limits per plan

Plan Monitors
Free 5
Pro 20
Business 50

Disabling a monitor

You can pause a monitor from the Monitors page without deleting it. Paused monitors do not run checks and do not affect component status.

Incidents

Incidents are the public record of outages and issues. They appear on your status page with a live timeline so users always know what's happening and what's being done about it.

Automatic vs manual incidents

Type When it's created When it resolves
Automatic Monitor detects a component is down Monitor detects recovery
Manual You create it from the dashboard You resolve it manually

Use manual incidents for issues not covered by monitors — for example, a third-party dependency problem or a data issue that doesn't affect HTTP responses.

Severity levels

Severity When to use
Critical Complete service outage — nothing is working
Major Significant functionality is unavailable for most users
Minor Non-critical issues, slow performance, partial errors
Maintenance Prefer using a Maintenance Window instead

Creating a manual incident

  1. Go to Incidents in the sidebar
  2. Click New Incident
  3. Fill in:
    • Title — short description visible on the status page (e.g. Payment processing delays)
    • Severity — see table above
    • Affected components — which components are impacted
    • Initial message — what you know right now

Posting updates

Keep users informed as the situation evolves:

  1. Open the incident → click Add Update
  2. Choose the update status:
Status Use when
Investigating You're aware of the issue and looking into it
Identified You know the root cause
Monitoring Fix applied, watching to confirm stability
Resolved Issue is fully resolved
  1. Write a message — it will appear on the public timeline with a timestamp

Resolving an incident

  • Automatic incidents resolve on their own when the monitor returns to operational
  • Manual incidents require you to post a final update with status Resolved

Once resolved, the incident stays visible in the history on your status page (subscribers can see the full timeline for transparency).

Incident templates

If you frequently create similar incidents, save time with templates:

  1. Go to Incidents → click Templates
  2. Create a template with a name, title, message, and severity
  3. When creating a new incident, select a template from the Load from template dropdown — it pre-fills the title, message, and severity fields

Templates are per-project and can be edited or deleted at any time.

Post-mortem reports

After resolving an incident, you can write a post-mortem to document what happened and what you're doing to prevent it in the future:

  1. Find the resolved incident in the Resolved section and expand it
  2. Click Write Post-mortem
  3. A markdown editor opens, pre-filled with a template:
    • Root Cause — what caused the issue
    • Timeline — auto-generated from the incident's update history
    • Action Items — steps to prevent recurrence
  4. Use the Write / Preview toggle to switch between editing and rendered preview
  5. Click Save Post-mortem

Post-mortems are written in Markdown and rendered on the public status page. Visitors can expand any resolved incident in the history section to read the full post-mortem.

Incident history

All incidents are stored permanently. Visitors to your status page can browse the full incident history — including timelines and post-mortems — which helps build trust by demonstrating transparency.

Notifications

Livstat sends alerts to your team when a monitor changes status. Configure notification channels under Settings → Notifications.

Channel types

Email — all plans

Sends an HTML email to any address when a monitor changes status.

  • Go to Add Channel → Email
  • Enter the destination address (e.g. ops@yourcompany.com)
  • You can add multiple email channels for different team members or mailing lists

Slack — Pro and Business

Posts a formatted message to a Slack channel via Incoming Webhook.

Setup steps:

  1. In Slack, go to Apps → Incoming Webhooks
  2. Click Add to Slack, choose a channel, and click Allow
  3. Copy the webhook URL (it starts with https://hooks.slack.com/services/...)
  4. Paste it into Livstat when adding the Slack channel

Discord — Pro and Business

Posts a message to a Discord channel via webhook.

Setup steps:

  1. In Discord, open the channel you want notifications in
  2. Go to Edit Channel → Integrations → Webhooks → New Webhook
  3. Copy the webhook URL (it starts with https://discord.com/api/webhooks/...)
  4. Paste it into Livstat when adding the Discord channel

Webhook — Pro and Business

Sends a POST request with a JSON payload to any HTTP endpoint. Use this to integrate with custom systems, ITSM tools, or scripts.

Payload format:

{
  "monitorId": "mon_abc123",
  "componentId": "cmp_xyz456",
  "componentName": "Payment API",
  "newStatus": "major_outage",
  "previousStatus": "operational",
  "timestamp": "2026-01-01T12:00:00Z"
}

Available status values: operational, degraded_performance, partial_outage, major_outage, under_maintenance

PagerDuty — Business plan only

Automatically creates and resolves PagerDuty alerts using the Events API v2.

Setup steps:

  1. In PagerDuty, create a new Service (or use an existing one)
  2. Add an Events API v2 integration to the service
  3. Copy the Integration Key (also called Routing Key)
  4. Paste it into Livstat when adding the PagerDuty channel

Livstat uses dedup_key = livstat_monitor_{id} so alerts auto-resolve correctly when the monitor recovers.

Subscriber notifications

In addition to team channels, visitors to your status page can subscribe to receive email notifications:

  • They click Subscribe on your public status page and enter their email
  • They receive an email whenever an incident starts, is updated, or is resolved
  • They can unsubscribe at any time via a link in any notification email

Manage your subscriber list under Subscribers in the sidebar.

Notification limits per plan

Plan Team notification channels
Free Email only
Pro Email, Slack, Discord, Webhook
Business All channels including PagerDuty

REST API

Livstat exposes a REST API for programmatic access to your status pages, monitors, and incidents.

Available on: Pro and Business plans

Base URL

https://livstat.com/api/v1/

Interactive documentation

Full interactive API docs (Swagger UI) are available at:

livstat.com/api/docs

You can try every endpoint directly in the browser.

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Generate and manage API keys under Settings → API Keys in the dashboard. You can create multiple keys with different names (e.g. one per integration) and revoke them individually.

Keep your API keys secret. Do not commit them to version control. Rotate a key immediately if you believe it has been compromised.

Endpoints overview

Components

Method Path Description
GET /api/v1/components List all components
POST /api/v1/components Create a new component
GET /api/v1/components/:id Get a single component
PATCH /api/v1/components/:id Update a component
DELETE /api/v1/components/:id Delete a component

Component Groups

Method Path Description
GET /api/v1/component-groups List all groups
POST /api/v1/component-groups Create a group
PATCH /api/v1/component-groups/:id Update a group
DELETE /api/v1/component-groups/:id Delete a group

Monitors

Method Path Description
GET /api/v1/monitors List all monitors
GET /api/v1/monitors/:id Get a single monitor
POST /api/v1/monitors Create a monitor
PATCH /api/v1/monitors/:id Update a monitor
DELETE /api/v1/monitors/:id Delete a monitor

Incidents

Method Path Description
GET /api/v1/incidents List incidents
GET /api/v1/incidents/:id Get a single incident
POST /api/v1/incidents Create a manual incident
PATCH /api/v1/incidents/:id Update an incident
DELETE /api/v1/incidents/:id Delete an incident
POST /api/v1/incidents/:id/updates Add a timeline update

Scheduled Maintenance

Available on: Pro and Business plans

Method Path Description
GET /api/v1/maintenance List maintenance windows
GET /api/v1/maintenance/:id Get a single maintenance window
POST /api/v1/maintenance Schedule a maintenance window
PATCH /api/v1/maintenance/:id Update a maintenance window
DELETE /api/v1/maintenance/:id Delete a maintenance window

Heartbeat

Method Path Description
GET or POST /api/v1/heartbeat/:token Send a heartbeat ping (no auth header needed)

Rate limits

Requests are rate-limited per API key:

Plan Limit
Free — (no API access)
Pro 300 requests / minute
Business 1,000 requests / minute

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

Example: create a monitor

curl -X POST https://livstat.com/api/v1/monitors \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Health",
    "type": "http",
    "url": "https://api.example.com/health",
    "interval": 60,
    "regions": ["eu-central", "us-east"]
  }'

Example: schedule a maintenance window

curl -X POST https://livstat.com/api/v1/maintenance \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database upgrade",
    "description": "Upgrading PostgreSQL to v17. Expect 15 minutes of downtime.",
    "scheduledStart": "2026-03-10T02:00:00Z",
    "scheduledEnd": "2026-03-10T03:00:00Z",
    "componentIds": ["cmp_abc123"]
  }'

Example: create an incident

curl -X POST https://livstat.com/api/v1/incidents \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated error rates on Payment API",
    "severity": "major",
    "componentIds": ["cmp_abc123"]
  }'

Example: add an incident update

curl -X POST https://livstat.com/api/v1/incidents/inc_xyz/updates \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "identified",
    "message": "Root cause identified — deploying hotfix now."
  }'

Plans & Billing

Livstat offers three plans. All plans include unlimited status page views and automatic TLS certificates.

Plan comparison

Feature Free Pro Business
Price $0 $19 / mo $39 / mo
Projects 1 3 10
Components 5 20 50
Monitors 5 20 50
Email subscribers 100 1,000 5,000
Team members 1 5 20
Monitoring regions 1 (EU) 3 5 (all)
Check interval 5 min 1 min 30 sec
Uptime history 30 days 365 days 365 days
Custom domain — ✓ ✓
Slack / Discord / Webhook — ✓ ✓
Email channel — ✓ ✓
PagerDuty — — ✓
REST API access — ✓ ✓
MCP integration — ✓ ✓
Maintenance windows — ✓ ✓
Heartbeat monitors — ✓ ✓
Incident templates ✓ ✓ ✓
Post-mortem reports ✓ ✓ ✓
Remove Livstat branding — — ✓
Custom CSS — — ✓

Free plan

Perfect for personal projects, side projects, or trying out Livstat. Includes:

  • 1 project with a livstat.com/[slug] page
  • Monitoring from EU Central (Frankfurt)
  • Up to 100 email subscribers
  • 30-day uptime history

Pro — $19 / month

For small teams and growing products:

  • 3 projects with custom domain support
  • Monitoring from 3 regions (EU, US East, US West)
  • 1-minute check interval for faster incident detection
  • Heartbeat monitors (dead man's switch for cron jobs)
  • Slack, Discord, Webhook, and Email notifications
  • REST API and MCP integration
  • Maintenance windows
  • 365-day uptime history

Business — $39 / month

For companies where uptime is business-critical:

  • 10 projects
  • Monitoring from all 5 global regions
  • 30-second check interval
  • PagerDuty integration
  • Custom brand color, logo, and CSS
  • Remove Livstat branding from status pages

Upgrading

Go to Settings → Billing in the dashboard to upgrade your plan. Payments are handled securely by Stripe.

When you upgrade mid-cycle, you are charged a prorated amount for the remainder of the billing period.

Cancelling

You can cancel at any time from Settings → Billing. Your plan remains active until the end of the current billing period. After that, your account downgrades to the Free plan — your data is not deleted.

Invoices and receipts

All invoices are available in Settings → Billing → Invoice history. Stripe sends an email receipt after every successful payment.

Questions?

Contact us at support@livstat.com for billing questions or to discuss volume pricing.

Badges & Embeds

Livstat provides two embeddable formats so you can show your service's real-time status anywhere — GitHub READMEs, your own website, or your app's footer.

Status Badges (SVG)

A shields.io-style SVG badge that shows the current overall status of your project (or a specific component).

URL format

https://<slug>.livstat.com/<slug>/badge

Or with a custom domain:

https://status.yoursite.com/<slug>/badge

Query parameters

Parameter Description Example
(none) Overall project status …/badge
component Status of a specific component (use the component UUID) …/badge?component=abc-123

Embed in a GitHub README

![Status](https://yourslug.livstat.com/yourslug/badge)

Or as a clickable badge that links to your status page:

[![Status](https://yourslug.livstat.com/yourslug/badge)](https://yourslug.livstat.com)

Per-component badge

Find the component ID in the URL when editing a component, or via the API.

[![API](https://yourslug.livstat.com/yourslug/badge?component=<component-id>)](https://yourslug.livstat.com)

Badge colors

Status Color
Operational Green
Degraded Yellow
Partial Outage Orange
Major Outage Red
Maintenance Blue

Badges are cached for 60 seconds (Cache-Control: public, max-age=60, stale-while-revalidate=300).

Embeddable Widget (JavaScript)

A lightweight JS snippet that renders a clickable status badge on your own website. No iframe, no external fonts, no tracking — just a single <script> tag.

Embed snippet

<script src="https://yourslug.livstat.com/yourslug/widget" async></script>

The widget appends itself to document.body by default. To control placement, add a data-livstat attribute to any element:

<div data-livstat></div>
<script src="https://yourslug.livstat.com/yourslug/widget" async></script>

Light theme

By default the widget uses a dark theme. Pass ?theme=light for a light background:

<script src="https://yourslug.livstat.com/yourslug/widget?theme=light" async></script>

What it renders

The widget renders a small inline element showing:

● Your Project Name  ·  All Systems Operational  livstat
  • The dot color matches the current status (green / yellow / orange / red / blue)
  • The status label is human-readable
  • Clicking the widget opens your full status page in a new tab

Technical details

  • Status data is embedded server-side in the script response — no client-side API calls
  • The script is ~1 KB (uncompressed)
  • Cached for 60 seconds
  • Works in all modern browsers; no dependencies

API Quickstart

Get up and running with the Livstat API in under 5 minutes.

Available on: Pro and Business plans

1. Generate an API key

  1. Go to Settings → API Keys in your dashboard
  2. Click New Key, give it a name (e.g. my-integration), and click Create
  3. Copy the key — it starts with sk_live_ and is shown only once

Store it securely (environment variable, secrets manager). Never commit it to version control.

2. Make your first request

All requests go to:

https://livstat.com/api/v1/

Pass your key as a Bearer token:

curl https://livstat.com/api/v1/components \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx"

A successful response looks like:

[
  {
    "id": "cmp_abc123",
    "name": "API",
    "status": "operational",
    "description": "REST API endpoints"
  },
  {
    "id": "cmp_def456",
    "name": "Dashboard",
    "status": "degraded",
    "description": null
  }
]

3. Update a component status

curl -X PATCH https://livstat.com/api/v1/components/cmp_abc123 \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "degraded"}'

Valid status values: operational, degraded, partial, major, maintenance

4. Create a manual incident

curl -X POST https://livstat.com/api/v1/incidents \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated error rates on Payment API",
    "severity": "major",
    "message": "We are investigating reports of elevated error rates.",
    "componentIds": ["cmp_abc123"]
  }'

Valid severity values: minor, major, critical

5. Post an incident update

Keep your subscribers informed by posting updates as the situation evolves:

curl -X POST https://livstat.com/api/v1/incidents/INC_ID/updates \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "identified",
    "message": "Root cause identified. Rolling back the problematic deployment now."
  }'

Valid status values: investigating, identified, monitoring, resolved

Setting status to resolved will close the incident and send recovery notifications to subscribers.

6. Resolve the incident

curl -X POST https://livstat.com/api/v1/incidents/INC_ID/updates \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "message": "The rollback is complete. All systems are back to normal."
  }'

Rate limits

API requests are rate-limited per key, based on your plan:

Plan Limit
Free No API access
Pro 300 requests / minute
Business 1,000 requests / minute

Every successful response includes rate limit headers:

Header Description
X-RateLimit-Limit Max requests per minute for your plan
X-RateLimit-Remaining Requests remaining in current window
X-RateLimit-Reset Unix timestamp when the window resets

When you exceed the limit, you'll receive a 429 response with a Retry-After header (seconds until reset).

Error codes

Code Meaning
401 Missing or invalid API key
403 API access not available on your plan — upgrade to Pro or Business
404 Resource not found
422 Validation error (check the error field in the response)
429 Rate limit exceeded — see Retry-After header

Interactive docs

Try every endpoint directly in the browser at livstat.com/api/docs — no code needed.

Webhook Payload Reference

When you add a Webhook notification channel, Livstat sends an HTTP request to your endpoint every time a monitor changes status in a notable way (going down or recovering).

When webhooks fire

Webhooks are sent on two transitions only:

Transition Description
operational → anything else Monitor went down
anything → operational Monitor recovered

Non-notable transitions (e.g. degraded → major) are not sent — only the first failure and the final recovery matter.

Request format

POST https://your-endpoint.example.com/livstat-hook
Content-Type: application/json

The HTTP method (POST, PUT, etc.) is whatever you configured in your notification channel settings. The request always has Content-Type: application/json.

Payload structure

{
  "event": "status.changed",
  "data": {
    "monitorId":      "550e8400-e29b-41d4-a716-446655440000",
    "componentId":    "7f3c2a10-4b5e-4d6f-9c2a-1234567890ab",
    "projectId":      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "previousStatus": "operational",
    "newStatus":      "major",
    "roundId":        "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "timestamp":      "2026-02-22T10:15:30.000Z"
  }
}

Fields

Field Type Description
event string Always "status.changed"
data.monitorId string (UUID) The monitor that changed
data.componentId string | null The linked component, if any
data.projectId string (UUID) Your project
data.previousStatus string Status before the change
data.newStatus string Status after the change
data.roundId string (UUID) The check round that triggered this
data.timestamp string (ISO 8601) UTC time of the status change

Status values

operational · degraded · partial · major · maintenance

Recovery example

{
  "event": "status.changed",
  "data": {
    "monitorId":      "550e8400-e29b-41d4-a716-446655440000",
    "componentId":    "7f3c2a10-4b5e-4d6f-9c2a-1234567890ab",
    "projectId":      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "previousStatus": "major",
    "newStatus":      "operational",
    "roundId":        "1a2b3c4d-5e6f-7890-abcd-fedcba987654",
    "timestamp":      "2026-02-22T11:02:45.000Z"
  }
}

Requirements & limits

Requirement Value
Protocol HTTPS only
Private/internal IPs Blocked (SSRF protection)
Timeout 10 seconds
Retries None — delivery is best-effort

Your endpoint should return a 2xx status code. Non-2xx responses are logged as failures but do not trigger retries.

Verifying the request

Livstat does not currently sign webhook payloads. To secure your endpoint:

  • Restrict access by IP (Livstat sends from your worker server IPs — see your dashboard)
  • Use a secret path (e.g. /hooks/livstat/your-secret-token)
  • Validate the Content-Type: application/json header

Quick handler example (Node.js)

app.post('/livstat-hook', express.json(), (req, res) => {
  const { event, data } = req.body;

  if (event === 'status.changed') {
    const isDown = data.newStatus !== 'operational';
    console.log(
      isDown
        ? `⚠️  Monitor ${data.monitorId} went ${data.newStatus}`
        : `✅  Monitor ${data.monitorId} recovered`
    );
  }

  res.sendStatus(200);
});

MCP Integration (Claude AI)

Connect Livstat to claude.ai, Claude Desktop, or Claude Code via the Model Context Protocol (MCP). Manage your status page — create incidents, update components, check monitors — using natural language.

Available on: Pro and Business plans

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude interact with external tools and services. Livstat provides both a ready-to-use plugin and a remote MCP server, so you can connect Claude in seconds.

Prerequisites

  • Pro or Business plan (API access required)
  • API key generated from Settings → API Keys

Setup

Option 1: Download Plugin (Easiest)

The fastest way to connect Claude — a pre-configured plugin with your API key built in.

  1. Go to Settings → API Keys and create a new key
  2. Click Download Claude Plugin (appears after key creation)
  3. Open claude.ai → Customize → Browse Plugins
  4. Go to the Personal tab → click + → Upload plugin
  5. Select the downloaded .zip file — done!

The plugin is a standard .zip archive containing a self-contained MCP server (Node.js 18+, zero dependencies) and works immediately.

Option 2: Remote MCP Connector

Connect Claude to the hosted MCP server — no local installation needed.

  1. Open claude.ai and go to Settings → Connectors
  2. Scroll down and click Add custom connector
  3. Enter the URL: https://livstat.com/mcp
  4. In Advanced settings, add the authorization header with your Livstat API key
  5. Click Add

Note: The claude.ai web interface uses an OAuth-like flow for connectors. If bearer token authorization is not supported in the web UI, use the plugin method above or Claude Desktop/Code instead.

Claude Desktop

Add the following to your Claude Desktop config file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "livstat": {
      "type": "streamable-http",
      "url": "https://livstat.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Option A: Install the plugin (recommended — includes skill prompts + MCP server)

  1. Download the .zip file from Settings → API Keys
  2. Unzip it to a folder (e.g., ~/livstat-plugin)
  3. Run:
claude --plugin-dir ~/livstat-plugin

Or install permanently:

claude plugin install ~/livstat-plugin

Option B: Remote MCP server (no local files needed)

Add to your project's .mcp.json (or ~/.claude/.mcp.json for global config):

{
  "mcpServers": {
    "livstat": {
      "type": "streamable-http",
      "url": "https://livstat.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Option C: One-liner (quickest, adds remote MCP via CLI)

claude mcp add livstat --transport streamable-http \
  --url https://livstat.com/mcp \
  --header "Authorization: Bearer sk_live_your_key_here"

Available tools

Tool Description
get_status_summary Full project overview: components, incidents, monitors, plan
get_plan_info Current plan tier and rate limit usage
list_components List all components with statuses
create_component Create a new component
update_component Update component name, description, status, or group
delete_component Delete a component
list_component_groups List all component groups
create_component_group Create a new group
update_component_group Rename or reorder a group
delete_component_group Delete a group
list_incidents List incidents (optionally filter by active/resolved)
get_incident Get incident with full timeline
create_incident Create a new incident
update_incident Update incident metadata
delete_incident Delete an incident
add_incident_update Add a timeline update to an incident
list_monitors List all monitors (read-only)

Example conversations

Check current status:

"What's the current status of my Livstat project?"

Claude calls get_status_summary and presents a formatted overview of all components, active incidents, and monitor health.

Create an incident:

"Our payment API is returning 500 errors. Create a major incident."

Claude calls create_incident with title "Payment API returning 500 errors", severity "major", and an initial message.

Update during an incident:

"We found the root cause — it's a database connection pool issue. Update the incident."

Claude calls add_incident_update with the message and transitions status to "identified".

Resolve an incident:

"The fix is deployed and confirmed working. Resolve the payment incident."

Claude calls add_incident_update with status "resolved" and a resolution message.

Manage components:

"Set the Database component status to degraded."

Claude calls update_component with the component ID and status "degraded".

Plan awareness

The MCP server automatically detects your plan tier from API rate limit headers. When Claude encounters:

  • 403 Forbidden — suggests upgrading from Free to Pro or Business
  • 429 Rate Limited — shows current limits and suggests upgrading if on Pro

Ask Claude "What plan am I on?" and it will call get_plan_info to show your tier, rate limit, and what the next plan offers.

Advanced: Local STDIO mode

The downloaded plugin already uses a local STDIO server. If you want to configure it manually in Claude Desktop or Claude Code:

{
  "mcpServers": {
    "livstat": {
      "command": "node",
      "args": ["/path/to/livstat-mcp-server.mjs"],
      "env": {
        "LIVSTAT_API_KEY": "sk_live_your_key_here",
        "LIVSTAT_BASE_URL": "https://livstat.com"
      }
    }
  }
}

The server is self-contained (zero npm dependencies) and requires Node.js 18+.

Troubleshooting

Missing Authorization header

Make sure your config includes the headers block with Authorization: Bearer sk_live_.... Generate a key at Settings → API Keys.

API access is not available on your current plan

You're on the Free plan. Upgrade to Pro ($19/mo) or Business ($39/mo) at Settings → Billing.

Rate limit exceeded

You've hit the per-minute rate limit (Pro: 300/min, Business: 1000/min). Wait for the window to reset or upgrade your plan.

Claude doesn't show Livstat tools

  1. Verify the URL is https://livstat.com/mcp
  2. Check that the Authorization header includes your API key
  3. Restart Claude Desktop / Claude Code after config changes