Skip to main content

Funnels

These tools cover the full AI-powered funnel lifecycle: find a funnel, create one from a natural-language brief or copy an existing one, request content edits, poll an async job until it finishes, and publish the result. A typical flow is create_funnel → get_funnel_job_status (loop until completed) → publish_funnel once the user agrees, then update_funnel → get_funnel_job_status → publish_funnel for each later revision.

Creating and editing only change the funnel's draft. Nothing reaches a visitor until publish_funnel is called, so confirm with the user before each publish.

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.

Funnels can also run A/B tests. When a funnel has one, update_funnel and publish_funnel behave a little differently; see Experiments (A/B Tests).

Tools​

ToolPurposeKey inputsReturns
list_funnelsList a workspace's funnels and their IDsworkspaceId, status?, includeArchived?Paginated funnel list
create_funnelCreate a funnel and start async AI HTML generationdata.name, data.prompt, one of data.brandId / data.noBrandjobId, funnelId, status: "pending"
duplicate_funnelCopy an AI/HTML funnel as a new draftfunnelId, data.name?New funnel id, name, editorUrl
update_funnelRequest an AI content edit on an existing funnelfunnelId, prompt, version?jobId, funnelId, editorUrl, status: "pending"
get_funnel_statusOne funnel: its status, URLs and sharing previewfunnelId, includeRevisions?The list_funnels item; revisions with includeRevisions
get_funnel_htmlRead an existing funnel's HTML, in numbered windows of up to 32 KBfunnelId, optional offset / column / limit / version / revision / downloadcontent, line window, totals, nextOffset / nextColumn; a downloadUrl with download
update_funnel_metadataRename a funnelfunnelId, data.nameUpdated funnel object
request_html_uploadImport your own HTML page (up to 1.5 MB): returns a 5-minute upload token and a curl commandname (new funnel) or funnelId (replace the draft); optional workspaceId with name; optional modeuploadUrl, token, expiresAt, curlExample
import_funnel_htmlImport your own HTML page inline (up to 200 KB)name or funnelId, plus html; optional workspaceId with name; optional modejobId, funnelId, editorUrl, status: "pending", trackingWarnings (mode exact: status: "saved", changed, no jobId)
get_funnel_job_statusPoll a generation or edit job (long-poll, ~20 s per call)jobIdStatus, URLs and summary when completed
publish_funnelPut the current draft livefunnelId, data?, confirmStartExperiment?funnelId, liveUrl, experiment?

list_funnels​

The main way to discover funnels and their IDs. Each funnel has a status (draft, live, offline). Drafts and classic (non-HTML) funnels are included; archived funnels only with includeArchived: true. Check isHtmlFunnel on each item: only AI/HTML funnels can be edited, copied or tested through MCP.

Inputs​

NameTypeRequiredDescription
workspaceIdstringYesWorkspace whose funnels to list, from list_workspaces
status"draft" | "live" | "offline"NoOnly funnels with this status. Omit for all statuses
includeArchivedbooleanNoInclude archived funnels. Defaults to false
pagenumberNoPage number, starting at 1 (default 1)
limitnumberNoPage size, 1–100 (default 25)

Returns the funnels plus pagination info (count, totalCount, pageCount). More pages exist while page is below pageCount. Each funnel has its id, name, status, isArchived, isHtmlFunnel, createdAt and updatedAt (UTC), and its sharing preview when set: sharingImageUrl, sharingTitle and sharingDescription, the image, title and description shown when the link is shared. An AI/HTML funnel also has its previewUrl and, when live, its liveUrl.

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 editor URL.

The funnel is created as a draft and does not publish itself. Once generation completes, ask the user whether to publish, then call publish_funnel.

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​

NameTypeRequiredDescription
data.namestringYesShort human-readable funnel name
data.promptstringYesNatural-language brief built from brand-aware clarification answers; cover goal, audience temperature, length tolerance, primary objection
data.brandIdstringExactly one of brandId / noBrandID of the brand profile to apply (from list_brands → get_brand)
data.noBrandtrueExactly one of brandId / noBrandSet only after the user actively chooses to create without a brand
data.workspaceIdstringNoTarget workspace; defaults to account default

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

duplicate_funnel​

Copies an existing AI/HTML funnel into the same workspace, keeping its integrations and brand. The copy is created immediately, so there is no job to poll. It is always an unpublished draft, even when the source is live; ask the user before publishing it with publish_funnel.

A classic funnel returns "Funnel not found" here, so pick one with isHtmlFunnel: true from list_funnels. The copy counts against the account's funnel and workspace limits but uses no AI credits. The copy starts without the source's AI chat history; the first update_funnel on it opens a new conversation on top of the copied page.

Inputs​

NameTypeRequiredDescription
funnelIdstringYesID of the AI/HTML funnel to copy
data.namestringNoName for the copy. Omit to reuse the source name as is (prefer a distinct name)

Returns { data: { id, name, editorUrl } }.

update_funnel​

Appends a natural-language edit instruction to the funnel's existing AI conversation, so each edit keeps the earlier context. The edit changes the funnel's draft only: the live URL stays the same until publish_funnel is called again after the 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.

Works on any AI/HTML funnel: created with create_funnel, copied with duplicate_funnel, or created through the API. Classic funnels have to be edited in the Perspective app.

Inputs​

NameTypeRequiredDescription
funnelIdstringYesID of the AI/HTML funnel to edit (isHtmlFunnel: true in list_funnels)
promptstringYesNatural-language description of the change (e.g. "make the headline punchier and add a testimonials section"). For a bug, describe the symptom and steps to reproduce, not a fix
version"original" | "variant"While the funnel has an A/B testWhich version of the page to edit. Required while the funnel has a draft or running test; leave it out otherwise

version and A/B tests​

A funnel with a draft or running A/B test has two pages: the original and the variant. Every edit has to say which one it is for. Without version, the call fails with EXPERIMENT_VERSION_REQUIRED. On a funnel without a test, version: "variant" fails with NO_EXPERIMENT_VARIANT.

Both versions share the funnel's one AI conversation, so the returned jobId and get_funnel_job_status work the same for either. The share card, favicon and cookie banner belong to the whole funnel and cannot be changed on the variant, so change them with version: "original", which applies them to both versions.

On a running test, a finished edit is saved but visitors keep seeing the old content of that version until the funnel is published again. See Changes go live on publish.

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

get_funnel_html​

Reads the current HTML of an existing AI/HTML funnel, so the assistant can see what is on its pages before it describes a change for update_funnel. Read-only: edits go through update_funnel, or, for a purely visual change you make to the HTML yourself, through an import in mode exact.

Lines come back numbered (N→). Each result is capped at 32 KB, cut at a whole line, so a large funnel is read in windows: the result reports the window, the document's total size, and nextOffset to continue from. A single line larger than the cap (for example a minified funnel) is cut mid-line; the result then also returns nextColumn, and passing it as column reads on inside that line.

Inputs​

NameTypeRequiredDescription
funnelIdstringYesID of an AI/HTML funnel (list_funnels reports isHtmlFunnel: true)
offsetintegerNo1-indexed line to start from (default 1)
columnintegerNoOnly to continue a line the cap cut: pass the previous nextColumn unchanged, with its nextOffset
limitintegerNoMaximum number of lines (default 2000); the 32 KB cap still applies
version"original" | "variant"NoOn a funnel with an A/B test, which version to read (default original)
revisioninteger | "current" | "live"NoWhich revision to read (default current). See Revisions and downloads
downloadbooleanNotrue: answer with a 5-minute link to the revision's stored file instead of its content. See Revisions and downloads

Returns { data: { funnelId, content, startLine, startColumn?, endLine, totalLines, totalBytes, truncated, nextOffset?, nextColumn? } }, plus revision when you passed one. nextOffset is absent once the window reaches the end of the document. With download: true: { data: { funnelId, revision, downloadUrl, expiresAt } }.

get_funnel_status​

One AI/HTML funnel, as the same item list_funnels returns: name, status, isArchived, previewUrl, liveUrl (only when live), the sharing preview, createdAt and updatedAt. Use it to check whether a funnel is live and where, for example after publish_funnel. A classic funnel, or one outside the user's workspaces, reads as not found.

Inputs​

NameTypeRequiredDescription
funnelIdstringYesID of an AI/HTML funnel
includeRevisionsbooleanNotrue: also return revisions, the original's last 20 revisions, newest first. See Revisions and downloads

update_funnel_metadata​

Renames a funnel without touching its content. It does not publish; to move a funnel to another domain or slug, use publish_funnel.

Inputs​

NameTypeRequiredDescription
funnelIdstringYesID of the funnel to rename (from create_funnel or list_funnels)
data.namestringYesNew funnel name (minimum 1 character)

Returns { data: { id, name, ... } } — the updated funnel object.

get_funnel_job_status​

Long-polls a job started by create_funnel, update_funnel or create_experiment. Each call waits until the job finishes or for about 20 seconds (occasionally longer when the upstream is slow), then returns the latest status, so no extra delay is needed between calls. A full generation usually completes within about 5 minutes.

Inputs​

NameTypeRequiredDescription
jobIdstringYesJob token returned by create_funnel, update_funnel or create_experiment

On completed, returns the funnel name, editorUrl, liveUrl (only once the funnel has been published), a short summary, a ready-to-display markdown rendition, and nextStep, a suggested next step. On failed, returns an error and a hint on how to retry. When the job edited one version of an A/B test, the response says which one and what the next publish will do to the test.

publish_funnel​

Promotes the funnel's current draft to a live, browser-viewable URL. Publishing makes changes visible to visitors, so confirm with the user before each publish.

When the funnel is already live, publishing again keeps it on its current domain (omit data). On a first publish, the funnel can go to the shared Perspective domain (omit domainId) or to one of the company's own ready domains from list_domains.

Inputs​

NameTypeRequiredDescription
funnelIdstringYesID of the funnel to publish (from create_funnel or list_funnels)
data.domainIdstringNoDomain to publish under (from list_domains). Omit for the shared Perspective domain
data.slugstringNoURL path segment, combined with domainId into {domainUrl}/{slug}. Letters, digits and hyphens only. Ignored without a domainId
confirmStartExperimentbooleanNoSet to true only after the user has agreed to start the funnel's draft A/B test, in reply to an EXPERIMENT_START_NOT_CONFIRMED error. Not needed when the funnel has no test or its test is already running

confirmStartExperiment and A/B tests​

Publishing is the moment a draft A/B test starts. So on a funnel with a draft test, the first call does not publish. It fails with EXPERIMENT_START_NOT_CONFIRMED and includes the test's name and split. Confirm with the user that they want to start the test (both versions go live and visitors are split), then call again with confirmStartExperiment: true. Publishing such a funnel always tries to start its test; to publish without it, discard the test first.

On a running test, publishing pushes the latest edits and split of both versions to visitors. No confirmation flag is needed.

After a publish, the response's message says what happened to the test:

  • Started: the draft test is now running and visitors are split.
  • Refreshed: the test was already running; the latest edits and split now reach visitors.
  • Not started: the user's role does not allow starting tests. The funnel is still published, showing only the original, and the test stays a draft (experiment.status is draft).
  • Failed: the funnel is published, but starting or refreshing the test failed. A draft test stays a draft, and a running test keeps serving each version as of the previous publish. Publishing again retries it.

Errors​

  • FUNNEL_GENERATION_IN_PROGRESS: an AI generation (including a variant being written) is still running. Poll get_funnel_job_status until it completes. A failed generation does not block publishing.
  • EXPERIMENT_START_NOT_CONFIRMED: see above.

Returns { data: { funnelId, liveUrl, experiment? }, message? }. Share liveUrl with the user. experiment (id, status, arms with each version and weight) and message are present whenever the funnel has a draft or running test.

Importing your own HTML​

request_html_upload and import_funnel_html bring a page you already built into Perspective. Both take a mode:

modeWhat happensAI credits
wire (default)Perspective stores the page as-is, keeping its design, layout and copy, then an AI pass splits it into Perspective pages and wires tracking, forms and navigation.Yes
exactPerspective stores the page exactly as you send it. No AI pass. Only for a page that already carries complete Perspective tracking (see below).No

Pass name to create a new funnel, or funnelId to replace the draft of an existing AI/HTML funnel. Replacing is refused while a generation is still running on that funnel. Only the draft changes: nothing reaches visitors until publish_funnel.

Mode wire: any HTML page​

Use it for a page built outside Perspective. The AI pass makes it a working Perspective funnel, so it spends the workspace's AI credits. If the workspace is out of credits, the import fails with 426 before anything is saved.

Mode exact: visual changes to a Perspective funnel​

Use it when the page already is a Perspective funnel and you only changed how it looks: for example, you read a funnel with get_funnel_html, changed colors, layout or copy, and now write it back. The page is stored as sent, with no AI pass and no AI credits.

  • Only with funnelId: exact replaces an existing funnel's draft. To create a new funnel from a page, use mode wire.
  • The page's tracking must already be complete: the data-ps-* attributes on pages, forms, fields and buttons. Perspective checks it, and a page with missing or broken tracking is refused with the list of problems; nothing is saved. Fix them, or import with mode wire.
  • get_funnel_html numbers its lines (N→). Strip those prefixes and join every window before sending the page back.
  • On a funnel with an A/B test, exact always replaces the original version, never the variant. Read the page with get_funnel_html without version.
  • A page identical to the current draft saves nothing new and answers changed: false.

Two-step upload (up to 1.5 MB)​

Call request_html_upload (with the mode you want), then upload the file within 5 minutes using the returned command:

curl -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: text/html" \
--data-binary @page.html \
https://api.perspective.co/v1/html-imports

The mode is part of the token, so the upload cannot change it. A successful upload answers:

FieldMeaning
jobIdMode wire (201): poll get_funnel_job_status with it, as for any other generation.
statusMode exact (200): saved. There is no job to poll.
changedMode exact: false when the page was identical to the current draft.
funnelIdThe funnel that was created or whose draft was replaced.
editorUrlLink to open the funnel in the editor.
trackingWarningsNon-blocking tracking advisories found in the page (an empty list if none).

The token is valid for 5 minutes; after that, call request_html_upload again.

Errors from the upload endpoint (the body is JSON with a message):

StatusMeaning
401The upload link expired or is invalid. Call request_html_upload again.
403Mode wire: your account cannot import funnels.
404No AI/HTML funnel with this funnelId in this workspace. Check it with list_funnels, or pass name to create a new funnel.
409A generation is still running on this funnel. Poll get_funnel_job_status until it finishes (a generation started in the editor has no jobId: wait a minute), then retry. In mode exact, a 409 can also mean the draft changed while the page was being saved: read the funnel again, apply your change and send it again.
413The page is too large (1.5 MB limit). Send a smaller page or remove inline assets such as base64 images.
415Wrong content type. Send the raw page with Content-Type: text/html.
422Mode exact: the page's tracking is incomplete or broken. The message lists the problems. Nothing was saved.
426Mode wire: the workspace is out of AI credits. Nothing was imported.
503Mode exact: Perspective could not check whether a generation is running, so nothing was saved. Try again in a moment.
502 / 504Perspective did not confirm the import in time. It may still have gone through, so check list_funnels (new funnel) or the editor before retrying.

Inline (small pages, up to 200 KB)​

If you cannot run shell commands, call import_funnel_html with the full HTML document in html and the same name / funnelId / mode. It answers like the upload: a jobId in mode wire, status: "saved" in mode exact. Errors come back as tool errors with the same meaning, for example HTML_TRACKING_INCOMPLETE for a refused exact page. For larger files use the two-step upload.

Revisions and downloads​

Every save of a funnel's draft (an AI build, an edit in the editor, an import, a restore) is kept as a numbered revision, and none is deleted with age. The original and the A/B variant count their own. After an A/B test is ended, the history starts where the winning version was created. These inputs are being enabled workspace by workspace (revision and download on get_funnel_html, includeRevisions on get_funnel_status); until they are, the tools don't offer them. They need a signed-in user, as every funnel tool does.

  • List: get_funnel_status with includeRevisions: true returns revisions: the original's last 20, newest first, each with revision, source, createdAt, and when known author, publishedAt, isLive, restoredFrom and group (revisions of one AI build share it). When there are more, moreRevisions points at the REST list, GET /v1/funnels/{funnelId}/revisions, which also lists the variant's.
  • Read: get_funnel_html with revision reads that revision in the usual windows. current is the latest save, live the one marked live (last published), a number that revision. A window of a numbered revision says to continue with the same revision.
  • Download: get_funnel_html with download: true (and optionally revision and version) answers with a downloadUrl instead of content: a 5-minute signed link to the revision's stored file. Fetch it with no other credential; it is gzip-encoded: curl --compressed -o funnel.html "<downloadUrl>". The file is the revision as it was saved: for the variant, the funnel's shared title, meta, share image, favicon and cookie banner come from the original (a write re-applies them). The link serves only the revision it names; after 5 minutes the storage answers 403, so ask for a new one.

To change a funnel's look by hand: download it, edit the file, and write it back with request_html_upload in mode exact, which saves it as a new revision. Mode exact always replaces the original, so edit a download of the original (no version), and of its current revision unless you mean to bring an older one back.

ErrorMeaning
REVISION_NOT_FOUNDThe funnel has no revision with this number.
LIVE_REVISION_UNKNOWNlive, but no revision is marked live: the funnel is not published, or was published before revisions were recorded. Use current or a number.
EXPERIMENT_ARM_MISSINGThe funnel's A/B test has no such version.