Pages

A page is an individual URL discovered on a site. Pages are long-lived — they persist across crawls, accumulating snapshots, analysis, and drafts over time.

Read endpoints require sites:read; write endpoints require content:write.

For a single-call work packet see brief.

GET /sites/{siteId}/pages

List a site's pages (lean summary shape), with filtering, sorting, and pagination. Priority pages always sort first, then by your chosen sort/direction.

Scope: sites:read

Path parameters

Query parameters

Regardless of sort, priority pages (is_priority: true) are always listed before non-priority pages.

Request

curl "https://new.metamonster.ai/api/v1/sites/42/pages?is_priority=true&min_score=50&sort=opportunity_score&direction=desc&limit=20" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 5001,
      "url": "https://example.com/pricing",
      "path": "/pricing",
      "site_id": 42,
      "title": "Pricing — Example",
      "primary_keyword": "example pricing",
      "is_priority": true,
      "opportunity_score": 78
    }
  ],
  "meta": { "total": 128, "page": 1, "per_page": 20 }
}

Each item (page summary shape):

Errors

POST /sites/{siteId}/pages

Create a page by path on one of your sites. Pass crawl: true to immediately scrape the live page instead of getting back the bare record — this is the fast lane for "analyze this URL" when the URL isn't a page MetaMonster already knows about: create it here with crawl: true, then poll the returned job, then run POST /pages/{pageId}/analyze.

Scope: content:write

Path parameters

Request body

curl -X POST https://new.metamonster.ai/api/v1/sites/42/pages \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/pricing", "crawl": true }'

Response 201 (no crawl)

{
  "data": {
    "id": 5001,
    "url": "https://example.com/pricing/",
    "path": "/pricing/",
    "site_id": 42,
    "title": null,
    "primary_keyword": null,
    "is_priority": true,
    "opportunity_score": null
  }
}

Same page summary shape as GET /sites/{siteId}/pages above. title is null until an analysis produces a snapshot.

Response 202 (crawl: true)

{ "data": { "job_id": "job_cr_990", "status": "processing", "page_id": 5001, "retry_after_seconds": 5 } }

The page row is created before the crawl is queued either way, so a 202 response's page_id already refers to a real page — use it right away (e.g. for PATCH /pages/{pageId}) without waiting on the job.

Not blocked by a running site crawl. Unlike POST /pages/{pageId}/recrawl, this endpoint's crawl: true path does not check for (or 409 on) an in-progress site-level crawl. A brand-new site's setup crawl can be running at the same time you create-and-crawl an individual page here — both proceed independently. The only gate on the crawl path is an active subscription.

Errors

GET /pages/lookup

Resolve an absolute URL to one of your pages — the entry point for "analyze this URL" flows, when you have a URL but not a page_id. Host matching ignores www.; path matching ignores trailing slashes. If several pages match, the most recently added site wins (the same domain can be added more than once), then its most recently updated live page.

Scope: sites:read

Query parameters

Request

curl "https://new.metamonster.ai/api/v1/pages/lookup?url=https://example.com/pricing" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": {
    "page_id": 5001,
    "site_id": 42,
    "url": "https://example.com/pricing",
    "path": "/pricing"
  }
}

Errors

GET /pages/{pageId}

Fetch a single page with full detail — including its latest snapshot, a summary of its latest analysis, and its active field drafts.

Scope: sites:read

Path parameters

Request

curl https://new.metamonster.ai/api/v1/pages/5001 \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": {
    "id": 5001,
    "url": "https://example.com/pricing",
    "path": "/pricing",
    "name": null,
    "purpose": "Convert plan comparisons",
    "planned": false,
    "site_id": 42,
    "primary_keyword": "example pricing",
    "secondary_keywords": ["pricing plans", "cost"],
    "is_priority": true,
    "is_priority_manual": true,
    "opportunity_score": 78,
    "gsc_url": "https://example.com/pricing",
    "gsc_indexed": true,
    "discovered_via": "crawl",
    "created_at": "2026-05-01T13:00:00Z",
    "updated_at": "2026-07-20T09:30:00Z",
    "last_analyzed_at": "2026-07-19T18:00:00Z",
    "latest_snapshot": {
      "id": 8100,
      "title": "Pricing — Example",
      "meta_description": "See Example's pricing plans.",
      "h1": "Pricing",
      "word_count": 640,
      "status_code": 200,
      "created_at": "2026-07-20T09:20:00Z"
    },
    "latest_analysis": {
      "id": 7200,
      "overall_score": 78,
      "overall_grade": "B",
      "status": "completed",
      "completed_at": "2026-07-19T18:00:00Z",
      "score_source": "audit",
      "content_stale": false
    },
    "drafts": [
      { "field": "title", "status": "draft", "draft_value": "Example Pricing: Plans & Costs" }
    ]
  }
}

Page detail shape:

latest_analysis summary object: { id, overall_score, overall_grade, status, completed_at, score_source, content_stale }. score_source is audit or verified (see the analysis field table below). content_stale: true means the page's content changed after this analysis ran — treat overall_score/overall_grade as void until a re-analysis completes. For the full analysis with components and recommendations, use GET /pages/{pageId}/analysis.

Errors

PATCH /pages/{pageId}

Update a page's target keywords, priority flag, page context, and Search Console URL. This is a plain data update — no AI, no credits consumed.

If a keyword-generation workflow is currently running for this page's site (primary_keyword, status pending/processing), writes that touch primary_keyword or secondary_keywords are rejected with 409 keyword_generation_in_progress — the worker owns primary_keyword while it runs and would silently overwrite an API write. Retry once the workflow finishes. Writes to is_priority/purpose alone are never gated. A successful keyword write also recomputes the site's cached opportunity scores and priority set (best-effort — a recompute failure never fails the request). Because the response is built from the page row as of the update (before that recompute runs), opportunity_score/is_priority in this response can predate the recompute's effects — fetch the page again with GET /pages/{pageId} to see the recomputed values.

Scope: content:write

Path parameters

Request body

Send at least one of these fields. Unknown fields are rejected.

curl -X PATCH https://new.metamonster.ai/api/v1/pages/5001 \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "primary_keyword": "example pricing", "is_priority": true }'

Self-healing a wrong gsc_url. Per-page GSC endpoints (/queries, /performance) measure exactly one URL. If a page's Search Console numbers look far smaller than what GET /sites/{siteId}/performance attributes to its page_id, the stored gsc_url is pointing at a variant — repoint or clear it:

curl -X PATCH https://new.metamonster.ai/api/v1/pages/5001 \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gsc_url": null }'

Response 200

Returns the updated page in the same detail shape as GET /pages/{pageId} — embeds included, reflecting the post-update state. One canonical page representation everywhere:

{
  "data": {
    "id": 5001,
    "url": "https://example.com/pricing",
    "path": "/pricing",
    "name": null,
    "purpose": "Convert plan comparisons",
    "planned": false,
    "site_id": 42,
    "primary_keyword": "example pricing",
    "secondary_keywords": ["pricing plans"],
    "is_priority": true,
    "is_priority_manual": true,
    "opportunity_score": 78,
    "gsc_url": "https://example.com/pricing",
    "gsc_indexed": true,
    "discovered_via": "crawl",
    "created_at": "2026-05-01T13:00:00Z",
    "updated_at": "2026-08-01T10:00:00Z",
    "last_analyzed_at": "2026-07-30T09:00:00Z",
    "latest_snapshot": { "id": 8100, "title": "Pricing — Example", "meta_description": "…", "h1": "Pricing", "word_count": 640, "status_code": 200, "created_at": "2026-07-29T08:00:00Z" },
    "latest_analysis": { "id": 7200, "overall_score": 72, "overall_grade": "B-", "status": "completed", "completed_at": "2026-07-30T09:00:00Z", "score_source": "audit", "content_stale": false },
    "drafts": [{ "field": "title", "status": "draft", "draft_value": "Example Pricing: Plans & Costs" }]
  }
}

Errors

PATCH /sites/{siteId}/pages

Apply the same patch to up to 50 pages of one site in a single call — the bulk form of PATCH /pages/{pageId}. Use it to mark a batch of pages priority, assign a shared purpose, or clear keywords across a set. Plain data update: no AI, no credits.

Scope: content:write

This endpoint is partially successful by design: an ID that isn't a live page of this site is reported in failed rather than failing the whole call, and one failed write doesn't abandon the rest. Pages are written one at a time, in the order you list them.

gsc_url is not settable here — it's per-page by definition (its host is validated against the site's domain). Use PATCH /pages/{pageId} for it.

Path parameters

Request body

curl -X PATCH https://new.metamonster.ai/api/v1/sites/42/pages \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_ids": [5001, 5002, 5003], "set": { "is_priority": true } }'

The keyword gate applies to the batch as a whole: if set touches primary_keyword/secondary_keywords while a keyword-generation workflow is running for this site, the entire call is rejected with 409 keyword_generation_in_progress and no page is written. A successful keyword batch recomputes the site's opportunity scores and priority set once, after the batch (best-effort), so — as with the single PATCH — the opportunity_score/is_priority values in this response can predate the recompute.

Response 200

{
  "data": {
    "updated": [
      {
        "id": 5001,
        "url": "https://example.com/pricing",
        "path": "/pricing",
        "site_id": 42,
        "is_priority": true,
        "is_priority_manual": true,
        "latest_snapshot": { "id": 8100, "title": "Pricing — Example" },
        "latest_analysis": { "id": 7200, "overall_score": 72, "overall_grade": "B-" },
        "drafts": []
      }
    ],
    "failed": [
      { "page_id": 9999, "code": "not_found", "message": "Page not found on this site" }
    ]
  },
  "meta": { "requested": 2, "updated": 1, "failed": 1 }
}

meta.updated + meta.failed always equals meta.requested. A call where every ID failed is still a 200 — check meta, not the status code.

Errors

GET /pages/{pageId}/content

Get the page's current body content, serialized to markdown, along with the ID of the content version it came from.

Scope: sites:read

Request

curl https://new.metamonster.ai/api/v1/pages/5001/content \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": {
    "content_version_id": 9300,
    "source": "outline",
    "version_created_at": "2026-08-01T10:00:00Z",
    "markdown": "# Pricing\n\nSee our plans below…"
  }
}

Errors

POST /pages/{pageId}/content

Save a new body content version for the page, from either markdown or a raw ProseMirror document. Stores exactly what you send — no AI generation.

Scope: content:write

Request body

Provide exactly one of markdown or doc:

curl -X POST https://new.metamonster.ai/api/v1/pages/5001/content \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "markdown": "# Pricing\n\nOur updated plans…", "base_version_id": 9300 }'

Response

Errors

See also Content versions for reading version history and rolling back to an earlier version.

POST /pages/{pageId}/recrawl

Tell MetaMonster to re-fetch the page from the live site — this is how MetaMonster learns about edits you made directly on the site (not through this API). Fully async: guards and any slug migration run synchronously in this request, but the actual scrape happens in a worker. Returns 202 with a job id to poll.

Scope: content:write

Path parameters

Request body

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

Response 202

{ "data": { "job_id": "job_cr_990", "status": "processing", "page_id": 5001, "retry_after_seconds": 5 } }

A recrawl requires an active subscription — unlike analyze, there's no free-preview carve-out. Only one crawl (single-page recrawl or full-site crawl) may be in flight per site at a time; triggering a second one 409s.

On completion, the recrawl advances the page's content version (source: "crawl") and marks the page's current analysis content_stale: true. Any base_version_id you were holding for POST /pages/{pageId}/content is now stale and will 409 — re-GET /pages/{pageId}/content for the fresh content_version_id before your next save. If the live page returned an error response, no snapshot is written and the completed job's result.snapshot_id is null — see Jobs.

Migrating a slug with new_path

If you renamed the URL directly on the site, pass new_path so MetaMonster tracks it as the same page (same id) rather than losing history. The page row's url/path are updated in place before the crawl is queued; id never changes.

curl -X POST https://new.metamonster.ai/api/v1/pages/5001/recrawl \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_path": "/pricing-plans" }'

Full-site-crawl hazard. This new_path migration only happens when you explicitly call this endpoint. If a slug rename is instead picked up by a full-site crawl (the site-level crawl your dashboard runs periodically, not this endpoint) without ever having gone through new_path here, the crawler has no way to know the new URL is "the same page" — it creates a brand-new page record at the new path, and the old page record becomes orphaned (still exists, no longer reachable from the live site). If you're renaming slugs via direct site edits and want to preserve page history/analysis/drafts, always migrate through new_path on this endpoint rather than letting a routine crawl discover the rename on its own.

Errors

GET /pages/{pageId}/analysis

Get the page's latest SEO analysis, including its per-criterion components and its recommendations. Returns the most recent analysis that isn't skipped.

Scope: sites:read

Query parameters

Request

curl https://new.metamonster.ai/api/v1/pages/5001/analysis \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": {
    "id": 7200,
    "page_id": 5001,
    "site_id": 42,
    "snapshot_id": 8100,
    "status": "completed",
    "overall_score": 78,
    "overall_grade": "B",
    "estimated_score": 90,
    "estimated_grade": "A",
    "analyzed_content": {
      "hash": "9f2c…",
      "fields": {
        "title": { "value": "Pricing — Example", "hash": "1a3b…" },
        "meta_description": { "value": "…", "hash": "4c5d…" },
        "schema": { "value": null, "hash": "6e7f…" },
        "body_content": { "value": "# Pricing…", "hash": "8a9b…" },
        "primary_keyword": { "value": "pricing", "hash": "0c1d…" },
        "secondary_keywords": { "value": "plans\ntiers", "hash": "2e3f…" }
      },
      "sources": {
        "title": { "source": "draft", "draft_id": 4410 },
        "meta_description": { "source": "snapshot" },
        "schema": { "source": "none" },
        "body_content": { "source": "content_version", "content_version_id": 9100 }
      }
    },
    "score_source": "audit",
    "verified_at": null,
    "content_stale": false,
    "curve_shape": "proportional",
    "triggered_by": "auto_run",
    "started_at": "2026-07-19T17:55:00Z",
    "completed_at": "2026-07-19T18:00:00Z",
    "created_at": "2026-07-19T17:55:00Z",
    "updated_at": "2026-07-19T18:00:00Z",
    "components": [
      {
        "id": 6100,
        "analysis_id": 7200,
        "component_type": "title",
        "label": "Title tag",
        "status": "completed",
        "score": 80,
        "grade": "B",
        "estimated_score": 95,
        "estimated_grade": "A",
        "criteria_scores": { "…": "…" },
        "rationale": "The title is clear but could include the primary keyword earlier.",
        "model": "claude-…",
        "created_at": "2026-07-19T18:00:00Z",
        "updated_at": "2026-07-19T18:00:00Z"
      }
    ],
    "recommendations": [
      {
        "id": 5500,
        "analysis_id": 7200,
        "page_id": 5001,
        "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": "pending",
        "target_field": "title",
        "operation": "replace",
        "sort_order": 1,
        "created_at": "2026-07-19T18:00:00Z",
        "updated_at": "2026-07-19T18:00:00Z"
      }
    ]
  }
}

The top-level object is the analysis. Key fields:

Each component carries: id, analysis_id, component_type, label, status, score, grade, estimated_score, estimated_grade, criteria_scores, rationale, model, site_id, created_at, updated_at.

Each recommendation carries: id, analysis_id, page_id, site_id, title, description, why_it_matters, impact, status, source, source_components, operation, target_field, target_node_ids, after_node_id, insertion_point, rubric_criteria, resolution_method, resolved_at, dismissal_rationale, sort_order, point_value, carried_from_recommendation_id, verification, content_excerpt, created_at, updated_at.

status lifecycle: pending (open, not yet acted on) → in_progress (an AI action or edit is underway) → applied (change made, points earned) or dismissed (rejected — see dismissal_rationale).

• point_value (integer | null) — additive score points this recommendation is worth. estimated_score = overall_score + the sum of open recommendations' point_value. null on recommendations predating the additive model.
• carried_from_recommendation_id (integer | null) — set on display-only history rows carried forward (status applied) from a prior analysis. Exclude these when counting or summing this analysis's work.
• verification (object | null) — AI verification verdict for an applied recommendation; null until verified. Shape: { addressed: boolean, reasoning: string, placeholders: string[], skipped: boolean, validation_scope: string|null, validated_node_ids: string[]|null }. addressed: false means the applied change did NOT resolve the recommendation and it earned no points. skipped: true means no validator verdict backs the pass (force-resolved, or the validator was unavailable) — it does NOT count toward the verified score; recheck to confirm it. placeholders lists template fragments (e.g. "[Your Company]") a human must replace before publishing. validation_scope/validated_node_ids record which content the verdict was formed against; validation_scope is null when no scope was recorded (force-resolved, verified in-app outside this API, or written before scopes existed) — see recommendations.md.
• content_excerpt (string | null) — markdown of the doc node(s) this recommendation targets, so you can locate the passage without ProseMirror node ids. Populated for body_content-target recommendations when the targeted nodes could be resolved from the current content version; null for metadata-target recommendations or when nothing could be resolved.

Act on individual recommendations with Recommendations: dismiss, resolve (with AI verification), and recheck.

Analyzed content provenance

analyzed_content.sources tells you exactly which content the score was formed against — the answer to "did my pending draft count?".

• draft — an active draft (status draft, pending or generating) supplied the value; draft_id identifies it. A draft with a blank or null value is skipped in favour of the snapshot.
• snapshot — the value came from the last crawl of the live page.
• none — neither a draft nor the snapshot had a value, so nothing was scored for that field.
• content_version — the body markdown was rendered from that content version; content_version_id is the version that was scored.

sources is absent on analyses that ran before provenance was recorded (it is descriptive only and is not part of hash, so it never affects change detection). Treat a missing sources as "unknown", not as "nothing was drafted".

Comparing against a previous analysis

?compare= returns the same analysis with a comparison block attached: what the score, each component, each criterion and each recommendation did between that earlier run and this one. It's the "did my edits work?" call — one request instead of fetching two analyses and diffing them yourself.

curl "https://new.metamonster.ai/api/v1/pages/5001/analysis?compare=prev" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

{
  "data": {
    "id": 7201,
    "overall_score": 84,
    "overall_grade": "B",
    "components": ["…"],
    "recommendations": ["…"],
    "comparison": {
      "previous_analysis_id": 7200,
      "previous_analyzed_at": "2026-07-19T18:00:00Z",
      "overall_score": { "prev": 72, "now": 84, "delta": 12 },
      "overall_grade": { "prev": "C", "now": "B" },
      "components": [
        { "component_type": "metadata", "score": { "prev": 70, "now": 90, "delta": 20 } },
        { "component_type": "content", "score": { "prev": 74, "now": 80, "delta": 6 } }
      ],
      "criteria": [
        { "component_type": "metadata", "key": "title_keyword", "label": "Keyword in title", "prev": 1, "now": 4, "delta": 3 },
        { "component_type": "metadata", "key": "meta_length", "label": "Meta description length", "prev": null, "now": 3, "delta": null }
      ],
      "recommendations": {
        "new": [{ "id": 5610, "title": "Add an FAQ block", "…": "…" }],
        "still_open": [{ "id": 5611, "title": "Tighten the meta description", "…": "…" }],
        "resolved": [{ "id": 5612, "title": "Lead the title with the primary keyword", "…": "…" }],
        "dropped": [{ "id": 5502, "title": "Add an internal link to /pricing", "…": "…" }]
      },
      "matching": "best_effort_title"
    }
  }
}

Recommendation buckets (new, still_open and resolved hold recommendations from the current analysis; dropped holds them from the earlier one), each in the same shape as recommendations on the analysis itself:

A recommendation that both runs raised but you dismissed appears in no bucket: it's neither progress nor outstanding work.

Matching is best-effort. Nothing links a recommendation from one run to "the same" recommendation in the next — each analysis writes fresh rows. Recommendations are paired by target_field plus a normalized title (lowercased, punctuation stripped, whitespace collapsed), so wording churn like Lead the title with the primary keyword. ≡ Lead the title with the PRIMARY keyword still matches, but a genuine rewrite reads as one dropped plus one new. Treat the buckets as a summary, not a ledger.

Two more caveats:

• Scores are only comparable within one curve_shape (the grade curve was recalibrated 2026-07-23). Check curve_shape on both analyses before quoting a delta.
• comparison can be null — always a 200, never an error. comparison_note says why:

Errors

GET /pages/{pageId}/analyses

Score history for a page — its completed analyses, newest first. This is the "did my edits move the number?" view: run it after an analysis completes to see the new score next to the old ones, per criterion.

Only completed analyses appear. A history is a series of comparable scores, and queued, failed or skipped runs have none. Recommendations aren't included — read those from GET /pages/{pageId}/analysis for the latest run.

Scope: sites:read

Path parameters

Query parameters

Request

curl "https://new.metamonster.ai/api/v1/pages/5001/analyses?limit=5" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 7200,
      "page_id": 5001,
      "site_id": 42,
      "snapshot_id": 8100,
      "status": "completed",
      "overall_score": 78,
      "overall_grade": "B",
      "estimated_score": 90,
      "estimated_grade": "A",
      "score_source": "audit",
      "content_stale": false,
      "curve_shape": "proportional",
      "triggered_by": null,
      "started_at": "2026-07-19T17:55:00Z",
      "completed_at": "2026-07-19T18:00:00Z",
      "created_at": "2026-07-19T17:55:00Z",
      "updated_at": "2026-07-19T18:00:00Z",
      "components": [
        {
          "id": 6100,
          "analysis_id": 7200,
          "component_type": "title",
          "label": "Title tag",
          "score": 80,
          "grade": "B",
          "criteria_scores": { "…": "…" },
          "rationale": "The title is clear but could include the primary keyword earlier."
        }
      ]
    },
    {
      "id": 7050,
      "page_id": 5001,
      "status": "completed",
      "overall_score": 64,
      "overall_grade": "C",
      "completed_at": "2026-07-05T11:20:00Z",
      "components": []
    }
  ],
  "meta": { "total": 7, "page": 1, "per_page": 5 }
}

Each entry is the same shape as the analysis object in GET /pages/{pageId}/analysis — same fields, same meanings — with two differences:

• No recommendations. They belong to a single run; get them from the analysis endpoint.
• components is present only with include=criteria (the default), and is [] for an analysis whose components weren't recorded. Each component carries the same fields as on the analysis endpoint, including criteria_scores — join criteria_scores[].key to GET /sites/{siteId}/rubric to see what a line item was scored against.

meta.total counts every completed analysis for the page, not just this page of results.

Comparing scores: only compare analyses with the same curve_shape — the grade curve was recalibrated on 2026-07-23, so a flat score and a proportional score aren't on the same footing. content_stale: true on the newest entry means the page changed after that run, so its score describes content that no longer exists.

Errors

POST /pages/{pageId}/analyze

Trigger a new SEO analysis for a page. Fully async: guards run synchronously in this request, the actual scoring runs in a worker. Returns 202 with a job id to poll.

Scope: content:write

Path parameters

Request body

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

Forcing a fresh audit regardless of whether content changed:

curl -X POST https://new.metamonster.ai/api/v1/pages/5001/analyze \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "force": true }'

Response 202

{ "data": { "job_id": "job_an_7301", "status": "queued", "page_id": 5001, "retry_after_seconds": 2 } }

Entitlement guard mirrors the dashboard exactly (the API is not a side door around billing) — three distinct 402 paths, checked in this order:

1. Active subscription, but the plan's page-audit allowance for this period is used up → payment_required with details: { limit, used, remaining }.
2. No active subscription, and this isn't the site's homepage → payment_required, no details.
3. No active subscription, this IS the homepage, but the one-time free preview audit was already used → payment_required, no details. (The homepage gets exactly one free preview analysis without a subscription — mirrors the dashboard's onboarding flow.)

triggered_by on the resulting analysis is null for key-triggered runs (distinguishing them from dashboard-triggered ones).

The page must have something to analyze: a snapshot, a content version, or at least one active draft. An analysis already in progress for the page (status pending/processing) blocks a second trigger — poll the existing job instead of retrying.

Errors

POST /sites/{siteId}/analyze

Trigger analyses for up to 50 pages of one site in a single call — the bulk form of POST /pages/{pageId}/analyze. Same guards per page, one 202 for the batch.

Scope: content:write

Every page runs through the same entitlement, content, and in-progress gates as the single trigger, so each one either mints a job or comes back in skipped carrying the reason the single route would have raised as an error. The response is always 202, even when nothing was queued — the outcome is per page, so the status code can't carry it. Branch on meta.queued. Poll the jobs it mints with GET /jobs?ids= — up to 50 per request, so a whole batch is one poll.

Path parameters

Request body

Provide exactly one of page_ids or filter — both, or neither, is a 400.

curl -X POST https://new.metamonster.ai/api/v1/sites/42/analyze \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_ids": [5001, 5002, 5003], "force": true }'

Re-auditing everything you've marked priority:

curl -X POST https://new.metamonster.ai/api/v1/sites/42/analyze \
  -H "Authorization: Bearer mm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filter": "priority" }'

Pages are queued one at a time, in order, and your plan's page-audit allowance is re-checked for each one. A batch bigger than your remaining allowance therefore partial-queues: the first N pages get jobs and the rest come back as allowance_exhausted. It never overshoots the limit, and it never fails the whole call over it.

Response 202

{
  "data": {
    "jobs": [
      { "page_id": 5001, "job_id": "job_an_7301", "retry_after_seconds": 2 },
      { "page_id": 5002, "job_id": "job_an_7302", "retry_after_seconds": 2 }
    ],
    "skipped": [
      { "page_id": 5003, "reason": "analysis_in_progress", "message": "An analysis is already in progress for this page." }
    ]
  },
  "meta": { "requested": 3, "queued": 2, "skipped": 1, "truncated": false }
}

meta.queued + meta.skipped always equals meta.requested.

Skip reasons

Errors

Only whole-call failures are errors here; a per-page problem is a skipped entry.