Skip to content

Pressroom Engineering

Automated SEO Audits as an API Contract: Turning Crawl Failures into Pre-Flight Entry Warnings

From Pressroom Engineering · 6 articles · latest

Architecture diagram of Pressroom's SEO audit API contract from entries preview to audits seo_entry and remediation
Pressroom's closed-loop SEO API contract: pre-flight AST linting via entries preview, atomic persistence, and post-publish verification via audits seo_entry and audits seo.

On November 11, 2026, a Bing site scan came back with an embarrassing number: 94 entries across our migrated blogs had meta titles that were too long. Nobody had forgotten to populate metadata. In fact, every single one of those 94 posts had a populated title field—and that was the exact problem. Early publishing scripts and LLM agents had either copied 75-character headlines straight into metaTitle or mechanically sliced them off at 60 characters with a trailing ellipsis.

When a human edits a CMS form in a browser, a red character counter usually stops them before they hit publish. When an autonomous agent publishes over an API, there is no browser UI, no visual SERP preview, and no red border around an input box. If your publishing endpoint accepts whatever JSON payload an agent sends and silently returns 200 OK, crawl failures accumulate invisibly until a search engine crawler flags ninety-four pages weeks later.

In Pressroom, we solved this by treating SEO hygiene as a first-class API contract rather than a quarterly spreadsheet chore. Instead of waiting for Bing Webmaster Tools or Google Search Console to tell us a post shipped broken markup, Pressroom exposes pre-flight rendering checks in entries preview and structured corpus diagnostics in audits seo, audits seo_entry, and audits media.

Why Agentic Publishers Fail at SEO Silently

Most CMS APIs validate schema types (string, boolean, enum) and stop there. That leaves a wide gap between "valid JSON" and "clean HTML for crawlers and readers." Across dozens of automated runs before we hardened Pressroom's MCP surface, we saw the same four failure modes repeat across every weblog:

  1. Title-Copy and Truncation Reflexes: When a post title exceeds 60 characters, agents instinctively copy title verbatim into metaTitle or truncate it mid-word ("Safe Agent Editing at Scale: Optimistic Locking, Partial..."). Search engines either rewrite the <title> element or display a mangled snippet.
  2. Truncated Opening-Paragraph Descriptions: Without explicit bounds, agents leave searchDescription blank or dump the first 220 characters of the intro paragraph into it—producing awkward mid-sentence cutoffs in search snippets.
  3. Duplicate <h1> Tags and Broken Heading Outlines: Agents trained on standalone Markdown files routinely start every draft with # Post Title. Because Pressroom themes already render the entry title as the page's <h1>, a # heading in the body emits a second <h1> or creates skipped levels (<h2> straight to <h4>).
  4. Unimported Hotlinks and Naked <img> Elements: As we documented in Pictures by Default and Shortcodes, Leaflet Maps, and JSON-LD, leaving a raw external URL or plain <img> tag in Markdown bypasses responsive WebP srcset generation, drops BlurHash placeholders, and often ships without alt text.

Important

Contract Rule for metaTitle: Omit metaTitle whenever title is 60 characters or fewer so Pressroom can render the title and append the weblog name when it fits. Only set metaTitle when title exceeds 60 characters—and write a fresh, complete title of at most 60 characters that leads with the core topic.

Shifting Left With entries preview

You should not have to persist an entry to PostgreSQL just to find out its Markdown compiles into broken HTML. Pressroom's entries preview action runs the exact same CommonMark AST parser, shortcode expander, and OWASP sanitizer used by the live permalink renderer—without writing a row or creating a revision.

Alongside the rendered html string, entries preview returns a warnings array catching structural defects at draft time:

  • Body <h1> collisions: Flags # headings in the body so authors start sections at ##.
  • Skipped heading levels: Catches jumps such as h2 directly to h4 that break document outline accessibility.
  • Inline color and background styles: Catches HTML such as <div style="color:#000"> that becomes illegible on dark themes like Pressroom's portfolio layout, steering authors toward portable GitHub alerts (> [!NOTE], > [!TIP], > [!IMPORTANT]).
  • Hotlinked external images: Flags remote image URLs that lack local WebP renditions and break if the upstream host disappears.
  • Broken fragment and slug links: Verifies in-page #anchor targets against generated heading IDs and checks internal links before they ever return a 404 to a crawler.
{
  "html": "<h2 id=\"section-one\">Section One</h2>\n<h4 id=\"skipped-heading-level\">Skipped Heading Level</h4>\n...",
  "warnings": [
    "A heading skips a level: h2 \"Section One\" is followed by h4 \"Skipped Heading Level\". Go down one level at a time, so the outline has no gaps.",
    "1 link points at a part of this entry that does not exist: #nonexistent-anchor. No element in the body has that id; a Markdown heading's id is its text in lower case with hyphens for spaces (## Ferry times is #ferry-times)."
  ]
}

Our publishing contract is simple: an agent treats entries preview as a hard pre-flight gate before calling entries create or entries update, resolving every body-level warning (h1, skipped heading levels, inline color divs, external hotlinks, broken #anchor links) before persistence. Because entries preview also accepts an existing entry id paired with a targeted edits array ([{find, replace}]), agents can dry-run partial patches against live posts before risking a write.

The Post-Save Audit Plane: audits seo, audits seo_entry, and audits media

Body linting catches markup bugs, while metadata and cross-corpus checks belong in Pressroom's audits MCP tool. Every publishing pipeline gets three complementary views over /api/mcp:

1. Per-Entry Verification (audits seo_entry)

Immediately after entries create or entries update, the publishing agent calls audits seo_entry with the entry id and weblog handle. Pressroom inspects both the entry's metadata fields and its full rendered body, returning structured findings objects with machine-readable codes, severity, human-readable remediation advice, and measured limits:

{
  "id": "f11a974a-b5a5-45bd-a700-a5d27ad7cfd7",
  "anchor": "meet-the-blogger-agent-autonomous-publishing-quality-gates-anti-slop",
  "title": "Meet the Blogger Agent: Autonomous Publishing, Quality Gates, and the War on AI Slop",
  "findings": [
    {
      "code": "title_long",
      "severity": "warning",
      "message": "The page title, \"Meet the Blogger Agent: Architecture, Philosophy & Publishing\", is 61 characters; a search result cuts it off after 60. Set a shorter meta title.",
      "value": 61,
      "limit": 60
    },
    {
      "code": "image_not_responsive",
      "severity": "warning",
      "message": "1 image of this weblog is placed with a plain img, so every reader downloads the full-size file. Place it with [image id=54aaf22b-bac4-4517-bf98-81eae228f45c] instead, which serves a size that fits the screen; add caption=\"...\" for a caption."
    }
  ]
}

Notice how specific that diagnostic is: it does not just say "title invalid." It tells the agent the exact measured length (61), the search-result budget (60), and the exact media UUID to substitute into an [image id=...] shortcode. When an entry passes every check—like Safe Agent Editing at Scale—the endpoint returns "findings": [].

2. Weblog-Wide Gap Sweeps (audits seo)

Individual checks miss cross-entry collisions like duplicate titles or descriptions. Calling audits seo sweeps an entire weblog and aggregates counts across every tracked SEO defect:

{
  "total": 1,
  "counts": {
    "missing_search_description": 0,
    "missing_meta_title": 0,
    "missing_featured_image": 0,
    "noindex": 0,
    "search_description_long": 0,
    "search_description_short": 0,
    "search_description_cut": 0,
    "meta_title_cut": 0,
    "title_long": 1,
    "title_duplicate": 0,
    "search_description_duplicate": 0
  },
  "entries": [
    {
      "entryId": "f11a974a-b5a5-45bd-a700-a5d27ad7cfd7",
      "anchor": "meet-the-blogger-agent-autonomous-publishing-quality-gates-anti-slop",
      "title": "Meet the Blogger Agent: Autonomous Publishing, Quality Gates, and the War on AI Slop",
      "gaps": ["title_long"]
    }
  ]
}

Together, those eleven gap flags encode our entire search-hygiene policy in deterministic server code:

  • Title hygiene: missing_meta_title fires when an entry's title exceeds 60 characters and has no metaTitle; title_long fires when the effective page title exceeds 60 characters; meta_title_cut catches truncated strings ending in ellipses; title_duplicate catches colliding titles within the same weblog.
  • Snippet hygiene: missing_search_description, search_description_short (under the 50-character minimum, with our editorial target set tightly at 120–155 characters), search_description_long (over 160 characters), search_description_cut, and search_description_duplicate.
  • Visual and crawlability hygiene: missing_featured_image and noindex ensure no post slips onto the front page without an OpenGraph hero card or accidentally blocks indexing.

3. Asset Alt-Text Compliance (audits media)

Images imported via media import or featuredImageUrl can still lack accessibility descriptions if an older migration or manual upload skipped altText. Calling audits media returns missingAltText along with the exact items that need media update remediation—closing the loop on both screen-reader accessibility and image search indexing.

Fix the Content, Never Silence the Warning

The single fastest way to ruin an automated audit system is to treat a warning code as a checkbox to game. After the November Bing scan, it would have been trivial to write a five-line Python script that copied entry.title[:57] + "..." into metaTitle or padded short descriptions with boilerplate filler. That would have driven missing_meta_title to zero while making every search snippet objectively worse.

Note

Editorial Rule: Clear a warning by rewriting the content, never by gaming the threshold. A title_long or meta_title_cut finding means "author a crisp, complete sub-60-character title," and an image_not_responsive finding means "replace raw <img> HTML with [image id=...]."

When audits seo flags an older post, our remediation loop pairs with Pressroom's optimistic concurrency controls:

  1. Read the entry metadata (or full body with contentHash via entries get).
  2. Author a genuinely better metaTitle (<= 60 characters), searchDescription (120–155 characters), or targeted edits patch swapping raw <img> markup for [image id=...].
  3. Preview with entries preview, commit with expectedContentHash and a revisionNote, and re-run audits seo_entry to confirm "findings": [].

As we outlined in Meet the Blogger Agent, reliable agentic publishing is mostly the discipline of making invalid states unpublishable. By encoding search-engine and accessibility standards directly into entries preview and audits, Pressroom turns crawl failures from post-hoc surprises into immediate, verifiable API feedback.

Authoritative References

Keep reading

Comments