Skip to content

CMS integrations

Overwatch is built to be read from inside a CMS. Three endpoints serve what a CMS plugin (such as the Sanity Studio plugin) needs: everything known about one page, a site digest for an Overwatch tool, and a re-check an editor can run after fixing something.

Overwatch reports and suggests. Fixes happen in the CMS: every finding carries why it matters and what to do, plus enough detail (the link target, the offending text) to find it in the document.

The @weareheavy/sanity-plugin-overwatch plugin is built on these endpoints. It adds:

  • an Overwatch tool with the site digest;
  • an Overwatch view on each document;
  • a footer badge;
  • wavy underlines on dead links.

Its README covers setup.

Use a read-only API key. The key is visible to every editor who can open the CMS, and a read-only key can call all three endpoints, including the re-check.

Call the API straight from the browser: requests with an x-api-key header are allowed from any origin, such as localhost, *.sanity.studio or your own domain. These cross-origin requests carry no cookies, and the browser won’t send an Authorization header with them.

Every item is keyed by page URL. Pass the document’s public URL as it is. Overwatch keys it the way the crawler keys pages: www. and non-www. fold together, and the site’s ignored query parameters (stripParams) are dropped. Map URLs back onto documents in the CMS: in Sanity, use the same URL resolution as Presentation.

GET /v1/sites/{id}/page?url=… answers with:

  • findings, hottest first, from every app installed on the site:
    • links: the page’s broken or unreachable outgoing links, with the anchor text and where the link sits on the page;
    • SEO: the SEO checks, with stable issue ids;
    • accessibility: confirmed accessibility violations;
    • google: Google’s own verdicts from URL Inspection.
  • page: the page as the latest crawl read it. This is its title, description, canonical, word count, whether the sitemap lists it, how many pages link to it (inlinks), and clicks from the homepage (depth).
  • crawled: whether the latest crawl reached the page at all. A draft or an unlinked page is false.
  • search: when Search Console is connected, the last 28 days’ clicks, impressions, CTR and position, the 28 days before (previous), and the searches that lead to the page.
  • insights: a few signals derived from that search data:
    • slipping: clicks fell 30% or more against the previous 28 days, from at least 20;
    • low-ctr: the page ranks well but is rarely clicked;
    • striking-distance: searches that rank the page just off page one.
  • index: Google’s last inspection of the page.

GET /v1/sites/{id}/digest is the overview for an Overwatch tool:

  • fixFirst: the ten pages to fix first. Pages are ranked by how serious their findings are, weighted by how many people see the page in search.
  • pages: every page with findings, in the same order, with counts by severity, its worst finding, and problems: its findings folded by rule, worst first, with how many of each. Use it for per-document badges, or to group pages by problem.
  • byRule: how many pages each kind of finding affects.
  • changes: what broke and what was fixed since since (epoch milliseconds). By default this is the crawl before the latest, so a plugin can store when the editor last looked and pass it back. It covers broken links and SEO issues. A link whose page disappeared isn’t counted as fixed.
  • signals: when Search Console is connected, the site’s slipping pages, rarely clicked pages and striking-distance searches.

POST /v1/sites/{id}/page/recheck with { "url": "…" } re-reads the live page and re-checks its links straight away, without waiting for the next crawl:

  • It checks every link on the page, up to 100 plus any that were broken before.
  • It follows the crawl’s scope: robots.txt, the site’s exclude paths and ignored parameters.
  • The fresh result replaces that page’s problem links in the latest crawl, so the dashboard and report agree with the CMS.

The answer lists what was fixed, what is still broken and what is newly broken, plus the fresh page view.

Only links are re-checked. SEO, accessibility and Google findings refresh with the next crawl. A page can be re-checked once every 30 seconds (429 otherwise), and only pages on the site’s own host can be fetched (400 otherwise).