tutorial

Uptime Monitoring for Mintlify Documentation Infrastructure 2026

Mintlify hosts your docs but won't alert you when your custom domain or embedded content breaks. Add external uptime monitoring, API health checks, and instant alerts in under 30 minutes — free.

Uptime Monitoring for Mintlify Documentation Infrastructure 2026

Mintlify is the hosted documentation platform built for developer-facing products — clean design, MDX support, OpenAPI reference generation, and zero-config deployment. Your team writes docs in Git; Mintlify handles the rest.

But "Mintlify handles it" doesn't mean nothing can go wrong. Your custom domain, your embedded API playground, the third-party services Mintlify calls on your behalf — all of these are outside Mintlify's direct control. External monitoring catches what Mintlify's own uptime tracking misses.

By the end of this guide you'll have independent uptime monitoring on your Mintlify-hosted docs, API health monitoring for the product your docs describe, and instant alerts when users can't reach your documentation — all on the free tier.

What Mintlify doesn't monitor for you

Mintlify monitors its own platform and shows status at mintlify.com/status. What it doesn't do:

  • Monitor your custom domain configuration — DNS misconfiguration or certificate issues affect only you
  • Alert you when your API (the one your docs reference) goes down — broken API examples hurt the docs experience
  • Notify you when the OpenAPI spec your docs pull from changes unexpectedly
  • Alert you when Mintlify platform issues affect only your subdomain, not the broader platform
  • Monitor embedded content (Loom videos, CodeSandbox embeds, third-party widgets) that can 404 independently

Step 1: Monitor your Mintlify custom domain

Every Mintlify project serves on a *.mintlify.app subdomain by default. If you've configured a custom domain (e.g. docs.yourdomain.com), that custom domain is what your users — and your marketing site, your README, your getting-started emails — all point to. A misconfigured DNS record or expired SSL cert on your custom domain is a hard outage your users hit before Mintlify does.

Sign up at Vigilmon — free tier, no credit card required.

  1. Click New Monitor → HTTP
  2. Enter your custom docs domain (e.g. https://docs.yourdomain.com)
  3. Set check interval to 5 minutes
  4. Add a Keyword match — paste the title of your docs homepage or a string that only appears in your content
  5. Save

The keyword match catches the case where your custom domain resolves (200) but is serving Mintlify's default 404 page or a DNS parking page — both are a real outage from your users' perspective.

Also add your Mintlify subdomain as a secondary monitor:

https://your-project.mintlify.app

If your custom domain monitor fires but the .mintlify.app monitor is fine, the issue is your DNS/SSL, not Mintlify. This two-monitor pattern narrows the blast radius in seconds.

Step 2: Monitor the API your docs describe

Mintlify's OpenAPI integration lets users try your API live from the docs. If your API is down, the interactive playground breaks — users get errors while following your getting-started guide, right when you want them to have a good experience.

Add a health endpoint to your API and monitor it independently:

Express / Node.js:

// routes/health.js
const router = require('express').Router();
const db = require('../db');

router.get('/health', async (req, res) => {
  try {
    await db.raw('SELECT 1');
    res.json({ status: 'ok', service: 'api' });
  } catch (err) {
    res.status(503).json({ status: 'error', detail: err.message });
  }
});

module.exports = router;

FastAPI / Python:

from fastapi import FastAPI
from sqlalchemy import text

app = FastAPI()

@app.get("/health")
async def health(db: AsyncSession = Depends(get_db)):
    try:
        await db.execute(text("SELECT 1"))
        return {"status": "ok"}
    except Exception as e:
        return JSONResponse(status_code=503, content={"status": "error", "detail": str(e)})

In Vigilmon, add an HTTP monitor for https://api.yourdomain.com/health. Route its alerts to your engineering channel — when the docs playground breaks, engineering needs to know, not just the docs team.

Step 3: Monitor your OpenAPI spec endpoint

If Mintlify pulls your OpenAPI spec from a URL (common for teams who generate the spec on CI), that spec endpoint is another dependency to monitor.

A spec endpoint returning an error means Mintlify can't regenerate your API reference — new endpoints and changes don't appear in the docs until the spec is accessible again.

In Vigilmon:

  1. New Monitor → HTTP
  2. URL: https://api.yourdomain.com/openapi.json (or wherever your spec is hosted)
  3. Add a Keyword match on "openapi" — all valid OpenAPI 3.x specs contain this string
  4. Save

This gives you early warning before your docs fall out of sync with your actual API.

Step 4: Heartbeat monitoring for your docs sync pipeline

If you use Mintlify's GitHub integration, every push to your docs branch triggers a redeploy. If GitHub Actions or your CI pipeline stops triggering, your docs go stale. Add a heartbeat monitor to catch a broken sync:

In Vigilmon:

  1. Click New Monitor → Heartbeat
  2. Set the expected interval (e.g. 25 hours if you expect at least one docs commit per day)
  3. Copy the ping URL

Add a heartbeat ping to your docs publish workflow:

# .github/workflows/docs-sync.yml
name: Sync Mintlify Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'openapi/**'
      - 'mint.json'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate mint.json
        run: |
          node -e "JSON.parse(require('fs').readFileSync('mint.json', 'utf8'))"

      - name: Validate OpenAPI spec
        run: npx @redocly/cli lint openapi/openapi.yaml

      - name: Ping heartbeat on success
        if: success()
        run: curl -s "${{ secrets.MINTLIFY_SYNC_HEARTBEAT_URL }}"

Add MINTLIFY_SYNC_HEARTBEAT_URL as a repository secret. Now if docs commits stop flowing to Mintlify — broken workflow, bad spec validation, missing secret — you'll know before users notice stale content.

Step 5: Validate mint.json on every change

Mintlify's configuration lives in mint.json. An invalid mint.json breaks the entire docs deployment. Add validation before the sync step:

// scripts/validate-mint-config.mjs
import { readFileSync } from 'fs';

const config = JSON.parse(readFileSync('mint.json', 'utf8'));

const requiredFields = ['name', 'navigation'];
const missing = requiredFields.filter(f => !config[f]);

if (missing.length > 0) {
  console.error(`mint.json is missing required fields: ${missing.join(', ')}`);
  process.exit(1);
}

// Validate navigation pages exist
function checkPages(items, prefix = '') {
  for (const item of items) {
    if (typeof item === 'string') {
      const path = `docs/${item}.mdx`;
      try {
        readFileSync(path);
      } catch {
        console.error(`Navigation references missing file: ${path}`);
        process.exit(1);
      }
    } else if (item.pages) {
      checkPages(item.pages);
    }
  }
}

for (const group of config.navigation) {
  if (group.pages) checkPages(group.pages);
}

console.log('mint.json is valid');

Run this in CI before Mintlify syncs. A navigation entry pointing to a deleted page fails silently in Mintlify — this script makes the failure loud.

Step 6: Webhook alerts

Slack:

  1. Create an incoming webhook at api.slack.com/messaging/webhooks
  2. In Vigilmon: Notifications → New Channel → Slack
  3. Paste the webhook URL and assign it to your Mintlify monitors

Discord:

  1. Server Settings → Integrations → Webhooks → New Webhook → Copy URL
  2. In Vigilmon: Notifications → New Channel → Discord
  3. Paste and assign to monitors

Route docs domain alerts to a #docs-alerts channel; API health alerts to your #engineering or #on-call channel. Different monitors, different audiences.

Step 7: Public status page

When your docs are down, users will ask in Slack, Discord, or GitHub Issues. A status page answers the question before they need to ask.

  1. In Vigilmon: Status Pages → New Status Page
  2. Add your custom domain monitor and API health monitor
  3. Save

Link the status page from your Mintlify footer. In mint.json:

{
  "footerSocials": {
    "website": "https://yourdomain.com",
    "github": "https://github.com/yourorg"
  },
  "navigation": [
    {
      "group": "Resources",
      "pages": ["status"]
    }
  ]
}

Create docs/status.mdx with a link to your Vigilmon status page — Mintlify doesn't support external footer links directly, but a docs page works.

What you've built

| What | How | |---|---| | Custom domain monitoring | Vigilmon HTTP monitor with keyword match | | Platform vs. DNS triage | Secondary monitor on .mintlify.app subdomain | | API health monitoring | Health endpoint + Vigilmon HTTP monitor | | OpenAPI spec endpoint monitoring | Vigilmon HTTP monitor with keyword match | | Docs sync heartbeat | CI ping after successful Mintlify sync | | mint.json validation | Pre-sync script that catches broken navigation | | Instant alerts | Slack/Discord webhook notifications | | Public status page | Vigilmon status page linked from docs |

Mintlify handles your docs platform. Vigilmon makes sure your users can always reach it. Together you have complete coverage — hosted convenience and independent availability verification.

Get started free at vigilmon.online — your first monitor is running in under a minute.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles