Funnels

These tools cover the full AI-powered funnel lifecycle: create a funnel from a natural-language brief, request content edits, rename or re-publish to a custom domain, and poll an async job until generation completes. A typical flow is create_funnel → get_funnel_job_status (loop until completed) → update_funnel_metadata to set the final URL, then update_funnel for any subsequent content revisions.

Before calling create_funnel you must pick (or create) a brand profile via list_brands and get_brand — the brand's colors, typography, and voice are woven into the generation brief automatically.

Tools

Tool	Purpose	Key inputs	Returns
create_funnel	Create a funnel and start async AI HTML generation	data.name, data.prompt, one of data.brandId / data.noBrand	jobId, funnelId, status: "pending"
update_funnel	Request an AI content edit on an existing funnel	funnelId, prompt	jobId, funnelId, editorUrl, status: "pending"
update_funnel_metadata	Rename a funnel or publish it to a custom domain/slug	funnelId, data (name, domainId, slug)	Updated funnel object
get_funnel_job_status	Poll a generation or edit job (long-poll, ~20 s per call)	jobId	Status + funnel URLs when completed

create_funnel

Starts AI generation of a brand-new funnel from a natural-language brief. The call is non-blocking: it creates an empty funnel shell, kicks off the AI generation job, and returns immediately with status: "pending". Poll get_funnel_job_status until status: "completed" to get the live URL.

The funnel is published automatically when generation completes. Pass domainId and/or slug to land on a custom URL; otherwise it publishes under the default Perspective domain.

Mandatory pre-call flow:

1. Call list_brands and present the user with a 4-option brand-pick choice.
2. Call get_brand (or use the create_brand response directly) to load brand identity.
3. Ask 3–5 brand-aware clarification questions (goal, audience temperature, length, primary objection).
4. Then call this tool with brandId set (or noBrand: true if the user declined a brand).

Inputs

Name	Type	Required	Description
data.name	string	Yes	Short human-readable funnel name
data.prompt	string	Yes	Natural-language brief built from brand-aware clarification answers; cover goal, audience temperature, length tolerance, primary objection
data.brandId	string	Exactly one of brandId / noBrand	ID of the brand profile to apply (from list_brands → get_brand)
data.noBrand	true	Exactly one of brandId / noBrand	Set only after the user actively chooses to create without a brand
data.workspaceId	string	No	Target workspace; defaults to account default
data.domainId	string	No	Domain to publish the funnel under once generation completes
data.slug	string	No	URL path segment; combined with domainId → {domainUrl}/{slug}. Letters, digits, and hyphens only

Returns { data: { jobId, funnelId, status: "pending" } }.

update_funnel

Appends a natural-language edit instruction to the funnel's existing AI conversation. Changes are published automatically to the funnel's current live URL when the edit job completes. Only one generation may run at a time per funnel — poll get_funnel_job_status until the current job is done before calling again.

Inputs

Name	Type	Required	Description
funnelId	string	Yes	ID of the funnel to edit (from create_funnel or list_workspaces)
prompt	string	Yes	Natural-language description of the change to make (e.g. "make the headline punchier and add a testimonials section")

Returns { data: { jobId, funnelId, editorUrl, status: "pending" } }.

update_funnel_metadata

Renames a funnel or changes its published domain/slug without touching the funnel content. At least one of name, domainId, or slug must be provided. Providing domainId or slug (or both) triggers a republish of the funnel to the new URL.

Inputs

Name	Type	Required	Description
funnelId	string	Yes	ID of the funnel to update (from create_funnel or list_workspaces)
data.name	string	No	New funnel name (minimum 1 character)
data.domainId	string	No	Domain to publish under; providing this republishes the funnel
data.slug	string	No	Publish slug in kebab-case (letters, digits, and hyphens only; no slashes, underscores, spaces, or dots). Empty string clears the current slug. Providing this republishes the funnel

At least one of data.name, data.domainId, or data.slug must be set; the call is rejected if all three are omitted.

Returns { data: { id, name, slug, domainId, ... } } — the updated funnel object (without previewUrl).

Related

• Guide: ../../guides/funnels