Recommendations

A recommendation is one actionable, scored suggestion attached to a page's analysis — e.g. "lead the title with the primary keyword." Recommendations aren't listed or fetched standalone; you read them embedded in GET /pages/{pageId}/analysis, then act on individual ones by recId through the three verbs on this page.

All three verbs require content:write and return the same envelope shape: the updated recommendation plus a refreshed analysis score summary, so you see the effect of your action in the same response — no follow-up GET needed to know whether the score moved.

The verification model

resolve and recheck both call an AI validator (Claude Haiku) that reads the recommendation and the current content and judges whether the recommendation was actually addressed. This is the only place in the API that runs AI on a write path.

• Availability-first. If the validator errors or times out (6s), the recommendation is auto-verified — addressed: true with skipped: true — rather than blocking the call. A human already made the edit; a telemetry-grade check failing shouldn't hold up the response. skipped: true is your signal that the "pass" wasn't independently checked.
• A skipped verdict does NOT count toward the verified score. "Verified" means verified: a recommendation applied on a skipped verdict keeps its status: applied and still counts toward estimated_score, but it does not promote overall_score/score_source. Call recheck once the content is final — a real verdict carries no skipped flag, and the promotion lands on the normal recalculation.
• Placeholders don't block addressing, but they block score promotion. The validator also flags unresolved template fragments in the content ("[Your Company]", "XX%", TODO, lorem-style filler) as placeholders. A recommendation with placeholders can still be addressed: true and status: applied — the structural change was made — but leaving placeholders in place is a publishing-readiness problem, not a scoring one. Replace them and call recheck to confirm; a clean recheck is what actually promotes overall_score from audit to verified. Fragments a user has marked as real content in the MetaMonster UI are excluded from placeholders on every recheck verdict; regenerating the content (accepting a new AI action or bulk rewrite) starts a fresh scan.
• force: true on resolve skips validation entirely. The recommendation is marked applied with a synthetic skipped: true verdict and validation_scope: null — use when you're confident the change is right and don't want to spend the validation round-trip. Same caveat as above: it won't promote the verified score until a real recheck confirms it.
• Content MetaMonster applies for you skips the AI validator too. A recommendation applied by MetaMonster itself — accepting an AI-generated action, or a bulk content rewrite — never runs the Haiku check in the first place. It's verified with a deterministic placeholder scan instead: addressed is always true for non-empty applied content, and placeholders is what actually tells you whether it's publish-ready. This verdict carries validation_scope: "system_applied". Applied content with no verifiable surface (e.g. an untargeted action) still falls back to the ordinary skipped: true verdict — same no-promotion rule as any other skipped case. Calling recheck on one of these recs stays on the same fast path: it re-runs only the placeholder scan against the current content — no AI validator round-trip — and the stored/returned validation_scope stays system_applied. If nothing resolves to validate against on the recheck (e.g. the targeted content was since deleted), it returns the ordinary skipped: true verdict instead of 400 no_content_to_validate — same no-promotion rule as any other skipped case — see the scope table below.

Verification outcomes

resolve and recheck return the same top-level verdict block — addressed, reasoning, skipped, placeholders, validation_scope, validated_node_ids — plus recommendation and analysis. The same fields (minus reasoning duplication) are mirrored on recommendation.verification so a later GET /pages/{pageId}/analysis replays them.

The Status change column describes resolve. recheck never changes status — its only gate is status: applied, and the rec stays applied whatever the verdict; only validation_result is rewritten. So a rec that fails a recheck (addressed: false) stays applied but stops counting as verified: the promoted overall_score gives its points back, and because a failed verdict isn't an earnable open gain it drops out of estimated_score too. Fix the content and recheck again to re-earn them.

validation_scope and validated_node_ids

validation_scope tells you which slice of the page the verdict was formed against, so you never have to guess why a verdict came out the way it did:

Body recommendations are always validated against the targeted nodes and the full document. Node-scoped validation alone used to fail a recommendation like "mention the primary keyword in the intro" whenever the phrase landed in a neighbouring node; the whole document now rides along as context (capped at 60,000 characters, with [… truncated] appended past the cap), so the recommendation passes wherever the change landed. validation_scope stays targeted_nodes in that case — it names the primary read, and validated_node_ids tells you which nodes that was.

content_excerpt

Every recommendation response includes recommendation.content_excerpt — the markdown of the specific doc node(s) the recommendation targets, so you can locate the passage without touching ProseMirror node ids. It's populated when the recommendation targets body_content and the API was able to resolve the targeted nodes from the current content version; it's null for metadata-target recommendations (title, meta description, etc.) and when nothing could be resolved. GET /pages/{pageId}/analysis populates it for every body_content recommendation up front; the verb responses below populate it only when the verb itself extracted targeted content along the way (e.g. resolve auto-resolving content for a body_content rec) — if you passed content explicitly, or the recommendation targets metadata, expect null here even though the recommendation was still updated correctly.

Internal-link recommendations

An "add internal links" recommendation is scored against your current content — specifically, the links found in whatever GET /pages/{pageId}/content (or the brief's fields.body.value) currently returns for the page, not the links the crawler saw on the live site. So: add links via POST /pages/{pageId}/content (or PUT /pages/{pageId}/drafts/body + publish), then POST /pages/{pageId}/analyze — the new links count on that next audit. Links that only exist in the site's crawled navigation or footer (visible via GET /pages/{pageId}/links) are context for the model, not counted toward this criterion — they were never part of the page's own content in the first place.

The schema workflow

A schema-target recommendation (e.g. "add Organization structured data") is resolved the same way as any metadata rec, but the write step is specific:

1. PUT /pages/{pageId}/drafts/schema with { "draft_value": "<JSON-LD string>" }. The write only fails (400 invalid_request) if the JSON itself doesn't parse; schema.org rule violations save anyway and come back as validation on the response — see drafts.md.
2. POST /recommendations/{recId}/resolve with no body. content defaults to the draft you just wrote (falling back to the crawled snapshot's schema if you skip step 1), so there's nothing to pass explicitly.

You can also check schema health any time from the brief's fields.schema.validation without a dedicated call — see brief.md.

POST /recommendations/{recId}/dismiss

Dismiss a recommendation — "we're not doing this." Stores an optional rationale (kept for future analysis context) and recalculates scores: a dismissed recommendation's points are forfeited from estimated_score.

Scope: content:write

Path parameters

Request body

curl -X POST https://new.metamonster.ai/api/v1/recommendations/5500/dismiss \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rationale": "Already A/B tested — keyword-first titles underperformed here." }'

Response 200

{
  "data": {
    "recommendation": {
      "id": 5500,
      "analysis_id": 7200,
      "page_id": 5001,
      "site_id": 42,
      "title": "Lead the title with the primary keyword",
      "description": "Move \"pricing\" toward the front of the title tag.",
      "why_it_matters": "Front-loaded keywords improve relevance signals.",
      "impact": "medium",
      "status": "dismissed",
      "source": "audit",
      "source_components": ["title"],
      "operation": "replace",
      "target_field": "title",
      "target_node_ids": null,
      "after_node_id": null,
      "insertion_point": null,
      "rubric_criteria": null,
      "resolution_method": null,
      "resolved_at": "2026-08-14T10:10:00Z",
      "dismissal_rationale": "Already A/B tested — keyword-first titles underperformed here.",
      "sort_order": 1,
      "point_value": 4,
      "carried_from_recommendation_id": null,
      "verification": null,
      "content_excerpt": null,
      "created_at": "2026-07-19T18:00:00Z",
      "updated_at": "2026-08-14T10:10:00Z"
    },
    "analysis": {
      "overall_score": 78,
      "overall_grade": "B",
      "estimated_score": 82,
      "estimated_grade": "B",
      "score_source": "audit",
      "verified_at": null
    }
  }
}

recommendation uses the same shape documented in GET /pages/{pageId}/analysis, plus content_excerpt (always null on dismiss — dismissing never resolves content). analysis is null if the recommendation had no analysis_id; otherwise it's { overall_score, overall_grade, estimated_score, estimated_grade, score_source, verified_at } re-read after the recalculation triggered by this call.

Errors

POST /recommendations/{recId}/resolve

"I made this change" — the agent's feedback signal. Validates the current content against the recommendation and, on a pass, marks it applied (earning its points). See The verification model above.

Scope: content:write

Path parameters

Request body

Request — auto-resolved body content

curl -X POST https://new.metamonster.ai/api/v1/recommendations/5501/resolve \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200 — addressed

{
  "data": {
    "addressed": true,
    "reasoning": "The section now includes a plan comparison table addressing pricing objections as recommended.",
    "skipped": false,
    "placeholders": [],
    "validation_scope": "targeted_nodes",
    "validated_node_ids": ["node_42a"],
    "recommendation": {
      "id": 5501,
      "analysis_id": 7200,
      "page_id": 5001,
      "site_id": 42,
      "title": "Add a plan comparison table",
      "description": "Insert a table comparing plan tiers under the intro paragraph.",
      "why_it_matters": "Comparison tables reduce bounce on pricing pages.",
      "impact": "high",
      "status": "applied",
      "source": "audit",
      "source_components": ["structure"],
      "operation": "insert",
      "target_field": "body_content",
      "target_node_ids": ["node_42a"],
      "after_node_id": "node_41",
      "insertion_point": "after",
      "rubric_criteria": null,
      "resolution_method": "manual",
      "resolved_at": "2026-08-14T10:12:00Z",
      "dismissal_rationale": null,
      "sort_order": 2,
      "point_value": 6,
      "carried_from_recommendation_id": null,
      "verification": {
        "addressed": true,
        "reasoning": "The section now includes a plan comparison table addressing pricing objections as recommended.",
        "placeholders": [],
        "skipped": false,
        "validation_scope": "targeted_nodes",
        "validated_node_ids": ["node_42a"]
      },
      "content_excerpt": "| Plan | Price | Seats |\n| --- | --- | --- |\n| Starter | $19 | 1 |\n| Team | $49 | 5 |",
      "created_at": "2026-07-19T18:00:00Z",
      "updated_at": "2026-08-14T10:12:00Z"
    },
    "analysis": {
      "overall_score": 82,
      "overall_grade": "B+",
      "estimated_score": 86,
      "estimated_grade": "B+",
      "score_source": "verified",
      "verified_at": "2026-08-14T10:12:00Z"
    }
  }
}

resolution_method is "manual" for every API-driven resolve (mirrors the dashboard's manual-resolve path — distinct from "ai_action", which only AI-applied actions set). Note score_source flipping to "verified" with verified_at populated: promoting overall_score out of audit happens automatically the first time a validated, addressed recommendation lands.

Response 200 — not addressed

The recommendation stays open (status unchanged, still pending/in_progress) and no points are earned — only validation_result/verification is updated:

{
  "data": {
    "addressed": false,
    "reasoning": "The title still leads with the brand name, not the primary keyword.",
    "skipped": false,
    "placeholders": [],
    "validation_scope": "field_draft",
    "validated_node_ids": null,
    "recommendation": {
      "id": 5501,
      "status": "pending",
      "verification": {
        "addressed": false,
        "reasoning": "The title still leads with the brand name, not the primary keyword.",
        "placeholders": [],
        "skipped": false,
        "validation_scope": "field_draft",
        "validated_node_ids": null
      },
      "content_excerpt": null,
      "…": "…other fields unchanged"
    },
    "analysis": null
  }
}

(analysis is null here only because this example recommendation has no analysis_id; normally it's the same refreshed summary object as above — unaffected, since nothing was applied.)

Errors

POST /recommendations/{recId}/recheck

Re-verify an already-applied recommendation after you've fixed something the first verification flagged — typically unresolved placeholders, or a skipped: true verdict from force: true/validator unavailability. Recheck doesn't change status (it's already applied); it re-runs validation and, if the fresh verdict is a clean pass, that's what promotes overall_score/score_source from audit to verified via the normal recalculation. The only gate is status: applied — a skipped verdict is always re-checkable, and a real verdict carries no skipped flag, so the promotion lands.

Where recheck reads content from — recheck never accepts inline content; it validates against what MetaMonster currently holds for the page:

• Body-content recs (target_field: "body_content"): the latest content version, narrowed to the nodes the original apply landed in (applied_node_ids), else the rec's target_node_ids, else the whole document. When it narrows to nodes, the full document still rides along as validator context, so a fix made elsewhere on the page counts. Recrawls and POST /pages/{id}/content saves both feed this.
• Metadata/schema recs (title, meta_description, h1, schema): the field's current draft (PUT /pages/{id}/drafts/{field}), falling back to the latest crawled snapshot value if there's no active draft. Note that resolve with inline content is a one-shot verdict — it stores nothing — so a metadata rec you resolved that way has nothing to recheck against beyond the snapshot until you PUT the draft. If you plan to iterate on a metadata field, write the draft first and let resolve/recheck read it.

If neither source yields content you get 400 no_content_to_validate — except for a system_applied rec (see above), which gets the ordinary skipped: true verdict instead of a 400.

Scope: content:write

Path parameters

Request

No body.

curl -X POST https://new.metamonster.ai/api/v1/recommendations/5501/recheck \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Content resolution priority: the node ids recorded on the original apply (validation_result.applied_node_ids) → the recommendation's target_node_ids → the full current document (for body_content/no-target recs) or the field's current draft value, falling back to the latest crawled snapshot value (for title/meta_description/h1/schema-target recs).

Response 200

{
  "data": {
    "addressed": true,
    "reasoning": "The placeholder pricing figures have been replaced with real numbers.",
    "skipped": false,
    "placeholders": [],
    "validation_scope": "targeted_nodes",
    "validated_node_ids": ["node_42a"],
    "recommendation": {
      "id": 5501,
      "status": "applied",
      "resolution_method": "manual",
      "verification": {
        "addressed": true,
        "reasoning": "The placeholder pricing figures have been replaced with real numbers.",
        "placeholders": [],
        "skipped": false,
        "validation_scope": "targeted_nodes",
        "validated_node_ids": ["node_42a"]
      },
      "content_excerpt": "| Plan | Price | Seats |\n| --- | --- | --- |\n| Starter | $19 | 1 |\n| Team | $49 | 5 |",
      "…": "…other fields unchanged"
    },
    "analysis": {
      "overall_score": 82,
      "overall_grade": "B+",
      "estimated_score": 86,
      "estimated_grade": "B+",
      "score_source": "verified",
      "verified_at": "2026-08-14T10:20:00Z"
    }
  }
}

placeholders, skipped, validation_scope, and validated_node_ids are top-level fields on the response (not just inside verification) — the same values, surfaced for convenience since recheck's whole purpose is usually "did I clear the thing that blocked promotion." An empty placeholders array plus skipped: false means clean; either one otherwise means score promotion (if it hadn't already happened) still won't occur. See Verification outcomes.

Errors