Site planning
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.
A planned site is a site that isn't live yet. You describe the business in a brief, MetaMonster proposes the pages the site needs, assigns each a primary keyword, and you build the content before launch. When the site is published, going live crawls it and matches the crawled URLs to the planned pages by path, so their keywords, briefs and content carry over. This is the same flow as the dashboard's Plan a site.
Planned pages are ordinary pages with planned: true and no URL. Briefs (POST /pages/{pageId}/outline, then /outline/build), body content (POST /pages/{pageId}/content) and drafts all work on them.
Scope: sites:read for GET, content:write for everything else.
The flow:
POST /sites/plancreates the planned site.POST /sites/{siteId}/plan/generateproposes the page set.POST,PATCHandDELETEon/sites/{siteId}/plan/pagesrefine it.POST /sites/{siteId}/plan/keywordsassigns keywords; pollGET /sites/{siteId}/plan.POST /sites/{siteId}/go-liveonce the site is published.
POST /sites/plan
Create a planned site. No domain is needed and nothing is crawled.
Body
| Field | Type | Description |
|---|---|---|
brief |
string | Required unless suggest_pages is false; up to 20,000 chars. What the business does, who it serves, where, and its services or products. |
suggest_pages |
boolean | Optional, default true. false proposes no pages: the site starts with the homepage only, you add the rest with POST /sites/{siteId}/plan/pages, and generate returns the pages as they are without a model call (regenerate is a 400). Keywords are optional for these sites: assign them when you want, going live doesn't need them. |
name |
string | Optional. A working name, or the domain the site will launch on. Derived from the brief when omitted. |
location_country_code |
integer | Optional. DataForSEO country code for keyword research. Derived from the brief when omitted (US if unclear). |
location_country_name |
string | Optional. |
Without name or a location (and with a brief), one model call derives them, so this route spends the llm rate bucket (6 requests per 60 seconds). An organization without an active subscription gets 402 payment_required before anything is created.
curl -s -X POST "https://app.metamonster.ai/api/v1/sites/plan" \
-H "Authorization: Bearer mm_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"brief": "Family-owned roofing company in Austin, TX. Repairs, replacements and storm damage for homes."}'
Response 201
{ "data": SiteDetail } (see Sites). url is null until the site goes live.
POST /sites/{siteId}/plan/generate
Propose the page set from the brief, and structure the brief into the site's business_context and voice_tone. Idempotent: when planned pages already exist they are returned without a model call.
When the brief names its pages, only those (plus the homepage, always) are created. The other pages a site like this usually has come back as suggested_pages and are not created until you add them with POST /sites/{siteId}/plan/pages. When the brief names none, every proposed page is created and suggested_pages is empty.
| Field | Type | Description |
|---|---|---|
regenerate |
boolean | Optional. Replace the whole set with a fresh proposal. |
brief |
string | Optional. A revised brief; it replaces the stored one before generating. |
Generating takes two model calls (typically 10-30 seconds) and spends the llm rate bucket.
Response 200
{
"data": {
"pages": [
{ "id": 501, "name": "Home", "slug": "", "purpose": "Introduce the company and route visitors to services" },
{ "id": 502, "name": "Roof Repair", "slug": "services/roof-repair", "purpose": "Explain repair services and get quote requests" }
],
"suggested_pages": [
{ "name": "About Us", "slug": "about", "purpose": "Show the team and build trust" }
],
"brief": "Family-owned roofing company in Austin, TX. ..."
}
}
GET /sites/{siteId}/plan
The planned pages and keyword progress. Spends the jobs rate bucket, so it is safe to poll.
Response 200
{
"data": {
"total": 2,
"with_keyword": 1,
"failed": 0,
"done": false,
"keywords_running": true,
"crawl_status": null,
"pages": [
{ "id": 501, "name": "Home", "path": "/", "purpose": "...", "primary_keyword": "austin roofing company", "failed": false },
{ "id": 502, "name": "Roof Repair", "path": "/services/roof-repair", "purpose": "...", "primary_keyword": null, "failed": false }
],
"suggested_pages": [
{ "name": "About Us", "slug": "about", "purpose": "Show the team and build trust" }
]
}
}
failed counts pages whose keyword assignment terminally failed. crawl_status is null until the site goes live, then the status of its latest crawl. suggested_pages are pages the brief didn't name that the site could have; they are not created. Adding a planned page with the same slug (POST /sites/{siteId}/plan/pages) removes its suggestion.
POST /sites/{siteId}/plan/pages
Add a planned page, including one of the suggested_pages (use its name, slug and purpose). Body: { name, slug?, purpose? }. The slug is normalized like proposed paths (About Us becomes about-us, home is the homepage) and made unique; without one it is the slugified name. Response 201: { "data": { id, name, slug, purpose } }.
PATCH /sites/{siteId}/plan/pages/{pageId}
Edit a planned page. Body: at least one of name, slug, purpose. Response 200: the updated page. 404 for a page that isn't a planned page of this site.
DELETE /sites/{siteId}/plan/pages/{pageId}
Remove a planned page (soft delete; its slug is freed). Its work item goes with it if it hasn't started; once the page's work has started, removing it is a 409. Response 200: { "data": { "id": 502, "deleted": true } }.
POST /sites/{siteId}/plan/keywords
Assign a primary keyword to every planned page that has none yet. Each is picked from the page's name and purpose and the site's business context, checked against search data. Free.
Queued: answers 202 { "data": { "started": true } } at once. Poll GET /sites/{siteId}/plan until keywords_running is false. Nothing new is queued while an assignment is running (already_running: true).
This is the plan's confirmation. With work items on, each planned page also gets a queued "create" work item (Home first, then plan order) that waits in Up next; none start on their own, and confirming again adds none. From then on, a page added to the plan gets its item.
POST /sites/{siteId}/go-live
Take the site live. Body: { "domain": "acmeroofing.com" } (a scheme or path is stripped; a plain name is 400). The domain replaces the working name and a crawl starts.
Response 202
{ "data": { "crawl_id": 812, "status": "pending", "domain": "acmeroofing.com" } }
409 conflict when the site is already live or a crawl is running. Follow the crawl with GET /sites/{siteId} (latest_crawl) or GET /sites/{siteId}/plan (crawl_status).