How to Monitor Scalar with Vigilmon

Scalar is an open-source API documentation platform that generates interactive docs, a web API client, SDK stubs, and a mock server from your OpenAPI specification. It integrates with Hono, FastAPI, Nitro, Express, and 20+ other frameworks as middleware — meaning your Scalar docs live at the same domain as your API. When Scalar's UI goes down, developers can't explore your API, and when the mock server goes down, frontend teams lose their development environment. Vigilmon monitors every Scalar endpoint — the docs UI, the mock server, and the upstream spec file — so you catch outages before they block other teams.

What You'll Set Up

• HTTP uptime monitors for the Scalar docs UI endpoint
• HTTP monitors for the Scalar mock server
• HTTP monitors for the upstream OpenAPI spec file
• SSL certificate alerts for your API documentation domain
• Cron heartbeat monitors for automated SDK generation jobs

Prerequisites

• Scalar deployed as middleware in your API framework or as a standalone Docker container
• OpenAPI spec available at a public or internal URL
• A free Vigilmon account

Step 1: Monitor the Scalar Docs UI Endpoint

Scalar renders interactive API documentation at a URL you configure (typically /reference, /docs, or /api-reference). Add a Vigilmon monitor for it:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the docs URL: https://api.yourdomain.com/reference.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Optionally, set Expected response body contains: scalar to confirm the Scalar UI loaded (not a generic error page).
7. Click Save.

If your API server crashes or the Scalar middleware throws, this endpoint returns a 500 or times out — Vigilmon catches it and alerts before developers notice empty docs.

Step 2: Framework Integration and Health Endpoints

Scalar is embedded as middleware in your API server. Monitor the underlying server's health route to distinguish Scalar UI failures from server-level outages:

Hono

import { Hono } from 'hono'
import { apiReference } from '@scalar/hono-api-reference'

const app = new Hono()

app.get('/health', (c) => c.json({ status: 'ok' }))

app.get('/openapi.json', (c) => c.json(openApiSpec))

app.use('/reference', apiReference({
  spec: { url: '/openapi.json' },
}))

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get('/health')
def health():
    return {'status': 'ok'}

# Scalar replaces the default Swagger UI
from scalar_fastapi import get_scalar_api_reference

@app.get('/reference', include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(
        openapi_url=app.openapi_url,
        title=app.title,
    )

Express

import { apiReference } from '@scalar/express-api-reference'

app.get('/health', (req, res) => res.json({ status: 'ok' }))

app.use('/reference', apiReference({
  spec: { url: '/openapi.json' },
}))

Add a Vigilmon monitor for the /health route. A /reference failure with a healthy /health response points to a Scalar-specific configuration issue rather than a server crash.

Step 3: Monitor the OpenAPI Spec File

Scalar fetches the OpenAPI specification at render time (or bundles it at build time). If the spec URL goes down, the docs UI renders a blank or broken state. Monitor the spec endpoint directly:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter the spec URL: https://api.yourdomain.com/openapi.json or https://api.yourdomain.com/openapi.yaml.
3. Set Expected HTTP status to 200.
4. Set Expected response body contains: openapi (present in both JSON and YAML spec files).
5. Set Check interval to 5 minutes.
6. Click Save.

A stale or missing spec means Scalar docs show outdated endpoints. A missing spec URL means the docs load with no content at all.

Step 4: Monitor the Scalar Mock Server

Scalar's mock server spins up a local or hosted server that responds to API requests based on the OpenAPI spec — used by frontend developers while the real backend is in development. If the mock server goes down, frontend builds start failing against empty responses.

Standalone Scalar mock server (Docker)

docker run -p 9090:9090 \
  ghcr.io/scalar/mock-server:latest \
  --spec https://api.yourdomain.com/openapi.json

Add a monitor for it:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://mock.yourdomain.com:9090/health (or the root URL if there's no health route).
3. Set Expected HTTP status to 200.
4. Set Check interval to 1 minute.
5. Click Save.

Alternatively, probe a known mock endpoint — Scalar mock servers respond to any path defined in the spec:

https://mock.yourdomain.com/users

Set Expected HTTP status to 200 and Expected response body contains to [ (the start of a JSON array) if the endpoint returns a list.

Step 5: SSL Certificate Alerts for Documentation Domains

API documentation sites often have their own domain (docs.yourdomain.com, api.yourdomain.com) or subdomain. Add SSL monitoring for each:

1. Open the HTTP monitor created in Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

An expired certificate on your docs site is particularly visible — developers copy the API base URL from Scalar docs, and a TLS warning on the docs page immediately erodes trust in the whole API.

Step 6: Cron Heartbeat for Automated SDK Generation

Many teams trigger SDK generation from the Scalar CLI or @scalar/openapi-generator on a schedule (e.g., nightly to keep SDKs in sync with spec changes). Monitor these jobs with a heartbeat:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your schedule (e.g. 1440 minutes for daily SDK generation).
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/abc123.
4. Add the ping to your generation script:

#!/bin/bash
# Nightly SDK generation from Scalar
npx @scalar/openapi-generator \
  --input https://api.yourdomain.com/openapi.json \
  --output ./sdk/typescript \
  --generator typescript-fetch

if [ $? -eq 0 ]; then
  git -C ./sdk/typescript add -A
  git -C ./sdk/typescript commit -m "chore: regenerate SDK $(date +%Y-%m-%d)"
  git -C ./sdk/typescript push origin main
  curl -s https://vigilmon.online/heartbeat/abc123
fi

If the SDK generation fails (invalid spec, network error fetching the spec, git conflict), the heartbeat is never sent and you're alerted before the stale SDK causes downstream build failures.

Step 7: Configure Alert Channels and Thresholds

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook to notify the right team.
2. Route docs UI alerts to your developer experience (DevEx) channel.
3. Route mock server alerts to the frontend team channel.
4. Set Consecutive failures before alert to 2 for HTTP monitors.
5. Set Consecutive failures before alert to 1 for cron heartbeat monitors.

Use Vigilmon's status page feature to give frontend and partner teams a public status signal:

https://status.yourdomain.com

When the mock server or docs site is down, partners can check the status page instead of filing support tickets.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Scalar docs UI | https://api.yourdomain.com/reference | UI crash, middleware error | | Server health | https://api.yourdomain.com/health | Server-level outage | | OpenAPI spec | https://api.yourdomain.com/openapi.json | Missing or stale spec | | Mock server | http://mock.yourdomain.com:9090 | Frontend dev environment down | | SSL certificate | Each docs/API domain | TLS expiry | | SDK generation heartbeat | Heartbeat URL | Nightly SDK gen failure |

Scalar turns your OpenAPI spec into a developer portal — but that portal needs its own uptime guarantee. With Vigilmon watching the docs UI, mock server, spec endpoint, and SDK generation jobs, you ensure that the developer experience infrastructure your API depends on is as reliable as the API itself.