create_comparison_page
Generate a comparison or 'X vs Y' page for your brand, using research mode to crawl competitors or simple mode to write from your own data.
Instructions
Create a comparison / 'X vs Y' / 'best ' page for the brand WITHOUT going through the full SEO cluster → brief flow. One call kicks off generation and returns quickly with an operationId and a 'still_generating' or 'completed' status — it does NOT block until the page is fully built. mode controls the engine: 'research' crawls the named competitors + live SERP results before writing — slower (can take several minutes) but produces the strongest, best-grounded page; 'simple' skips all crawling and lets the LLM author from what you provide — fast, best when you already have the facts or just want a quick draft. When your inputs are sparse (few/no options, no domains, no seedData), prefer 'research' — it will discover and ground the comparison for you and yield a far stronger page than 'simple'. seedData (simple mode): paste your own raw facts/notes/competitor details here and the LLM writes from them instead of crawling — this is how you feed your own data and avoid a crawl. Async — fires the create, then waits only a short grace window before responding. On success returns { briefId, sidePageId, sidePageSlug, landingPageSlug, webUrl, warnings }. If it is still running past the grace window, returns { status: 'still_generating', operationId } — poll get_job with that operationId until state is 'completed'; do NOT fabricate the page yourself, and do NOT call create_comparison_page again for the same request while it's pending. Any warnings are surfaced verbatim — relay them to the user (e.g. sparse-input notes such as 'research mode would produce a stronger page').
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Generation engine. 'research' = crawl the competitors + live SERP, then write (slower, strongest, best for sparse inputs). 'simple' = no crawl, LLM authors from what you pass (fast; pair with seedData to feed your own facts). | |
| preset | No | Page shape: head_to_head (X vs Y), alternatives_listicle (X vs alternatives), or category_roundup (best <category>). Inferred when omitted. | |
| brandId | No | Brand ID (defaults to active brand) | |
| options | No | The things being compared. Omit to let research mode discover them. | |
| seedData | No | Simple-mode only: your own raw data/notes/facts about the options. When set, the LLM writes from this instead of crawling — feed it here to avoid a research crawl. | |
| briefData | No | Advanced: a full pre-built structured comparison brief. When supplied, generation uses it directly and skips the LLM authoring step. | |
| proposedSlug | No | Desired URL slug fragment for the new page (auto-generated from primaryKeyword if omitted). | |
| primaryKeyword | Yes | The topic/keyword the page targets, e.g. "Acme vs alternatives", "best CRM for startups", "Notion vs Obsidian". | |
| voiceProfileId | No | Voice profile ID to write the page in. | |
| pinnedCompetitor | No | A specific competitor to anchor a head-to-head comparison around. | |
| allowGenericRoundup | No | Allow a generic category roundup when no concrete options are supplied. | |
| parentLandingPageSlug | No | Slug of the parent landing page to nest this comparison under. Defaults to the brand's primary landing page. |