Link health

The Link health page is your inbox of broken links on your consumer sites. When a consumer site serves a 404, it can POST the missing path to Clog via the external API; the dashboard rolls those reports into a list ordered by hit frequency. From there, you decide whether each entry deserves a redirect, was already fixed, or should just be ignored.

This is the operational counterpart to Redirects — that page is for proactive redirects you author; this one is for reactive 404 cleanup.

You need settings:read or seo:read to view the page and settings:write or seo:write to resolve entries.

How reports get here

Consumer sites POST to POST /external/link-health on every 404 they serve, with the missing path and (optionally) the referring URL. See API → Redirects and link health for the full integration recipe.

The backend upserts on (workspaceId, path):

• First report for a path → creates a new BrokenLink row with hitCount = 1.
• Subsequent reports for the same path → bump hitCount, refresh lastSeenAt, update referrer to the latest reporter.

The endpoint is intentionally low-friction — it accepts any bound API key with workspace membership; no specific permission scope is required. That keeps reporting fire-and-forget from the consumer side.

The Link health page

Open Link health from the workspace sidebar. Each row shows:

• Path — the missing URL (without host).
• Referrer — the last document that linked to it, if reported.
• Hits — total count of 404 reports for this path.
• First seen / Last seen — timestamps from consumer reports.
• Status — Unresolved (default), or one of three resolved states.

From the top of the page:

• Search — across path and referrer.
• Filter — Unresolved / Resolved / All. Defaults to Unresolved.
• Sort — by hitCount (default, desc), firstSeenAt, lastSeenAt, path, or resolvedAt.

The default view is the most-hit unresolved 404s first — the ones costing you the most traffic.

Resolving an entry

Click a row. Three resolve actions appear:

Convert to redirect

Click Convert to redirect. A side sheet opens with:

Save. Two things happen atomically:

1. A new redirect row is created in the Redirects table — exactly as if you'd created it from there.
2. The broken-link entry is marked resolved with resolvedBy = "redirect:<new-redirect-id>", stamping resolvedAt to now.

The next time a consumer site syncs GET /external/redirects, the new redirect ships out and the 404s stop accumulating against this path.

This is the most-used resolve action — typically the answer for typo paths, renamed posts that were missed by the auto-301, and inbound links from old sites that didn't update.

Mark fixed

Click Mark fixed. The entry is marked resolved with resolvedBy = "fixed" and resolvedAt = now.

Use when you've actually fixed the underlying problem — restored the missing post, corrected the bad outbound link on your site, updated the wrong URL in your sitemap, etc. No redirect is created.

The dashboard keeps the row so you have a trail of what was fixed and when, but it stops showing in the default Unresolved filter.

Ignore

Click Ignore. The entry is marked resolved with resolvedBy = "ignored" and resolvedAt = now.

Use when the 404 is intentional and not worth a redirect — typically crawler-generated paths your consumer site never had (/wp-admin, /.env, /wp-login.php), bot fishing for old PHP installs, malformed URLs from broken backlinks you can't fix.

What if the same path 404s again?

The (workspaceId, path) upsert means a resolved entry stays attached to its original row — incoming reports on the same path keep bumping hitCount and refreshing lastSeenAt on the resolved row, not creating a new entry.

For each resolved kind, that means:

• Converted to redirect. If the redirect is live and consumers are honoring it, reports should drop to zero. If you keep seeing reports, a consumer site hasn't synced yet, or has a stale cache, or has a bug. Check the redirect row's Hits counter on the Redirects page to see if it's firing.
• Marked fixed. If you keep seeing reports, the fix didn't take. Open the row again and consider converting it to a redirect after all.
• Ignored. Reports keep accumulating in the background. The row stays out of the Unresolved view, but hitCount keeps ticking up. This is fine — it just means bots keep probing.

What this page is not

A few things to keep in mind so expectations stay grounded:

• It's not a 404 monitor for Clog. Clog itself doesn't serve traffic — the dashboard runs on its own subdomain, and the API returns JSON. Link health tracks 404s on your consumer sites, fed by their reports.
• It's not retroactive. Entries appear only after a consumer site reports a 404. If you haven't wired the reporting endpoint into your consumer site yet, this page stays empty.
• It's not exhaustive. A consumer site can choose not to report, can drop reports under load, can rate-limit them. The list reflects what Clog has received, not what crawlers and visitors actually hit.
• No bulk resolve action in v1. Each entry is resolved individually. For large lists of clear redirects (e.g. importing legacy URLs after a CMS migration), prefer the CSV bulk-import flow on the Redirects page.

Wiring the consumer reporter

The integrator's side of this loop — how a consumer site reports 404s back — lives in API → Redirects and link health. Briefly:

• Server-side, on the consumer's 404 handler, fire-and-forget POST /external/link-health with { path, referrer? }.
• Use a key bound to a member with workspace access — there's no specific permission scope, but the key still needs to authenticate.
• Repeat reports for the same path are explicitly safe — Clog upserts on (workspaceId, path).

Where to next

• Redirects — the destination for "convert to redirect" actions and the master list of all redirects in this workspace.
• API → Redirects and link health — the consumer-site integration.