Content ideas

Content ideas

Subscription required. Every endpoint on this page needs an active subscription. Without one the request is refused with 402 payment_required (Pick a plan to keep going.) before the endpoint runs, reads included. See Conventions.

Content ideas are available to every account.

MetaMonster studies a site's pages and live search data and writes a content playbook: the quick wins to make first (the moves field), strategies (the plays field: themes, such as a page template crossed with a keyword family), and ideas, each a new page to create or an existing page to retitle, expand or optimize. A run also builds the Authority map: the site's core (what it is known for), the topics around it, and the pages drifting away from it. This is the same data as the dashboard's Ideas page.

Scope: sites:read for GET, content:write for POST, PATCH and DELETE.

The flow:

  1. GET /sites/{siteId}/ideas/playbook for the plan, GET /sites/{siteId}/ideas for the ideas, GET /sites/{siteId}/ideas/topics for the Authority map.
  2. POST /sites/{siteId}/ideas/{ideaId}/accept or /dismiss to act on an idea (/restore and /reopen undo those).
  3. POST /sites/{siteId}/ideas/refresh to update the playbook (or start over), then poll GET /sites/{siteId}/ideas/run. A run takes about 10 minutes and has a real cost, so runs are limited (see below).

GET /sites/{siteId}/ideas

The site's ideas in one status, best first (playbook order).

Query Description
status open (default; not started), accepted (in progress, and done too), published (done only) or dismissed.
play A strategy id from the playbook, or none for ideas without an active strategy.
topic A topic id from the Authority map, or none.
funnel tofu (learning), mofu (comparing options) or bofu (ready to act or buy).
change create, retitle, expand or optimize.
q Matches the title and keywords.
page, per_page Pagination (per_page 1-100, default 25).
curl -s "https://app.metamonster.ai/api/v1/sites/42/ideas?funnel=bofu" \
  -H "Authorization: Bearer mm_YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "6f0c9a1e-2b7d-4c1a-9e55-0d3f1a2b3c4d",
      "title": "Roof repair cost in Austin: 2026 price guide",
      "status": "open",
      "action": "create",
      "change": "create",
      "primary_keyword": "roof repair cost austin",
      "secondary_keywords": ["roof leak repair cost"],
      "volume": 390,
      "difficulty": 18,
      "cpc": 12.4,
      "page_type": "service_page",
      "funnel_stage": "bofu",
      "why": "390 searches a month and the top results are national price lists with no local numbers.",
      "caveats": ["Quote real local prices; a range without a source will not rank."],
      "page_id": null,
      "page_path": null,
      "proposed_path": "/roof-repair-cost",
      "play": { "id": "1b2c...", "name": "Local cost guides" },
      "topic": { "id": "9d8e...", "name": "Roof repair" },
      "score": 87.5,
      "source": "suggested",
      "quick_win": true,
      "created_at": "2026-10-09T10:12:00Z",
      "status_changed_at": null,
      "progress": "not_started",
      "in_progress_at": null,
      "done_at": null,
      "done_source": null
    }
  ],
  "meta": { "total": 14, "page": 1, "per_page": 25 }
}
  • change is what the idea does: create a new page, or retitle, expand or optimize an existing one (page_id, page_path).
  • action is as stored: create, optimize, or either (a page partly covers it, so it may be accepted either way; it reads as create).
  • proposed_path is the URL proposed for a new page; null when the idea has a page.
  • progress is where the idea stands: not_started (status open), in_progress (accepted) or done (published); null for a dismissed idea. in_progress_at and done_at say when, and done_source says how it became done: manual, mcp or detected (its page went live in a crawl). See Progress.
  • why is the evidence; caveats are what to watch out for.
  • source is where the idea came from: suggested (a content ideas run), plan (added by a person) or drift (an accepted Drift finding). A refresh only ever retires suggested ideas; the others stay until someone acts on them.
  • quick_win is true when a quick win (move) of the latest playbook links to the idea. It is worked out on the list and on one idea; responses to accept, dismiss and progress carry false.

GET /sites/{siteId}/ideas/{ideaId}

One idea in any status, in full: the fields above plus description, keywords (the measured keywords behind it, each { keyword, volume, kd, cpc }), accepted_action, accepted_keywords, dismiss_reason and dismiss_note.


GET /sites/{siteId}/ideas/playbook

The latest playbook, or { "data": null } before the first successful run.

{
  "data": {
    "id": "c1d2...",
    "created_at": "2026-10-09T10:12:00Z",
    "moves": [
      { "title": "Publish the Austin cost guide", "why": "...", "effort": "S", "searches_per_month": 390, "keywords": ["roof repair cost austin"], "idea_ids": ["6f0c9a1e-..."] }
    ],
    "plays": [
      {
        "id": "1b2c...", "name": "Local cost guides", "pattern": "{service} cost in {city}", "rationale": "...",
        "effort": "M", "channels": [], "notes": [], "rank": 0, "volume": 1240,
        "ideas": [{ "id": "6f0c9a1e-...", "title": "...", "primary_keyword": "roof repair cost austin", "status": "open", "change": "create", "page_path": null, "proposed_path": "/roof-repair-cost" }]
      }
    ],
    "keywords": [{ "keyword": "roof repair cost austin", "play": "Local cost guides", "volume": 390, "kd": 18, "cpc": 12.4, "idea_id": "6f0c9a1e-..." }],
    "notes": [{ "kind": "skipped", "text": "Left out DIY repair guides: the results are video-led." }],
    "mode": "update",
    "changes": ["Kept the cost guides and moved Austin to the top.", "Added a strategy for storm damage."],
    "needs_live_update": false
  }
}

How it was written:

Field Meaning
mode update: written from the playbook before it. rebuild: written from scratch.
changes What an update changed, as plain sentences. Empty for a rebuild.
needs_live_update true when the playbook was written before the site went live and the site has been crawled since. Start an update (POST /sites/{siteId}/ideas/refresh) to check the plan against the real pages and search data.

notes are about the whole playbook: data (limits of the data) and skipped (ideas measured and left out, with why). Warnings about one page are on that idea's caveats.

GET /sites/{siteId}/ideas/topics

The Authority map as data, without drawing coordinates.

{
  "data": {
    "core": { "label": "Residential roofing in Austin", "summary": "..." },
    "topics": [
      { "id": "9d8e...", "name": "Roof repair", "description": "...", "core_distance": 0.1, "distance": "core", "page_count": 6, "drifting_count": 0, "idea_count": 4, "gap": false, "edited": false }
    ],
    "drifting_pages": [{ "page_id": 311, "path": "/careers", "title": "Careers", "topic": null, "reason": "No topic fits this page well" }],
    "cross_topic_pages": [{ "page_id": 305, "path": "/storm-damage", "title": null, "topics": [{ "id": "9d8e...", "name": "Roof repair" }, { "id": "7a6b...", "name": "Insurance claims" }] }]
  }
}

core_distance runs from 0 (the core itself) to 1 (unrelated to what the site is known for); distance is its band (core under 0.25, close under 0.5, adjacent under 0.75, else distant). A topic with gap: true has ideas but no pages yet. core is null and the lists are empty before a run has built the map; planned sites have none.

Correcting the Authority map

The app's map corrections. Each is logged as the key's acting user. Every one is a 409 while a content ideas run is in flight (try again when it has finished). A topic: { "id", "name", "description", "core_distance", "status": "active" | "archived", "origin": "user" | "model", "user_edited_at", "deleted_by_user_at", "page_count" }.

Endpoint Body Response
POST /sites/{siteId}/ideas/topics { "name": 1..80 chars, "description"?: string | null, "core_distance": 0..1 } 201 { "data": { "topic" } }. Runs keep a topic added by hand. 409 when an active topic has the same name (case, punctuation and plurals ignored)
PATCH /sites/{siteId}/ideas/topics/{topicId} any of name, description, core_distance (at least one) 200 { "data": { "topic" } }. Runs keep it as edited from then on. 404 for no such active topic; 409 for a taken name
DELETE /sites/{siteId}/ideas/topics/{topicId} none 200 { "data": { "topic", "pins_reset": [pageId], "outcome": { "resorted": { "pages", "ideas" }, "unplaced": { "pages", "ideas" }, "not_content", "reasons": [...] } } }. Archived (later runs never recreate it); pages pinned to it go back to automatic; its pages and ideas are sorted onto the remaining topics in the request (up to about 25 seconds). Those not placed in time wait for the next run; reasons says why (unavailable, no_topics, past_deadline, failed, over_cap, error)
PUT /sites/{siteId}/ideas/topics/pages/{pageId} exactly one of { "topic_id" } (pin), { "ignored": true | false }, { "reset": true } 200 { "data": { "page_id", "override": { "topic_id", "ignored", "set_at" } | null } }. A pin keeps the page in that topic in later runs; ignored takes it off the map and out of runs; null is automatic. 409 when there is nothing to change

Sharing the playbook

A share link is a read-only public page of the site's latest playbook (quick wins, strategies with their ideas, keywords and notes; no ids, statuses or costs). One active link per site.

Endpoint Response
GET /sites/{siteId}/ideas/playbook-share 200 { "data": { "token", "url", "created_at" } | null }
POST /sites/{siteId}/ideas/playbook-share The active link, or a new one made by the key's acting user: 201 (created) or 200 (existing) { "data": link, "meta": { "created" } }. No body
DELETE /sites/{siteId}/ideas/playbook-share 200 { "data": { "revoked": boolean } }. The link stops working; sharing again makes a new one

POST /sites/{siteId}/ideas/refresh

Start a run. By default a site that already has a playbook is updated: the run keeps the plan and adjusts it to the latest data, and the new playbook says what changed (changes). A site without a playbook gets a new one. Send mode: "rebuild" to start over and write a new playbook from scratch; open ideas the new playbook leaves out are removed, and accepted and published ideas stay. Use it when the business or the site has changed a lot.

Each run has a real cost (paid research and search data), and both modes use one run, so the same limits as the dashboard apply:

Status Code When
402 payment_required No active subscription.
400 invalid_request The site has no crawl and no planned pages yet, the body is not valid JSON, mode is not update or rebuild, or the body has another key.
409 ideas_run_in_progress A run is already in progress (details.run_id).
429 ideas_refresh_cooldown The site had a run in the last 24 hours (details.retry_at).

Request body (optional)

{ "mode": "update" }
Field Type Notes
mode "update" or "rebuild" Optional. No body, or no mode, means update. Any other value, a body that is not valid JSON, or any other key is a 400 invalid_request.

Response 202

{ "data": { "status": "queued" } }

The run takes about 10 minutes. Its id appears on GET /sites/{siteId}/ideas/run once it starts, usually within seconds.

GET /sites/{siteId}/ideas/run

The latest run, or { "data": null } before the first. Spends the jobs rate bucket, so it is safe to poll (every minute or two is plenty).

{
  "data": {
    "id": "e5f6...", "status": "running", "stale": false, "trigger": "manual",
    "stage": "research", "progress": "Measuring 40 keywords", "mode": "update",
    "started_at": "2026-10-09T10:02:00Z", "finished_at": null,
    "ideas": 14, "last_succeeded_at": "2026-09-09T10:11:00Z",
    "can_refresh_at": "2026-10-10T10:02:00Z", "auto_refresh": false, "next_refresh_at": null
  }
}

status is running, succeeded or failed; a run that stopped reporting reads as failed with stale: true. stage is understand, research, validate or write. mode says how the run writes the playbook: update adjusts the current one, rebuild writes it from scratch. It is null for the first seconds of a run, until the worker has settled on one, and for runs from before update mode. ideas and last_succeeded_at describe the last successful run.


POST /sites/{siteId}/ideas/{ideaId}/accept

open → accepted, as an explicit request to act on the idea. Unlike progress with in_progress, which changes the status only, an optimize accept merges the keywords and starts the analysis. The action must fit the idea (400 otherwise); 409 when the idea is not open.

Body For Effect
{ "action": "create", "page_id": 512 } create and either ideas Records the page made for the idea. Create it first with POST /sites/{siteId}/pages (see Pages).
{ "action": "optimize" } optimize and either ideas Adds the idea's keywords to its page's secondary keywords (deduped, 10 at most) and starts a forced analysis so the recommendations target them. The analysis spends one unit of the plan's analysis allowance.

Response 200

{
  "data": {
    "page_id": 204,
    "added_keywords": ["roof leak repair cost"],
    "analysis_started": true,
    "analysis_reason": null,
    "idea": { "id": "...", "status": "accepted", "...": "..." }
  }
}

An analysis that can't start does not undo the accept: analysis_reason is plan_required, already_running or error. Nothing is added (and no analysis starts) when the page already targets every keyword.

POST /sites/{siteId}/ideas/{ideaId}/progress

Moves an idea between Not started, In progress and Done (stored as open, accepted and published), like the stoplight in the dashboard. Needs content:write. Any move works in either direction; asking for the progress the idea is already at changes nothing. 409 when the idea is dismissed or changed since it was read.

Body: { "progress": "not_started" | "in_progress" | "done", "page_id"?: 512 }.

Move Effect
to in_progress, a new-content idea Changes the status and links the planned page; starts nothing paid and generates no content brief. The idea's planned page is page_id if you made one (create it first with POST /sites/{siteId}/pages), else the page it already has from an earlier In progress, else a page is made from the idea (title, proposed path, keywords).
to in_progress, an optimize idea Changes only the status. No keywords are added and no analysis starts, so nothing spends allowance. To add the keywords and analyze the page, call accept with optimize on a Not started idea, or analyze the page yourself. page_id is a 400.
to done Records done_at and done_source (mcp for a call made through the MCP server, otherwise manual).
back to not_started or in_progress Changes only the status. The planned page, the added keywords and the accept record stay. Leaving done clears done_at and done_source.

Analysis and briefs are explicit actions, but making one moves the idea along: when an analysis completes for a page, or a content brief is generated for it, every Not started idea of the site whose page_id is that page moves to In progress by itself. Dismissed, in progress and done ideas are left alone.

A new-content idea that is In progress is also marked done by itself, with done_source: "detected", when a crawl after it started In progress finds its page live.

Response 200

{
  "data": {
    "page_id": 204,
    "added_keywords": [],
    "analysis_started": false,
    "analysis_reason": null,
    "idea": { "id": "...", "status": "accepted", "progress": "in_progress", "in_progress_at": "2026-10-21T15:04:00Z", "...": "..." }
  }
}

page_id is the page made or already planned for a new-content idea moved to In progress, otherwise the idea's page (null when it has none). added_keywords is always empty and analysis_started always false here (the fields match accept, which does add keywords and start an analysis).

POST /sites/{siteId}/ideas/{ideaId}/dismiss

open → dismissed. Body: { "reason": "not_relevant" | "already_covered" | "not_now" | "wont_rank" | "other", "note"?: string } (note up to 500 chars). Later runs do not suggest the idea's keywords again. Response 200: { "data": ContentIdeaDetail }. 409 when the idea is not open.

POST /sites/{siteId}/ideas/{ideaId}/restore

dismissed → open, the app's Restore. No body. The idea comes back to the calendar at the end of the queue (a date the owner set that is still ahead is kept). Response 200: { "data": ContentIdeaDetail }. 409 when the idea is not dismissed.

POST /sites/{siteId}/ideas/{ideaId}/reopen

accepted → open, the app's Move back to Not started. No body. The page it pointed at before it was accepted comes back and its accepted keywords are cleared; a page made for it stays. Done ideas stay done (use /progress). Response 200: { "data": ContentIdeaDetail }. 409 when the idea is not accepted.

Playbook steering (preview)

In the app it is the Steering section of the Playbook's Settings.

Steering says what the owner wants the playbook to go after: a goal, kinds of ideas each less, normal or more (comparison, guide, refresh of the site's pages, product and feature pages, glossary, location), focus topics or keywords, what to avoid (one per line), and pages_wanted (pages the owner already wants, pasted as they gave them, with dates: the next run makes them ideas first, with their dates, and later runs leave those ideas to the owner). Every full content ideas run follows it (an update, a start over, and the monthly refresh); it never overrides the facts. How to write belongs in the site's guidance.

GET /sites/{siteId}/playbook/steering · PUT /sites/{siteId}/playbook/steering

GET returns the steering (the defaults, with updated_at null, when none was saved) and monthly_refresh (the site's monthly refresh, the same switch as Settings). PUT changes only the fields sent (kinds and focus replace the whole map or list; monthly_refresh turns the monthly refresh on or off); saving runs nothing. Response 200: { "data": PlaybookSteering }.

The content calendar

Each site has one content calendar. Every not-started and in-progress idea gets a date when it appears: the next free date of the site's repeat rule (by default every Tuesday, one idea each), in queue order (ideas linked from the playbook's moves first, in move order, then by play rank, then by score), after the latest scheduled idea. Dates never move as days pass: an idea whose date has passed stays there, overdue, until it is moved or done. A done idea shows on the day it was done. Dismissed and retired ideas leave the calendar; their dates stay empty until Reschedule from today. An idea that comes back (restored, or suggested again by a later run) gets a fresh place at the end of the queue, unless its date was set by hand and is still ahead.

The API works in UTC: "today", overdue and done_on are UTC dates. done_at is the exact moment, for clients that show it in a local time zone, as the dashboard does.

The repeat rule is an iCalendar RRULE subset, one idea per matching date:

Rule Means
FREQ=WEEKLY;INTERVAL=1;BYDAY=TU Every week on Tuesday (the default)
FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TH Every 2 weeks on Monday and Thursday
FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15 Every month on the 15th (a month without the day, such as the 31st in April, is skipped)
FREQ=MONTHLY;INTERVAL=1;BYDAY=1TU,3TU Every month on the first and third Tuesday (-1FR is the last Friday)

COUNT, UNTIL and other parts are a 400 that says why. INTERVAL counts from the calendar's start (start_on, the next Monday after the calendar is first laid out unless set).

A calendar entry: { "idea_id", "title", "progress": "not_started" | "in_progress" | "done", "scheduled_on", "scheduled_by_owner", "done_on", "done_at", "overdue", "position", "action": "create" | "optimize" }. Settings: { "site_id", "rule", "start_on" }.

Endpoint Body Response 200
GET /sites/{siteId}/ideas/calendar?from=&to= none (range at most 400 days; default four weeks back to twelve ahead) { "data": { "settings", "entries": [...] } }. A read never writes: an idea with no date yet has scheduled_on: null until the app's calendar or the next ideas run places it
PATCH /sites/{siteId}/ideas/calendar/settings { "rule"?, "start_on"? } (null resets the start) { "data": settings }; future dates not set by hand are laid out again
POST /sites/{siteId}/ideas/calendar/schedule { "idea_id", "on" } or { "idea_id", "snooze_weeks": 1..52 } { "data": entry }; a snooze counts from the idea's date, or from today when that date has passed. The date is then set by hand. 409 for a done idea
POST /sites/{siteId}/ideas/calendar/shift { "after": "2026-11-01", "weeks": -52..52 } { "data": { "moved" } }; moved dates are set by hand
POST /sites/{siteId}/ideas/calendar/reorder { "idea_ids": [...] } { "data": { "moved" } }; the ideas named come first, and future dates not set by hand follow the new order
POST /sites/{siteId}/ideas/calendar/reschedule none { "data": { "moved" } }; every not-done idea not set by hand, future or overdue, goes back onto the rule from today
POST /sites/{siteId}/ideas/calendar/ics-link { "reset"?: true } or none { "data": { "url" } }: the calendar feed (ICS) to subscribe to from Google Calendar and others, made on first use and the same after. Anyone with the link can read the schedule. reset: true replaces it and the old link stops working

Dates set by hand (scheduled_by_owner) are never moved by a layout, only by schedule or shift.

Ideas from Drift

POST /sites/{siteId}/drift/groups/{groupKey}/accept (needs Drift too) turns a Drift finding group into ideas: each page the group affects gets one open optimize idea with source: "drift", titled Fix: <finding> on <path>, its keyword the page's primary keyword (else its path), and evidence.drift holding the group key, the finding ids and the suggested rewrite. A finding that blames one page adds that page; one across pages adds every page its versions are on. Two or more pages also get one strategy holding them (shown as From Drift). The findings become confirmed. Nothing is queued: add the ideas to Up next in the app. Content ideas runs never retire these ideas.

Response 200: { "data": { "idea_ids": [...], "strategy_id": "..." | null } }. Accepting the same group again creates nothing and returns the same ids. 409 not_acceptable for a dismissed group or one with no live page; 404 for a group not on the site.