Add a new custom domain to the active brand. After adding, call verify_domain to check DNS and activate it.

Applies a completed vibe edit (from vibe_edit_landing_page) to the DRAFT as ONE new version. Pass exactly one of: all=true (accept every change), indices (subset by their index from get_vibe_edit_status), or paths (subset by their path). This does NOT publish — call publish_landing_page next to go live. Can be undone via restore_lp_version using the returned previousVersionId. If the draft has moved on since the edit was proposed (stale session), this returns a structured { error: 'stale_session', ... } payload instead of applying — either re-run vibe_edit_landing_page against the current draft, or retry this call with force=true to layer the selected changes onto the current draft.

Approve and schedule a draft post. Requires a future datetime. The scheduledAt must be an ISO 8601 UTC datetime, e.g. 2026-03-11T09:00:00Z. After approving, the post status becomes 'scheduled'.

Assign, reassign, or clear the asset in a landing-page or side-page slot. slotKey is a dotted key like 'hero.backgroundVideo' or 'cta.image' (discover valid keys with list_asset_slots). For array slots pass assetIds; for single slots pass assetId. The asset must already be in the brand's library (see list_assets / upload_asset / import_asset_from_url) and match the slot's media type. Pass sidePageSlug to target a side page. Set clear:true (or assetId:null) to empty the slot. Synchronous — the change applies immediately, no polling. Main-LP changes create a new draft version.

List available credit packs for one-off top-ups. Returns all packs with their SKU, price in USD, and credit amount. Call this tool first to show the user their options, then ask which pack they want. Only after the user explicitly chooses a pack, call billing_topup with that packSku.

List available PostKing subscription tiers (GROWTH, PRO, ENTERPRISE). Returns each tier's name, price in USD, monthly credits, and billing interval options. Use billing_subscribe to create a subscription Checkout session for a chosen tier.

Create a Stripe Checkout session for a PostKing subscription. Returns { checkoutUrl, sessionId, tier, interval, amountUsd }. Subscription credits refill User.credits each billing period. The subscription Checkout is best completed by a human; the Link virtual card covers the first invoice only (renewals need a durable payment method).

Top up credits by charging the account's card on file (Stripe off-session). Prefers the headless path — no checkout link required. IMPORTANT: Only call this tool after the USER has explicitly chosen a specific pack — it triggers a real charge. To show the user their options first, call billing_list_packs and present the results; do NOT pick a pack on the user's behalf. The response is ONE OF two shapes: (1) Headless success (default when a card is on file): { status: 'paid', paymentIntentId, amountUsd, credits, balance, packSku, cardLast4/receiptUrl when available }. When you receive status === 'paid', the payment has already completed and the credits are in the wallet NOW. Announce to the user: payment ID, last-4 card digits, credits added, and new balance. You are DONE — do NOT call billing_wallet to poll. (2) Checkout fallback (only when there is no card on file): { checkoutUrl, sessionId, amountUsd, credits, packSku }. When you receive checkoutUrl, hand that link to the user so they can complete payment in their browser. Valid skus: agent_4 ($4 / 160 credits), agent_5 ($5 / 220 credits), agent_25 ($25 / 1200 credits), agent_50 ($50 / 2600 credits).

Fetch the user's credit balance and recent usage entries. Returns { credits, recent } where recent is the last ~10 usage rows. Poll this to confirm a top-up landed ONLY after a billing_topup CHECKOUT result (one that returned a checkoutUrl), until credits rise. Do NOT poll after a status:'paid' headless top-up — those credits are already applied and the new balance is in the topup response.

Capture brand truths from plain natural-language text. Describe facts/observations about the brand in ordinary prose — a sentence or short paragraph (≤8000 chars). Do NOT pre-classify, pre-format, or guess the taxonomy: PostKing's LLM extraction pipeline reads the text and decides which atomic 'brand truths' to persist and which to skip (duplicates, too vague, or previously rejected facts). Returns { addedCount, skippedCount, added, skipped }: 'added' are the truths that were stored; 'skipped' lists each rejected quote with a reason. Review both — the skipped reasons tell you what didn't make it in and why.

Delete a brand truth by ID. This also records rejection memory: the system learns to stop re-suggesting that fact during future extractions. Use it deliberately — deleting a truth teaches PostKing that the fact should not come back.

Fetch a single brand truth by ID. short {id,name,type,pinned}; medium adds personaScope+tags+summary+timestamps; full = raw (includes full content). Use detail='full' to retrieve the complete content body.

List the brand's stored brand truths (atomic facts/observations used to ground generation). short {id,name,type,pinned}; medium adds personaScope+tags+summary+timestamps; full = raw. Filter by type, personaScope, tags (array or comma-separated), or a free-text query.

Targeted edit of an existing, known brand truth (by ID). This does NOT re-run the LLM extraction pipeline — it writes the provided fields directly. Use it to correct wording (name/description/content), fix the type/personaScope, adjust tags, or pin/unpin. To capture NEW facts from prose, use brand_truth_create instead.

Cancel a pending or running job/operation. Flips it to cancelled and stops it from being polled. Note: work already in flight may still finish server-side, but its result is discarded. Already-finished jobs cannot be cancelled. Pass the operationId (from list_jobs pollUrl / get_job).

Cancel a scheduled or approved post, reverting it to draft status without deleting it. Use delete_post to remove it entirely.

Check whether text is likely AI-generated. Returns a score and analysis.

List all connected and disconnected social accounts for the active brand. Lists default short; pass detail=medium/full for more fields. Run before posting to confirm platform availability.

Remove the selected visual from a post for a specific platform. Includes editInVisualEditor: a direct URL to edit the post in the visual editor (when active brand is set).

Async. Batch-add competitor domains (1–20) to the brand. Returns { operationId, status } — poll get_job until state=completed. Each domain triggers crawl + profile analysis. Typically takes ~2–5 min.

Async. Trigger analysis for existing BrandCompetitor rows that are pending or failed. Use competitor_add to create new rows; use this to retry failed ones. Returns { operationId, status } — poll get_job until state=completed. Typically takes ~2–5 min.

List the data sources used to build the brand's competitive comparison. Returns raw source records (URLs, snippets, timestamps) — useful for auditing comparison accuracy.

Soft-delete a tracked competitor from the brand. No credits are refunded. Use competitor_update (empty body) to restore.

Async. Generate the competitive landscape overview (uses ~20 credits). Returns { operationId, status } — poll get_job until state=completed. Typically takes ~2–5 min.

Get the brand's head-to-head competitive comparison. short {id,status,generatedAt,competitorCount}; medium adds summary+strengths+weaknesses; full = raw. Returns null when no comparison has been generated yet — use competitor_recompute_comparison to generate.

Get the brand's competitive landscape overview. short {id,status,generatedAt}; medium adds summary excerpt; full = raw. Returns null when no overview exists — use competitor_generate_overview to create one.

List the brand's tracked competitors. short {id,domain,analysisState}; medium adds source,creditsCharged,lastError,addedAt,lastCrawledAt,cacheSource; full = raw. Also returns a dashboard link to the Competitors tab.

Start a competitor discovery probe. PostKing crawls the web to find rival domains automatically. Returns { started: true } when kicked off, or { alreadyRan, status } when a probe result already exists. Poll competitor_probe_status to check readiness, then use competitor_probe_classify to accept/reject candidates.

Classify a discovered (or manually added) competitor candidate. 'direct' seeds a BrandCompetitor row; 'similar' and 'not_relevant' update the probe JSON only. Call once per domain. Probe must be in completed state first. Returns { candidates } — the updated full candidate list.

Check the status of the competitor discovery probe. Returns { status, candidates? } — status is one of: pending | running | completed | failed. When completed, candidates contains the discovered domains ready for classification.

Trigger a fresh head-to-head comparison recompute. Use after adding or re-analyzing competitors to get an up-to-date comparison.

Async. Refresh all active competitors for the brand (re-crawl + re-profile). Returns { operationId, status } — poll get_job until state=completed. Typically takes ~2–5 min.

Update a competitor's settings. Currently supports toggling excludeFromSeoPull (removes the domain from keyword-gap pull without deleting it). Send an empty body to restore a soft-deleted competitor.

Connect a verified domain to a blog publication so articles are served from that domain. Supports three routingType modes: 'path' ({domain}/blog), 'root' (bare {domain}), and 'subdomain' (blog.{domain} — provisions a separate Domain row that needs its own DNS verification before it resolves).

Create a new PostKing API key. The raw token (pk_live_*) is returned ONCE in this response and never shown again. Store it immediately — treat it like a password. Scope: 'write' (default) or 'read'.

Create a new author for blog articles. Returns an authorId that can be used in generate_blog_post and update_blog_article.

Create a new category in a blog publication.

STEP 1 of brand onboarding (manual path — no website crawl). Creates a new brand from user-supplied name/description, sets it as active, then RETURNS a nextStep payload telling you to ask the user which platforms they publish on. After the user answers, call set_brand_mediums with their picks. Ask the user for a description if they did not provide one — onboarding will fail without it.

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').

Save a post draft with custom content to one or more platforms. Supported platforms: x, linkedin, instagram, threads, facebook. After creating, call approve_post with a future ISO 8601 datetime to schedule it. To check which platforms are connected first, call check_social_accounts. Each created post includes editInVisualEditor: a direct URL to edit it in the visual editor.

Create a new blog publication (the container that articles live under). Returns a publicationId needed for generate_blog_post.

Return a clickable browser link to a PostKing dashboard page. ALWAYS use this instead of guessing dashboard URLs. The SEO roadmap / content plan is section 'seo_briefs' (or 'seo' for the overview) — there is NO '/seo/roadmap' page.

Soft-delete an asset from the brand library. Pass confirm: true to proceed.

Permanently delete a blog article.

Remove a custom domain. Connected blogs and landing pages are unlinked but not deleted.

Permanently delete a landing page. Pass confirm: true to proceed — this is irreversible.

Permanently delete a historical landing page version. Cannot delete the published version or the only remaining version (the server will reject those). Pass confirm: true to proceed.

Cancel and delete a post regardless of its current status (draft, scheduled, or posted).

Permanently delete a blog publication. Only allowed when it has zero articles and no connected domain/external sync/publishing connections — otherwise the API refuses with an explanation of what's still attached (remove/disconnect those first, e.g. delete_blog_article for every article under it).

Delete a side page. Pass confirm: true to proceed.

Permanently delete a historical side-page version. Deleting the current (draft) version is allowed and repoints the draft to the newest remaining version. Cannot delete the published (live) version or the only remaining version — the server will reject those and the rejection reason is returned as-is. Pass confirm: true to proceed.

Delete a content theme from the active brand.

Permanently remove the weekly schedule for the active brand. Pass confirm: true to proceed.

Pause the weekly content schedule without deleting it. Re-enable later with enable_weekly_schedule.

Disconnect a social account by its account ID.

Async LLM ai-edit of the brand's audience/ICP. Describe the change in prompt (natural language). sections is REQUIRED — the audience section(s) to edit (e.g. 'demographics', 'painPoints', 'positioning'). If unsure which sections are valid for this brand, call preview_audience_edit first and use the section keys it returns. Returns { operationId, status } — poll get_job(operationId) until state is 'completed' (or 'failed'/'cancelled' on error). Only one audience edit can run at a time; a second call returns an 'already_running' notice. Typically takes ~30–90 s.

Update METADATA ONLY — title and/or instructions — of a landing page. Does NOT touch page content. For content changes, use set_landing_page_section (targeted field/section writes) or vibe_edit_landing_page (AI-powered edits).

Edit a single carousel card on a post by its 1-based index. Provide title and/or body to update. Set rerender=true to regenerate the visual asset.

Update a side page's page-level metadata and, for type:"text" pages only, its content. Metadata (any side-page type): name (display title, shown in auto-generated footer/nav 'Solutions' links and breadcrumbs), newKey (rename the URL-slug fragment; old URL 404s, no redirect; internal references are rewritten in the background), and instructions (stored as an annotation for future context — does NOT trigger an AI edit). Content — type:"text" pages ONLY: title and/or htmlContent. Text side pages store a flat {title, htmlContent} document, not per-section overrides, so this is the direct way to write their content — landing/comparison pages have no title/htmlContent fields and must use set_side_page_section (or set_side_page_section with instructions-only for an AI rewrite of a text page's whole document) instead. Passing only one of title/htmlContent fetches and preserves the other automatically, so a partial write never clobbers the unset field. Every edit creates a new draft version (see list_side_page_versions / restore_side_page_version) — nothing here is destructive, any write (including a bad title/htmlContent edit) can be undone by restoring a prior version. On a published page, edits stay draft-only until set_side_page_state({published:true}) publishes them. When newKey triggers a reference rewrite, the response includes slugRewriteOperationId — poll it to confirm the cascade finished.

Edit an existing content theme's title or content instructions.

Enable the weekly content schedule without changing its configuration. The schedule must already be created with set_weekly_schedule.

Generate a full AI blog article. Requires a publicationId (from list_blogs or create_publication). Pass a voiceProfileId to write in a specific person's style (IDs from list_voices). Returns an articleId + operationId; generation is async — poll get_blog_status until completed, then get_blog_article. Use update_blog_article to edit, or publish_blog_article to push to external platforms. To make it live on your PostKing blog, call update_blog_article with status: 'published'.

Generate and schedule multiple posts across a date range in the background.

Generate a secure browser link to connect a social media account. Share this URL with the user to complete OAuth.

Create and AI-generate a new landing page for the brand. Step 1: Creates the LP record with the given slug. Step 2: Kicks off async AI content generation immediately. Returns { slug, operationId, pollUrl } — poll with get_job(operationId) until state is 'completed' (or 'failed'/'partially_failed'/'cancelled' on error). For targeted edits to an existing page, prefer vibe_edit_landing_page.

Generate AI content for a platform. Returns quickly with a postId and a 'generating' or 'completed' status — it does NOT block until generation fully finishes. Deducts 10 credits per variation. To control what the post is about, pass theme with a free-text brief (any topic/angle/facts/tone). If you omit theme, the topic is RANDOM — so always pass it when the user wants specific content. When variations > 1, ALL variations are returned under a SINGLE postId in the variations array — it does NOT create one post per variation. content is variation 1 (the primary, already saved on the post). Never call generate_post again to 'get the other variations' — they're all in the response. originalContent (if seen elsewhere) is the pre-voice-rewrite draft, not a separate variation. After generating, use create_post to save a chosen variation, then approve_post to schedule it. To repurpose: call repurpose_content first, then create_post with the result, then approve_post. Generation can take 1-5 minutes (longer with multiple variations or voice rewrite). This tool only waits a short grace period so fast generations can return inline content; if it returns status 'generating', the job is still running server-side — poll get_post with the returned postId until operationStatus is 'completed', then use that content. Do NOT call generate_post again for the same request while it's pending — retrying creates a duplicate draft and wastes credits. After generation, brand visual options (quote/card templates, brand images, stock photos) are prepared but NOT attached — share viewInBrowser for the visual picker, or call pick_post_visual to attach one. Do not attach a visual unless the user chooses it. The response includes editInVisualEditor: a direct URL to edit the post in the visual editor (once completed).

Generate a carousel PDF for a LinkedIn (or other) post from the post's cards. Returns an asset ID and download URL for the PDF. Requires cards to be set first via set_post_cards or edit_post_card.

Fetch available visual options for a post — card templates, library matches, stock photos. Returns a bestPick recommendation plus categorized options per platform. Use pick_post_visual to apply one of the returned options. Returns slim option list with pickArgs by default (medium). Use detail='short' for counts only, 'full' for raw catalog. Includes editInVisualEditor: a direct URL to edit the post in the visual editor (when active brand is set).

AI-generates a side page under a parent landing page. Async — kicks off the side-page generator and returns { success, operationId, operationRowId, pollUrl, sidePageId }. This is the GENERATOR (POST /side-pages/generate) — NOT a row creator. Comparison-type briefs may run synchronously and return sidePageId directly with no operationId. Two body modes: • freeform: pass key + prompt (+ optional keywords, selectedSections, voiceProfileId, sidePageType). Freeform now writes real section-level content (hero/features/showcase/faq/cta), not just metadata. • brief: pass key + brief (structured outline) + optional briefId and roadmapItemId. Poll get_job with the returned operationId until state is completed (or failed/partially_failed/cancelled on error); the generated page's sections will be populated once complete.

Generate or rewrite general-purpose, email-style/formal text — follow-up emails, cover letters, outreach messages, formal notes, etc. Returns quickly with an operationId and a 'still_generating' or 'completed' status — it does NOT block until generation fully finishes. This is NOT for social media posts — use generate_post for those. This is also NOT for a simple voice-only rewrite of existing text with no other options — for that, use rewrite_with_voice or rewrite_text instead. Reach for generate_text when you need mode selection (generate vs rewrite), a stated purpose, a target length, or when there's no source text at all (mode='generate'). mode='generate' writes new text from a prompt (what to write, e.g. 'a follow-up email after a sales call, polite but direct'). mode='rewrite' rewrites existing sourceText into a new form/tone. purpose is optional free text describing the goal, e.g. 'win-back email' or 'job application cover letter'. length can be short | medium | long, or a specific target word count (20-5000). Supports detail param: short=status+wordCount only, medium=truncated content (500 chars)+wordCount (default), full=raw result including content, aiDetectionScore, burstinessScore, promptLogId, wordCount. If it returns status 'still_generating', the job is still running server-side — poll get_job with the returned operationId (wait:true) until state is 'completed', then read the text from the operation's result. Do NOT call generate_text again for the same request while it's pending — retrying wastes effort and may create duplicate work.

Generate new content themes using AI. Waits a short grace window for generation to finish; if it's still running server-side after that, returns a 'generating' status instead of blocking — call list_themes a few seconds later to retrieve the new themes. Deducts credits.

Fetch the brand's audience intelligence / ICP (ideal customer profile). short = compact summary (name + primaryRoles + top painPoints + persona.role); medium adds positioning + fuller demographics; full = the raw payload (audienceData + positioning + persona + contentModulation). persona is the ghostwriter persona ({ role, styleNotes, ... }) and may be null. If the brand has no audience data yet, run website/audience analysis (onboarding) first.

Fetch a blog article by ID. detail='short' returns id/title/slug/status; detail='medium' adds excerpt+wordCount+previewUrl+editUrl; detail='full' (default) returns the COMPLETE content plus previewUrl (GUI preview link) and editUrl (dashboard editor link). Pass maxContentChars only if you need to bound the body size; omit it to get the whole article.

Poll the async generation status of a blog article. Use the articleId returned by generate_blog_post. Status: pending | running | completed | failed.

Get a brand's profile. Returns core identity fields plus slim summaries: themes as [{id,title}], voiceProfiles as [{id,name,isActive,optimizedMedium}], blogAuthors as [{id,firstName,lastName}], and postCount/memberCount as numbers. Use list_themes, list_voices, list_blog_authors, list_posts, or get_brand_members for full detail on each.

Read which publishing platforms (mediums) a brand posts to. Read-only counterpart to set_brand_mediums. NOTE: Reddit is NOT a medium — Reddit is a separate repurpose module; use the reddit_* tools or dashboard_link section 'reddit'.

List all active members of a brand with their role and user info (id, name, email).

View upcoming scheduled posts sorted by date. Returns id+status+scheduledAt by default; use detail='medium' or 'full' for more fields. For a single post use get_post.

Check your current PostKing credit balance and free-tier status.

To check whether ONE specific operation you started is finished, pending, or failed, call this with its operationId (the pollUrl param accepts a bare operationId + brandId). Do NOT use list_operations to check a specific op. Poll the status of any background Operation by its operationId or pollUrl. Returns the Operation row: { id, kind, state (pending|running|completed|partially_failed|failed|cancelled), brandId, scopeType, scopeId, progress, result, errors, startedAt, finishedAt, createdAt, updatedAt }. Call repeatedly until state is 'completed' or 'failed' (or 'cancelled'). When completed, the payload you want is in result; on failure, see errors. Pass wait:true to block until the job is done (polls every 3s, capped at ~30s per call) — preferred over calling repeatedly. For longer-running jobs, call get_job again with wait:true to keep polling until it completes. Most generate_* and vibe_edit_* tools (including seo_generate_clusters and seo_generate_keywords) return an operationId — use this to poll them. Supports detail param: short=id+kind+state+progress, medium=adds timestamps+resultRef (key IDs from result, no full payload), full=raw including complete result JSONB.

STEP 3 of brand onboarding. Polls background analysis + theme generation. detail='short' returns status only; detail='medium' (default) adds audienceSummary+themeCount; detail='full' returns raw data. Poll every ~15s. When done, surface the audience review + themes to the user.

View the full content and status of a single post. Use detail='short'|'medium'|'full' to control verbosity (default full). Multi-variation posts expose a variations array (all variations live on one postId). Output shows the final voice-rewritten content by default; pass includeOriginal=true to also see the pre-rewrite draft. Includes contentReviewUrl: a direct link to read and approve the generated body, and editInVisualEditor: a direct URL to edit the post in the visual editor.

View the SEO / GEO content roadmap — suggested blog topics, keywords, and completion status. detail='short' returns stats only; detail='medium' adds slim item list (id+title+status+keyword); detail='full' (default) returns raw response.

Read a brand's per-platform social media content rules (the same rules editable in dashboard Settings → Social media rules). Covers content/structure/engagement/visual-strategy guidance plus secrets, guidelines, content types, things to avoid, and core principles. Call this BEFORE set_social_media_rules so you only change the fields you intend to.

Poll vibe (AI) edit session status. detail='medium' (default) is the REVIEW view: { status, progress, stale, baseVersionId, currentVersionId, changesCount, credits, changes, error } where each changes entry is { index, path, before, after } (before/after truncated to 200 chars) — use these index/path values to select a subset in apply_vibe_edit. 'short' returns just { status, progress, error }. 'full' returns the raw payload including the untruncated editedData. error is populated when status is 'failed' and carries the failure reason — surface it to the user instead of just reporting 'failed'. When status is 'completed', call apply_vibe_edit next (this tool never applies anything).

Retrieve the current weekly content schedule for the active brand. Returns enabled status, lead time, timezone, and per-day platform configs. If no schedule is configured yet, returns suggested defaults. Includes a viewInBrowser link to open the calendar page in the app.

Check PostKing API health and local auth state. No authentication required — safe to call first thing in a session to see whether you're logged in and what to do next.

Apply LLM rewrite and BERT replacements to reduce AI detection signals in text.

Import an asset into the brand library from a public URL. The server fetches and stores the file. Set assetType (e.g. 'google-image') when importing a result surfaced by search_web_images — it is recorded as a tag on the asset to preserve provenance.

Batch-import up to 50 assets by providing an array of public URLs. All are added to the brand library. Supports detail param for the returned asset list.

Import articles from an external blog, RSS feed, or Blogger URL into a PostKing publication as drafts. Returns id+title+slug by default (short); use detail='medium' for wordCount. Inspect individual articles with get_blog_article.

Bring-your-own-HTML: import an existing landing page from pasted HTML or a live URL. Synchronous — no polling needed. Pass exactly one of html (paste the full page source) or url (fetch and import from a live page). By default creates a brand-new landing page (optionally with name; the slug is always auto-generated). Pass convertExistingSlug instead to overwrite an existing landing page's content with the imported HTML. Set createMissingSidePages to true to auto-create stub side pages for internal links discovered in the HTML that don't already exist. Returns { landingPage: {id, slug}, report } where report audits the import: externalHosts (third-party domains referenced), relativeAssetPaths (local asset paths that may need re-hosting), placeholders (unresolved template tokens found), internalLinks (each { href, slug, existingSidePage }), themeExtracted (whether a theme was inferred from the HTML), truncated (whether the source HTML was cut down to fit limits), and extractability ({ verdict: 'ok'|'warn', reasons } — 'warn' means framework hydration scripts won't load post-import but static content still renders). If the source is a client-rendered app shell whose content depends entirely on framework scripts that can't be hosted here (e.g. a bare Next.js/React app shell), the import is refused before anything is persisted — this tool returns a non-throwing result { error: 'not_extractable', message, reasons } instead. Relay the reasons to the user and suggest pasting a static/exported HTML instead, or publishing directly from their site builder. Example: import_landing_page_html({ url: 'https://example.com/pricing', name: 'Pricing' }).

Async. Create a new knowledge-base item for the brand. Returns { operationId, status } — poll get_job until state=completed. If description or tags are omitted, PostKing auto-generates them from the content. For contentType='json', content must be valid JSON — this tool validates client-side before calling the API. Typically takes ~15–30 s.

Soft-delete a knowledge-base item. The item is deactivated (isActive=false) and no longer appears in knowledge_list. This action is not reversible via the API.

Fetch a single knowledge-base item by ID. short {id,name,contentType}; medium adds tags+summary+timestamps; full = raw (includes full content). Use detail='full' to retrieve the complete content body.

List the brand's knowledge-base items. short {id,name,contentType}; medium adds tags+summary+timestamps; full = raw. Filter by tag, active status, or global scope.

Update a knowledge-base item. Minor edits (name, tags, description) return the updated item synchronously. When content changes significantly, PostKing queues an AI description regeneration and returns { operationId, status } — poll get_job until state=completed. For contentType='json', content must be valid JSON — this tool validates client-side before calling the API. Typically takes ~15–30 s.

List all API keys on the account. Shows prefix, scope, and revocation status. Does NOT show raw tokens. Lists default short; pass detail=medium/full for more fields.

List assets in the brand's visual library. Filter by type (IMAGE|DOCUMENT|VIDEO|LINK|LOTTIE), tags, or search text. Supports detail param: short=id+type+name, medium=key fields, full=raw.

List the asset slots (image/video placeholders) for a landing page or side page, with each slot's current asset assignment. Use this to discover valid slotKeys before calling assign_asset_to_slot. Pass sidePageSlug to inspect a side page's slots.

List all unique tags used across the brand's asset library.

List all blog authors for the active brand. Returns id+name by default (short); use detail='medium' for email/social links. Author IDs can be passed to generate_blog_post or update_blog_article.

List all categories for a blog publication. Returns id+name+slug by default (short); use detail='medium' for description+articleCount.

LIST tool. Even detail='full' OMITS article bodies (kept bounded) — to read an article's content, call get_blog_article. The number of rows is controlled by limit (default 50, max 200), NOT by detail; for a 'full list' of titles, raise limit and keep detail='short'.

List all brands on your PostKing account. Returns id+name+website by default (short). Use detail='medium' for description, 'full' for all raw fields. To zoom into one brand call get_brand_info with detail='full'.

List all custom domains for the active brand. Lists default short; pass detail=medium/full for more fields including SSL status, verification, and connected blogs or landing pages.

To check a SPECIFIC operation's status, call get_job with its operationId — this list only returns the most recent ops and may omit a just-started one. List background jobs for the active brand. Use status='pending' to see in-flight ops, 'completed' to see finished ones. Use get_job with an operationId to poll a specific job — most async tools return an operationId. Supports detail param: short=id+kind+state, medium=6 key fields, full=raw.

Lists landing pages. Default detail='short' (id/slug/name/status). Use view_landing_page for full content.

List all saved versions of a landing page. Default detail='short'. Each version includes previewUrl (public GUI preview link — the published version's form when that version is the live one, otherwise the ?version= form); the top-level previewUrl is for the current draft. Use view_lp_version to see section content.

To check a SPECIFIC operation's status, call get_job with its operationId — this list only returns the most recent ops and may omit a just-started one. List recent Operations (the newer async-op system) for the active brand. Each operation has: id, kind, state (pending|running|completed|partially_failed|failed|cancelled), progress, result, errors. Use get_job with an operationId to poll a specific one. Filters: kind (e.g. seo_keyword_generate, seo_cluster_generate, lp_generate), state. Supports detail param: short=id+kind+state, medium=adds scopeId+progress+timestamps (no result/errors), full=raw including result.

List the carousel cards attached to a post. Cards are used for LinkedIn carousel / PDF generation. Returns {index,title} by default; use detail='medium' for truncated body, 'full' for all fields.

List recent posts and drafts. Filter by status or platform. Use status='created' to find unscheduled drafts. Returns id+status+scheduledAt by default; use detail='medium' or 'full' for more fields. For a single post use get_post.

List all blog publications (the containers that blog articles live under). detail='short' returns id+name; detail='full' returns raw rows. Distinct from list_publishing_connections which lists external platforms like WordPress.

List external publishing connections for a blog publication (WordPress, Medium, Substack, etc.).

List side pages attached to a landing page. Default detail='short'. Heavy JSONB (overrides/config) only at full via view_side_page. medium/full include currentVersionId (the draft) and publishedVersionId (the live version) per row — compare them to spot pages with unpublished draft edits without a second call.

List all saved versions of a side page. Default detail='short'. Always includes top-level currentVersionId (the draft) and publishedVersionId (the live version) so an agent can tell draft vs. live without a second call. Use view_side_page_version to see section content.

List all content themes for the active brand with their IDs. detail='short' (default) returns id+title; detail='medium' adds content preview; detail='full' returns raw content.

List all available voice profiles with their IDs. Lists default short; pass detail=medium/full for more fields.

Wait for the user to approve the PostKing login code in their browser and then save the token. Polls automatically; call this immediately after login_start.

Start the PostKing login flow. Returns a URL and short code for the user to visit in their browser. IMPORTANT: Immediately after this tool returns, show the URL + code to the user and then call login_complete — it will wait (polling in the background) until the user approves the request in their browser, so there is no need to ask the user to tell you when they are done.

Clear locally stored PostKing credentials.

STEP 1 of brand onboarding (website path). Crawls the site in the background and kicks off audience analysis + 10 themes. Sets the new brand as active and RETURNS a nextStep payload. IMMEDIATELY after this returns, ask the user which social platforms they publish on, then call set_brand_mediums. Do not call get_onboarding_status until mediums are set.

Select a visual for a post on a given platform. Use the chosen option's pickArgs from generate_post_visual_options VERBATIM — for card/quote templates that means passing kind + style + variant together; for a library/smart asset or a stock photo, pass the assetId or slot from its pickArgs. Do not invent style names. variant is a 1-based template variant index. Includes editInVisualEditor: a direct URL to edit the post in the visual editor (when active brand is set).

Read-only helper. Call this BEFORE edit_audience to discover which sections/subsections values are valid for this brand. Pass the natural-language change you intend to make; returns the available sections/subsections (computed from the brand's current audience data) plus a preview. Use the returned section keys (e.g. 'demographics', 'painPoints', 'positioning') as the required sections array for edit_audience.

Push a blog article to connected external platforms (WordPress, Medium, Substack, etc.). Get connection IDs from list_publishing_connections.

Publish a landing page, making it publicly accessible at its URL.

Kick off async generation of a subreddit pool for the brand — finds relevant subreddits by crawling Reddit. Typically takes ~1–3 min. Returns { operationId, status }. Poll get_job with the operationId until state=completed, then call reddit_get_pool to see results. Reddit is a repurpose-to-Reddit workflow, NOT a scheduled publishing medium.

Returns the brand's pool of relevant subreddits — THIS IS the brand-level subreddit match (each scored). Use it to answer 'which/what/top N subreddits should my brand post in?' — NO content needed; results are sorted most-relevant first; pass top for a top-N list. (reddit_suggest is a different, content-specific step.) Reddit is a repurpose-to-Reddit workflow, NOT a scheduled publishing medium.

Return stats on the global subreddit dataset (count of known subreddits available for matching). Informational only — no DB writes.

List saved Reddit posts (outputs of reddit_rewrite). Cursor-paginated. Returns { posts: [{ id, platform, content, outputData, sessionId, voiceId, createdAt }], nextCursor }. outputData contains: redditTitle, body, notes, wordCount, angle, length, subreddit, variationIndex. Flow step 4 of 4: pool → suggest → rewrite → LIST_POSTS.

Async. Rewrite a blog article (or raw content) into a Reddit-native post for a specific subreddit. Typically takes ~30–90 sec per variation. Returns quickly — if generation finishes within a short grace window, the finished Reddit post is returned inline; otherwise it returns a postId and a 'still in progress' status. Poll get_post with that postId until operationStatus is COMPLETED. Do NOT call reddit_rewrite again for the same request while it's pending. The subreddit does NOT need to be in the brand's pool — if it isn't, the rewrite still proceeds using general Reddit best-practices, and the result includes a subredditNotice string flagging that this subreddit hasn't been onboarded yet. Flow step 3 of 4: pool → suggest → REWRITE → list_posts.

Given a brand's content (a blog post by id, or pasted title+text), return up to 8 best-fit subreddits from the brand's pool, each with 2-3 distinct posting angles (angle type + tailored title + framing hook), plus promotion mode, buyer intent, match score, and the key rule to watch. Use an angle's title/hook to then draft a native post via reddit_rewrite. short {subreddit,match_score,promotion_mode,buyer_intent,angle} (angle = first angle only); medium adds reason,rule_to_watch,angles (all angles); full = raw. Synchronous, 0 credits. Requires the brand pool to exist — call reddit_generate_pool first if it doesn't. Flow step 2 of 4: pool → SUGGEST → rewrite → list_posts.

Re-generate a landing page's content using AI. Optionally restrict to specific sections. Returns an operationId — poll with get_job to track progress. For targeted edits to an existing page, prefer vibe_edit_landing_page.

Regenerate the visual option set for a post — refreshes stock photo results and re-scores library assets. Returns slim option list with pickArgs by default (medium). Use detail='short' for counts only, 'full' for raw catalog. Includes editInVisualEditor: a direct URL to edit the post in the visual editor (when active brand is set).

Turn a URL, text, blog post, or existing PostKing post into new content for social media or blogs. IMPORTANT: When the source is a URL, pass it directly to this tool via sourceUrl — do NOT fetch or crawl the URL yourself first. PostKing handles all crawling internally. Source types: url | text | blog | social_post. Target types: social (LinkedIn, X, etc.) | blog | text. Supports detail param: short=ids only, medium=key fields (default), full=raw response.

Move a scheduled post to a new time. Pass a future ISO 8601 UTC datetime.

Undo/rollback the draft to a prior version. Find valid version IDs via list_lp_versions. This does not touch the published version.

Restore a side page's draft to a prior version. Find valid version IDs via list_side_page_versions. This only changes the DRAFT — it moves currentVersionId forward to a new version copied from the target (forward history is never deleted). The live/public page is unaffected until you publish again via set_side_page_state({ published: true }).

Permanently revoke an API key. Pass confirm: true to proceed — this is irreversible and any clients using this key will stop working immediately.

Rewrite text using a voice profile or general writing rules.

Rewrite text using a specific voice profile.

Trigger the smart-week content generation engine for a specific date. This immediately queues posts for that day's schedule configuration. Use YYYY-MM-DD format for the date. Returns postsCreated count.

Schedule an existing blog article to auto-publish at a future date/time. scheduledAt must be a future ISO 8601 datetime. When the time arrives, the article publishes to the PostKing blog and auto-pushes to any connected external platforms flagged autoPublish. To publish immediately instead, use update_blog_article with status='published'.

Schedule a draft or approved post for a specific time. Equivalent to approve_post but named to match 'pking posts schedule'. Pass a future ISO 8601 UTC datetime. After scheduling the post status becomes 'scheduled'.

Search stock photo/video libraries for images matching a query. Returns URLs and descriptions. Use import_asset_from_url to add a result to the library. Supports detail param: short=url+thumbnail, medium=adds description+credit, full=raw.

Search Google Images across the whole web for a query — broader than search_stock_images, which only searches licensed stock photo/video libraries. Returns image URLs, the source site, and a link back to the source page. openLicensedOnly is a best-effort source filter, not a legal license guarantee — agents and users should still verify usage rights before publishing any result. Use import_asset_from_url to add a chosen result to the library. Supports detail param: short=url+source, medium=adds sourceUrl+alt+dimensions, full=raw.

Step 1 of the SEO / GEO flow. Add 3–10 seed keywords that describe what the brand wants to rank for. After this, call seo_generate_keywords to expand them into the full keyword universe.

Approves one or more SeoBriefs and AUTO-fires L4 article/comparison generation immediately — do NOT call seo_write_article after this. Typically takes ~3–8 min per article. After approval, poll each returned operationId with get_job until state is completed (or failed/partially_failed/cancelled on error). A brief in status writing means generation is already in progress — poll the existing operation, do not re-submit. Body: briefIds (array, max 200). Response: { approved, failed: [{briefId, reason}], operationIds, operations: [{briefId, operationId, type}] }.

Approve a single cluster. Gates brief generation — only approved clusters get briefs drafted. Position in flow: after seo_generate_clusters + seo_list_clusters, before seo_generate_roadmap / brief review. Typically takes ~2–5 min per cluster. Returns { cluster, operationId } — the operationId is for the async brief-generation job kicked off by approval. Poll get_job with the operationId until state is completed (or failed/partially_failed/cancelled on error).

Optional capstone step — runs AFTER blog articles are published. Auto-suggests a published side-page CTA for each blog article in the batch by matching the article's keywords (cluster + tags + title) against the brand's published side pages, then writes the result to BlogArticle.sidePageInfo (header + ctaText + ctaButtonText + ctaHref). Defaults are safe to re-run: skips blogs that already have a CTA (overwriteExisting=false) and skips Webflow-synced blogs (skipWebflowSynced=true) since CTA edits don't push back to Webflow. Synchronous — returns { updated, skipped, errors, total, results: [{blogId, status, sidePageId?, sidePageSlug?}] } directly; no polling needed. Pass blogIds: "all" to process every blog for the brand, or a list of up to 50 blog IDs. Hard cap of 50 blogs per call. For brands with more uncovered blogs, batch your blogIds arrays in groups of 50. The matcher uses keywords today; reusing an existing CTA header/ctaText body as a matching signal is a planned enhancement.

Step 5b — bulk-approve N clusters in one call. Recommended path when an agent wants to move multiple clusters forward. Approving a cluster fires an async seo_brief_generate Operation per cluster; brief generation only runs on approved clusters. Typically takes ~2–5 min per cluster. Response includes operations: [{ clusterId, operationId }] and operationIds: string[] — Poll get_job with the operationId until state is completed (or failed/partially_failed/cancelled on error).

Soft-delete N SeoScoredKeyword rows in one call (sets deletedAt; rows stay in the DB but are filtered out of all queries). Housekeeping op — not part of the main flow. Pass confirm: true to proceed. Use to clear out a batch of junk/irrelevant keywords the auto-pipeline missed, e.g. after filtering seo_list_keywords by relevanceMax.

Edit userTags, intent, priority, and/or excludedFromClustering across N SeoScoredKeyword rows in one call — the same values are applied to every id in keywordIds. Housekeeping op — not part of the main flow. Pass confirm: true to proceed (this can silently overwrite tags/intent/priority for many keywords at once). At least one of intent, userTags, priority, or excludedFromClustering must be supplied. Typical flow: call seo_list_keyword_ids with a filter to get the target ids, then pass them here. Example: {"keywordIds":["kw_1","kw_2"],"excludedFromClustering":true,"confirm":true}.

Bulk-reject N clusters in one call. Symmetric to seo_bulk_approve_clusters.

Step 3 of the SEO / GEO flow. Tag keywords by search intent and/or user tags. Pass updates: an array of {keywordId, intent?, userTags?} (intent ∈ informational | commercial | navigational | transactional). Example: {"updates":[{"keywordId":"kw_123","intent":"commercial"}]}. After this, call seo_generate_clusters.

Compare the brand's keyword coverage against a competitor domain. Returns short detail by default: bucket totals only {overlapping: {total}, brandUnique: {total}, competitorOnly: {total}}. Use detail="medium" for capped keyword lists (up to 50 per bucket) or detail="full" for the raw API response.

Create a real, named SEO cluster by hand — bypasses the auto-clustering pipeline entirely (no LLM call). The cluster starts empty; use seo_create_custom_brief with the returned id as clusterId to add its first brief. Manual clusters are tagged origin: "manual" so the dashboard can distinguish them from pipeline-generated clusters, and are created already approved (no separate approval step needed). Cluster names must be unique per brand — if the name is already taken, this returns a clear cluster_name_taken error instead of creating a duplicate; pick a different name or reuse the existing cluster via seo_list_clusters.

Create a single custom SEO brief on demand — the MCP entry point for the 'generate-one' custom-brief flow (previously only reachable via raw agent-v1 REST). Pass clusterId (from seo_create_cluster or seo_list_clusters) to add this brief into an EXISTING named cluster. Omit clusterId to fall back to the legacy behavior: a throwaway single-brief cluster is minted automatically (tagged origin="manual"). Async — returns { operationId, status }. Poll get_job with the operationId until state is 'completed' (or 'failed'/'partially_failed'/'cancelled' on error), then call seo_get_brief with the briefId from the completed operation's result to read the generated outline. Typically takes ~2–5 min per cluster.

Hard-delete a cluster. This CASCADES: every SeoRoadmap item under this cluster is deleted, along with its brief. Blog articles and keywords that pointed at this cluster are NOT deleted but have their cluster link cleared. This is NOT UNDOABLE — there is no soft-delete for clusters (unlike keywords). Housekeeping op — not part of the main flow. Pass confirm: true to proceed. Prefer seo_reject_cluster if you just want to remove a cluster from the active pipeline without destroying its roadmap items and briefs — reject is reversible via seo_restore_cluster, delete is not.

Soft-delete a single SeoScoredKeyword (sets deletedAt; the row stays in the DB but is filtered out of all queries). Housekeeping op — not part of the main flow. Pass confirm: true to proceed. Use for obvious junk keywords the auto-pipeline missed. Prefer seo_edit_keyword with excludedFromClustering=true when you only want to hold a keyword out of the next clustering pass.

Edit an SeoBrief before approval. The inner route does NOT accept free-text 'instructions' — refinement is structured. Pass briefData (the full replacement JSON for the brief outline — H2s, FAQs, keyword targets, etc.) and/or status ('approved' | 'rejected'). Approving via this tool fires L4 article/comparison generation immediately and returns { brief, operationId } — prefer seo_approve_briefs for the canonical approval step. Typical refinement loop: seo_get_brief → mutate briefData locally → seo_edit_brief with the new briefData (status omitted) → seo_approve_briefs.

Edit a cluster's name, pillarKeyword, description, keywordsMeta, contentMix, and/or briefAssignments. Housekeeping op — not part of the main flow. At least one field must be supplied. MEMBERSHIP: there is no separate add/remove-member endpoint. Cluster membership is entirely controlled by keywordsMeta — it is a REPLACEMENT array, not a delta/patch. To add a keyword to the cluster, fetch the cluster's current keywordsMeta (seo_list_clusters with detail="full"), append a new entry {keyword, id, volume, kd, intent, relevance, priority, excluded?} (use the SeoScoredKeyword id from seo_list_keywords / seo_list_keyword_ids), and send the WHOLE array back. To remove a keyword, send the array with that entry omitted. Sending a partial array will drop the missing members from the cluster. contentMix must be an object with blog/tool/comparison/landing fractions summing to 1.0 (the server normalizes small rounding drift). briefAssignments is an array of {keyword, type, ...} entries (type ∈ hub|blog|comparison|tool|landing|skip); duplicate keywords are rejected. Example (rename): {"clusterId":"kwc_123","name":"Better cluster name"}. Example (remove a member): fetch full keywordsMeta, filter out the unwanted keyword, then {"clusterId":"kwc_123","keywordsMeta":[...remaining members]}.

Edit a single SeoScoredKeyword. Housekeeping op — not part of the main flow. At least one of intent, userTags, priority, or excludedFromClustering must be supplied. Use to override the auto-detected intent label, attach user tags, manually nudge priority (0..1), or exclude a noisy keyword from clustering. Example: {"keywordId":"kw_123","intent":"commercial","userTags":["enterprise"]}.

Identify content gaps — topics the brand's competitors cover but the brand doesn't. Returns short detail by default: {id?, topic?, keyword?} labels only per gap. Use detail="medium" for compact gaps (+ searchVolume, difficulty, competitorDomains) or detail="full" for the raw API response.

Step 4 of the SEO / GEO flow — async cluster-generation step. Groups related keywords into topic clusters that become candidate pillar topics. Typically takes ~1–2 min. Returns {operationId, status} — Poll get_job with the operationId until state is completed (or failed/partially_failed/cancelled on error). After completion, call seo_list_clusters to pick a target, then seo_generate_roadmap.

Step 2 of the SEO / GEO flow. Async — expands seed keywords into the full keyword universe. Typically takes ~1–3 min. Uses credits. Returns {operationId, status} — Poll get_job with the operationId until state is completed (or failed/partially_failed/cancelled on error). By default the server auto-derives 30-40 seed concepts from the brand's own context (products, ICP, positioning) and expands those. Pass seeds to steer expansion yourself instead — e.g. to target specific topics or geographies the brand context wouldn't surface on its own ("California", "Texas", "Nashville plumbers"). Supplying seeds REPLACES the automatic brand-derived seed generation for this call — it does not add to it. 3-20 short phrases, the kind of thing someone would actually type into Google (2-4 words, no jargon). The only other thing the agent can tweak is autoScore (defaults to true server-side — set false to skip volume/difficulty scoring). After completion, call seo_categorize.

Step 6. Turn one or more clusters into a prioritized content roadmap of blog articles to write. Pass clusterId (single) or clusterIds (array of cluster IDs from seo_list_clusters) — omit both to roadmap all clusters. After this, call seo_write_article.

Generates a side page for a brand's landing page, optionally linked to an SEO cluster (clusterId). When linked, the side page surfaces in cluster-context queries and inherits the cluster's keyword targeting — strengthening topical authority that feeds GEO citation patterns. Two body modes: • freeform: pass key + prompt (+ optional keywords, selectedSections, voiceProfileId, sidePageType). Freeform now writes real section-level content (hero/features/showcase/faq/cta), not just metadata. • brief: pass key + brief (structured outline) + optional briefId and roadmapItemId. Typically takes ~2–5 min. Async — returns { success, operationId, operationRowId, pollUrl, sidePageId }. Poll get_job with the returned operationId until state is completed (or failed/partially_failed/cancelled on error); the generated page's sections will be populated once complete. Comparison-type briefs run synchronously and return sidePageId directly. slug is the PARENT landing page slug under which the side page is created.

Fetch a single SeoBrief by id, including its briefData outline, status, roadmap item, and cluster. Returns full detail by default (complete brief incl briefData). Use detail="medium" for {id, type, status, title, clusterName, briefSummary, sidePageUrl} or detail="short" for {id, type, status}. Use to inspect a brief before refining it with seo_edit_brief or approving it with seo_approve_briefs.

Returns ALL briefs across EVERY status by default — do NOT add a status filter unless the user explicitly asks. statusBreakdown gives the per-status counts (match these to the dashboard's brief count). NOTE: briefs whose generation is still in-flight may not appear here yet — check list_operations / get_job for in-progress generation. Returns short detail by default: {id, type, status, title} per brief. Use detail="medium" for compact summary (clusterId, clusterName, briefSummary, sidePageUrl, generationError, blogArticleId, generatedAt, approvedAt) or detail="full" for raw briefs including briefData outline. To inspect a single brief's full outline, call seo_get_brief with detail="full". Filters: status (CSV — e.g. 'pending_review,approved'), type (CSV — e.g. 'blog,comparison,landing'), clusterId, roadmapItemId, q (cluster-name fuzzy match), limit (default 50, max 200), cursor. Response shape: { count, total, nextCursor, statusBreakdown, detail, briefs: [...] }.

Step 5. List clusters so the agent can pick one (or several) to approve before brief and roadmap generation. Returns short detail by default: {id, name, status} per cluster. Use detail="medium" for the full compact summary (pillarKeyword, briefGenerationStatus, briefCount, keywordCount, topKeywords, firstBriefId, description, productFit, relevanceScore) or detail="full" for raw cluster objects. Full keyword detail (keywordsMeta, contentMix, briefAssignments) is intentionally omitted at short/medium to keep context small — use cluster IDs with approve/reject tools directly. Supports server-side filtering: status (CSV of pending_review/approved/rejected), productFit (core/adjacent/out_of_scope), archetype (competitor), origin (CSV of pipeline/manual), q (text search over name/description/pillarKeyword).

Return just the ids of every SeoScoredKeyword matching a filter — unpaginated, no keyword data attached. Housekeeping op — not part of the main flow. Accepts the same filter set as seo_list_keywords: source, intent, clusterId, q, hasTag, volumeMin/volumeMax, kdMin/kdMax, relevanceMin/relevanceMax, priorityMin/priorityMax, includeDeleted, excludedFromClustering. Use to select "all keywords matching filter X" in one call, then feed the returned ids into seo_bulk_delete_keywords or seo_bulk_edit_keywords. Example: filter relevanceMax=0.2 to find low-relevance keywords, then bulk-delete or bulk-edit them. Or hasTag="geo:us-mn" to select every Minnesota-tagged keyword after seo_tag_geography.

List generated keywords for the brand. Useful for auditing between steps. Returns short detail by default: {id, keyword, intent} per keyword. Use detail="medium" for the full compact summary (priority, searchVolume, difficulty, relevance, clusterId, excludedFromClustering, userTags) or detail="full" for raw keyword objects. Supports server-side filtering: source, intent, clusterId, q (substring search), hasTag, volumeMin/volumeMax, kdMin/kdMax, relevanceMin/relevanceMax, priorityMin/priorityMax, includeDeleted, excludedFromClustering. hasTag filters on userTags (OR match) — use it to find geo-tagged keywords after seo_tag_geography, e.g. hasTag="geo:us-mn" or hasTag="geo:us-mn,geo:us-tx" for multiple regions. Use cursor (from a previous call's response) to page through results beyond limit.

List the 'Generated Results' (blog articles + side pages + comparisons) the SEO/GEO pipeline has produced — mirrors the dashboard Results tab. Includes BOTH draft and published items. Use kind to filter. This is the canonical 'what content has been generated' list — prefer it over reconstructing results from briefs.

List roadmap items (blog topics queued for writing). Returns short detail by default: {id, title, status} per item. Use detail="medium" for the compact summary (priority, primaryKeywords, clusterId) or detail="full" for raw objects. Call seo_roadmap_get with detail="full" for a single item's complete detail.

Merge one cluster into another: reassigns the source cluster's keywords, roadmap items (and their briefs, which follow transitively), and any linked blog articles to the target cluster, then deletes the source cluster. Not undoable. Housekeeping op — not part of the main flow. Use when seo_list_clusters or a rescan report shows near-duplicate clusters that should be consolidated. The target cluster's own name/description/keywordsMeta/contentMix are NOT changed by the merge — only the FK relations (keyword.clusterId, roadmap.clusterId, blogArticle.clusterId) move over. Use seo_edit_cluster afterward if the target's keywordsMeta needs updating to include the newly reassigned keywords.

Step 10. Publish or schedule a roadmap-generated article to a publication. Free-tier choke point — may return FREE_CAP_REACHED with a checkoutUrl.

Re-runs L3 brief generation for a single brief (scoped to its cluster). Typically takes ~2–5 min. Async — returns {operationId, status}. Poll get_job with the operationId until state is completed (or failed/partially_failed/cancelled on error), then re-fetch with seo_get_brief to see the refreshed briefData. Use when the existing brief's outline is unusable and a structured seo_edit_brief won't recover it.

Reject a single cluster — marks it rejected and detaches its scored keywords. Use when a generated cluster isn't relevant.

Restore a rejected cluster back to pending_review so it can be approved again.

Undo a soft-delete: clears deletedAt on the given SeoScoredKeyword ids so they reappear in seo_list_keywords / seo_list_keyword_ids. Housekeeping op — not part of the main flow. Use after seo_delete_keyword or seo_bulk_delete_keywords removed something that shouldn't have been removed. IDs that are not currently soft-deleted are silently no-ops (the response's restored count only reflects rows that actually changed). Find deleted ids with seo_list_keyword_ids using includeDeleted=true.

Permanently delete a roadmap item. Pass confirm: true to proceed — this is irreversible.

Edit a roadmap item — update its title, status (suggested|in_progress|completed|ignored), or priority.

View a single roadmap item by ID. Returns full detail by default (raw object). Use detail="medium" for {id, title, status, primaryKeywords, clusterId} or detail="short" for {id, title, status}.

Progress stats for the content roadmap (completed, in-progress, suggested counts).

Geo pivot Stage 1. Async — classifies every keyword's geographic intent and writes a geo:* tag into userTags. Tags: geo:<country>-<subdivision> (e.g. "geo:us-mn") for a place that resolves to one region, geo:<country> (e.g. "geo:us") for country-only intent, geo:none for no geographic intent, geo:ambiguous for a place name that maps to multiple regions with no way to resolve it. Typically takes ~1–2 min. Uses credits (unless dryRun is true). Returns {operationId, status} — poll get_job with the operationId until state is completed (or failed/partially_failed/cancelled on error). The job result includes tagCounts (tag -> count), ambiguousKeywords (needs human review), and costUsd. Idempotent by default: keywords that already carry any geo:* tag are skipped on a re-run — pass retag:true to force re-classification of everything. Pass dryRun:true to get the full classification breakdown WITHOUT writing any tags — use this first to review tagCounts and ambiguousKeywords before committing. After completion, use seo_list_keywords or seo_list_keyword_ids with hasTag="geo:us-mn" (etc.) to select the tagged keywords for further action.

Revert an approved cluster back to pending_review. Fails if briefs have already been generated for this cluster (cannot be reverted once briefs exist).

ALTERNATIVE write path — only call this when a brief was NOT approved via seo_approve_briefs (which already auto-generates). If the brief status is writing, generation is already in progress — poll the existing operationId with get_job until state is completed rather than calling this again. Step 7 (manual path). Draft a full blog article for a roadmap item. Uses credits. Typically takes ~3–8 min per article. Precondition: the brief for this roadmap item must be in status approved. If the brief is still drafted or pending_review, review with seo_list_briefs / seo_get_brief, refine with seo_edit_brief, then approve with seo_approve_briefs (which will auto-generate). Returns an articleId that can be reviewed, edited, or published.

Set the active brand for this session. All subsequent tools will use this brand by default.

STEP 2 of brand onboarding. Saves the list of platforms the brand publishes on. Call this immediately after create_brand or onboard_brand and the user has picked platforms. After this, call get_onboarding_status every ~15 seconds until it reports done.

Set one field on a landing page section (dot-paths in field supported, e.g. 'plans.0.ctaUrl'), or replace a whole section with replaceSection=true. Pass the bare content-section key (e.g. 'hero', 'features', 'pricing') — the server maps it into the page's content tree. Top-level roots like slotMap, config, navigation, siteMetadata are also accepted as-is. Each call creates a new draft version — for many related changes across a page, prefer vibe_edit_landing_page instead. Example: section='hero', field='title', value='New headline'.

Reorder and/or toggle visibility of a landing page's sections. Pass at least one of sectionOrder/sectionVisibility. Valid section-order keys (all 11): hero, features, pricing, cta, faq, howItWorks, showcase, categoryExplorer, replacesStack, comparisonMatrix, roiCalculator. sectionVisibility keys are the toggleable subset of the above. When both are given, order is attempted first, then visibility — each is applied independently, so one can succeed while the other fails. The result always reports both outcomes: { order: |{error}, visibility: |{error}, partialFailure: true } if only one part failed. This tool only throws if every requested part fails (or if a single requested part fails).

Bulk-replace all carousel cards for a post. Provide a full array of card objects with title, body, and optional number.

Update one section of a side page with STRUCTURED, typed fields (not a content string). The write must match the section's real shape or it is rejected with a 400 validation error. Landing sections use typed objects, e.g. hero → { title: { prefix, suffix }, description, testimonials: [...] }; comparison sections (matrix, verdict, scorecard, decisionTree, priceCalculator, competitorClaims, ...) use their comparison-schema shape. Use view_side_page(detail:'full') first to see the current section shape, then send the same shape back with your edits. Pass EITHER fields (a partial section object merged onto the current section) OR field (a dot-path) + value for a single nested change, OR instructions alone for a natural-language edit (the server runs an AI pass scoped to this section). type:"text" pages: there is no per-section nesting — the whole page is one flat {title, htmlContent} document. sectionId is accepted for symmetry (e.g. "content"/"htmlContent"/"title") but every edit applies to the whole document: pass fields:{title,htmlContent}, field:"title"|"htmlContent"+value, or instructions alone for an AI rewrite of the whole page. edit_side_page's title/htmlContent params are a simpler direct-write shortcut for the same document. Every edit creates a new draft version (like landing-page section edits) — see list_side_page_versions / restore_side_page_version; on a published page, edits stay draft-only until set_side_page_state({published:true}) publishes them.

Publish or unpublish a side page. published:true publishes the CURRENT DRAFT — it sets the published pointer to the latest draft version, which is how you make draft edits (from edit_side_page / set_side_page_section) live. published:false hides the page publicly but keeps the last-published version marker, so re-publishing with no further edits restores it instantly. The response includes publishedVersionId — the version now live (unchanged from before on unpublish) — so you know exactly which version is public without a follow-up view_side_page call.

Update a brand's social media content rules for ONE platform. By default this MERGES your provided fields into the existing rules (send only what you want to change — other fields are preserved; arrays you provide replace the old array). Set replace=true to overwrite the entire platform ruleset. Valid platforms: linkedin, x/twitter, facebook, instagram, threads, general. Tip: call get_social_media_rules first to see current values.

Create or replace the weekly content schedule for the active brand. dayConfigs: array of { dayOfWeek (0=Sun…6=Sat), mediums: [{ medium, postsPerDay }] }. Mediums: x/twitter | linkedin | instagram | facebook | threads | blog. After setting, call enable_weekly_schedule to activate it.

Add a new line item (deliverable) to a storyline's strategy. Specify the channel, type, title, description, and a config map (pass {} if no extra config).

Run the intake/clarification step for a storyline. The API returns follow-up questions or a readiness signal; call iteratively until the system has enough context. After clarification is complete, call storyline_generate_brief.

Confirm (lock) the brief for a storyline, advancing it to the strategy phase. After confirmation, call storyline_generate_strategy.

Create a new storyline (marketing plan) for the brand. Pass a prompt describing the campaign goal; optionally provide a title. After creation, call storyline_clarify to gather context, then storyline_generate_brief.

Archive (soft-delete) a storyline. Pass confirm: true to proceed. Use storyline_restore to reverse this.

Permanently remove a line item from a storyline's strategy. Pass confirm: true to proceed.

Apply an AI-driven edit to the current brief using a natural-language instruction. Examples: 'Make the tone more casual', 'Add a proof point about our 99% uptime SLA'. Optionally pass expectedVersion for optimistic concurrency.

Apply an AI-driven edit to the current strategy using a natural-language instruction. Examples: 'Add a LinkedIn video post for launch week', 'Remove the influencer outreach line items'.

Read-only dry-run. Estimate the credits required to execute the storyline without actually running it. Use before storyline_execute to surface the cost to the user for approval. Returns { estimatedCredits, lineItemBreakdown } or similar.

Async. Execute a storyline — generates content drafts for all selected line items. Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~3–8 min. Call storyline_estimate first to surface the credit cost before execution.

Async. Generate the marketing brief for a storyline (positioning, key messages, audience, timing, tone notes). Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~1–3 min. After completion, review the brief with storyline_get, then call storyline_confirm_brief to advance to strategy.

Async. Generate the strategy and line-items for a storyline based on its confirmed brief. Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~2–5 min. After completion, review with storyline_get_strategy, then optionally edit with storyline_edit_strategy or add/remove line items.

Fetch a single storyline by ID with its full state (brief, strategy, line items, status). Returns full detail by default. Use detail="medium" for a compact summary or detail="short" for {id,title,status}.

Fetch the strategy and line items for a storyline. Returns full detail by default (raw strategy + all line items). Use detail="medium" for a compact summary or detail="short" for {id,status} + line-item count.

List the brand's storylines (marketing plans). short detail {id,title,status}; medium adds isLive, dates, promptSummary; full = raw.

Async. Re-generate a single line item's content draft. Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~1–3 min.

Restore an archived storyline back to active state.

Manually set (replace) the full brief for a storyline. Use to provide a human-authored brief or to push back an edited version retrieved via storyline_get. Pass the complete brief object and the current expectedVersion (use 0 when setting from scratch). After setting, call storyline_confirm_brief to advance to strategy generation.

Update metadata on a storyline: title, live status, or start/end/launch dates. Pass at least one field to change.

Update a line item on a storyline — select/deselect, retitle, change description, targetDate, or config. Pass only the fields to change.

Get AI-suggested assets from the brand library that match a given post context or topic.

Add or remove tags on an asset. Provide addTags and/or removeTags as arrays.

Create one or more content templates for the brand. Pass a single template object, or pass the 'templates' array param for bulk creation. If both are supplied, 'templates' (bulk) takes precedence. Returns the created template record(s).

Permanently delete a content template from the brand. This action is irreversible.

AI extracts a reusable content template from a pasted post text. Synchronous (seconds) — no polling needed. Pass save=true to also persist the template to the brand's library. Returns the extracted template object; if saved, includes the new template id.

List the brand's saved content templates. short {id,title,category}; medium adds platforms,isFavorite,bodyPreview (160 chars); full = raw. Pass category to filter (e.g. 'hook', 'cta', 'thread'). Results are ordered by isFavorite desc, then usageCount desc.

RE-RANKER: AI scores a caller-supplied list of candidate templates and picks the N best-fitting ones for a given theme or topic. This tool does NOT read stored templates server-side — the caller must supply the candidates explicitly (e.g. call template_list first, then pass the results here). Synchronous — no polling needed. Pass the templates array from template_list (full detail) as candidates. Returns { templateIds } — an ordered array of the winning template IDs.

Update an existing content template. All fields are optional — only supplied fields are changed. Use isFavorite=true/false to toggle favorite status.

Browse top-trending posts (with deconstructions) for a niche + platform. Account/niche-scoped — NOT tied to a specific brand. Each post includes hook, template, pattern, and virality reason from the deconstruction. The crawler runs every 3 days; use days=3 (default) for the freshest batch. Supported niches: ai-saas, marketing, web3. Supported platforms: x.

Edit a blog article — title, content, excerpt, SEO fields, status, author, category, featured/header image, or CTA. Set status='published' to make it live on your PostKing blog. CTA (call-to-action) is structured data, NOT part of the article body — never write CTA markup into content. Use cta: { url, label, headline, body } to set it (url is required when enabling), or cta: { enabled: false } to remove it. cta and sidePageInfo are mutually exclusive — pass sidePageInfo only if you need to link to an existing side page by id/slug (from list_side_pages) instead of a raw url; either way, malformed CTA shapes are now rejected by the server rather than silently persisted, so pass exactly the documented fields.

Update an existing blog publication's metadata — title, description, domain/routing config, or layout. Only the fields you pass are changed (partial update). Distinct from create_publication (which creates a new one). publicationId comes from list_publications or list_blogs.

Upload an asset to the brand library from a local file path or base64-encoded content. Prefer filePath for local files: the server reads and base64-encodes the file itself, avoiding truncation of large base64 strings over the tool_call boundary. fileBase64 is still supported for remote/inline use where no local path is available. For large files over the remote/HTTP transport, a single fileBase64 string can get truncated crossing the LLM→tool_call boundary — use the chunked flow instead: upload_asset_begin → upload_asset_chunk (× N) → upload_asset_finish. Provide exactly one of filePath or fileBase64. Returns the new asset ID and URL.

Cancel a chunked asset upload in progress and discard any buffered chunks.

Start a chunked asset upload. Use this instead of upload_asset's fileBase64 param for large files over the remote/HTTP transport, where a single large base64 string can get truncated crossing the LLM→tool_call boundary. Flow: upload_asset_begin (once) → upload_asset_chunk (once per chunk, in order) → upload_asset_finish (once). Returns an uploadId that expires after 10 minutes of inactivity.

Send one chunk of a base64-encoded file previously started with upload_asset_begin. Chunks must be sent in order, index starting at 0, with no gaps.

Finalize a chunked asset upload: reassembles the buffered chunks, verifies integrity, and uploads the asset to the brand library. Returns the new asset ID and URL.

Check DNS verification for a domain. Returns whether it's pointing to PostKing servers and what A record is needed if not.

Use AI to propose an edit to a landing page based on natural-language instructions. This is step 1 of a propose → review → apply flow — it does NOT change anything by itself: 1) Call this tool. Returns { operationId } — nothing is applied yet. 2) Poll get_vibe_edit_status(slug, operationId) — NOT get_job — until status is 'completed'. Vibe-edit sessions live in a separate store from the generic job/operation queue, so get_job will not find them. 3) Review the changes array returned by get_vibe_edit_status: field-level before/after entries, each with an index and a path. 4) Call apply_vibe_edit with all=true (accept everything) or a subset via indices/paths. 5) Call publish_landing_page to make the applied changes live. scope='full' edits the whole page; scope='section' restricts the edit to one section — sectionId is REQUIRED when scope='section'. Example section keys: hero, features, pricing, cta, faq, howItWorks, showcase, categoryExplorer, replacesStack, comparisonMatrix, roiCalculator.

View details of a single asset by ID. Supports detail param: short=id+type+name, medium=key fields, full=raw.

Fetch a landing page by slug. detail='full' (default) returns full data JSONB plus previewUrl (public GUI preview link) and webUrl (dashboard editor link); 'medium' returns summary + sectionKeys/sectionWordCounts + previewUrl + webUrl; 'short' returns id/slug/name/status. Section bodies and rendered HTML appear only at full.

View the unpublished draft of a landing page. detail='full' (default) includes full versionData plus previewUrl (public GUI preview link, ?version= form); 'medium' adds sectionKeys/sectionWordCounts + previewUrl; 'short' is id/slug/name/status only.

View a specific LP version. detail='full' (default) returns full data plus previewUrl (public GUI preview link — the published form if this is the live version, otherwise the ?version= form); 'medium' adds sectionKeys/sectionWordCounts + previewUrl.

View a side page including sections and rendered HTML. detail='full' (default) includes rendered HTML and full overrides (use this to read a section's typed shape before editing it with set_side_page_section); 'medium' gives summary + overrideSectionKeys (the section ids you can pass to set_side_page_section); 'short' gives id/slug/name/type/isPublished. Rendered HTML appears only at full. medium/full also include currentVersionId (the draft) and publishedVersionId (the live version) — a mismatch means there are unpublished draft edits.

View a specific side-page version snapshot. detail='full' (default) returns the complete snapshot { type, overrides, siteMetadata, slotMap, config } plus _meta { versionId, isCurrent, isPublished, createdAt }; 'medium' gives type + _meta + overrideSectionKeys (section ids only, no content); 'short' gives just _meta.

Perform a live, real-time web search and get back a raw answer with sources — for questions like 'find me the top 10 places to share/index my MCP', 'what's the latest on X', or 'where can I find Y'. Distinct from search_web_images, which only returns images — this tool returns a synthesized text answer plus the sources it drew from (each with title, url, and optional description), and optionally related follow-up prompts. Results are returned as-is (unsummarized) — pass the answer and sources straight through to the user.

Return the profile of the currently authenticated PostKing user (email, plan, credit balance, token source).