Funnels

Funnels endpoints of the Zanfia Workspace API, with schemas and code samples.

6 min readLast updated Oct 31, 2026

Marketing funnels: named step chains that reference existing checkouts, pages, and workflows — a funnel never owns the artifacts its steps point to, and deleting one leaves them untouched. Create is recipe-first over a product's existing artifacts (lead_magnet / tripwire need a free checkout, sell_product / low_ticket a paid one, webinar any product: three empty page steps you generate next with the event date) and also drops the recipe's email sequence in as a draft workflow. from-template creates the funnel and generates its pages in one go. Statuses draft / live / archived are all reversible via PATCH. All routes require a Authorization: Bearer header — see Authentication.

List funnels

GET/funnels

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/funnels"

{  "funnels": [    {      "id": "string",      "name": "string",      "recipe": "lead_magnet",      "status": "draft",      "steps": [        {          "stepId": "string",          "type": "lead-magnet",          "name": "string",          "ref": {            "pageId": "string",            "checkoutId": "string",            "formId": "string",            "otoOfferId": "string"          },          "slug": "string",          "status": "ready"        }      ],      "workflowIds": [        "string"      ],      "productIds": [        "string"      ],      "challenge": {        "startAt": 0,        "timezone": "string",        "days": 0,        "courseProductId": "string",        "courseId": "string",        "registrationCheckoutId": "string",        "pitchProductId": "string",        "pitchCheckoutId": "string",        "cartClosesAt": 0,        "deadlineApplied": true,        "missions": [          {            "day": 0,            "moduleId": "string",            "lessonId": "string",            "unlockAt": 0          }        ],        "campaigns": [          {            "campaignId": "string",            "kind": "kickoff",            "day": 0,            "sendAt": 0          }        ]      },      "createdAt": 0,      "updatedAt": 0    }  ]}

{  "error": "string",  "message": "string"}

Create a funnel from a recipe

POST/funnels

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create a funnel from a recipe — resolves the product's existing artifacts (free/paid checkouts, OTO chain) into the step list and generates the recipe's email sequence as a DRAFT workflow. See FunnelDocument.

recipe*FunnelRecipe

Outcome-named creation recipes — the wizard's "what do you want to do?".

Value in

"lead_magnet"
"tripwire"
"sell_product"
"low_ticket"
"webinar"
"waitlist"
"challenge"

productId*string

The product the funnel sells (sell/tripwire/challenge pitch) or delivers (lead magnet).

name?string

lang*string

Language of the generated email copy (static EN/PL templates).

Value in

"en"
"pl"

challenge?

Challenge recipe only: the cohort. Required for FunnelRecipe.Challenge.

Response Body

`application/json`

curl -X POST "https://example.com/funnels" \  -H "Content-Type: application/json" \  -d '{    "recipe": "lead_magnet",    "productId": "string",    "lang": "en"  }'

{  "funnelId": "string",  "note": "string"}

{  "error": "string",  "message": "string"}

List funnel templates

GET/funnel-templates

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/funnel-templates"

{  "templates": [    {      "id": "squeeze",      "recipe": "lead_magnet",      "name": "string",      "namePl": "string",      "description": "string",      "descriptionPl": "string",      "requirement": "free_checkout",      "available": true,      "steps": [        {          "type": "lead-magnet",          "name": "string",          "namePl": "string"        }      ]    }  ]}

{  "error": "string",  "message": "string"}

Create a funnel from existing pages

POST/funnels/from-pages

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A funnel record over existing hosted pages (visitor order; the first is the entry).

pageIds*array<string>

name?string

Defaults to the entry page's title.

checkoutId?string

The checkout the pages sell, appended as the last (Checkout) step.

Response Body

`application/json`

curl -X POST "https://example.com/funnels/from-pages" \  -H "Content-Type: application/json" \  -d '{    "pageIds": [      "string"    ]  }'

{  "funnelId": "string"}

{  "error": "string",  "message": "string"}

Create a funnel from a template

POST/funnels/from-template

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /funnels/from-template — the server-side "Use funnel template" flow: creates the funnel from the template's recipe over the product's existing checkouts, drops the recipe's email sequence in as a draft workflow, and enqueues an AI page generation for every page step.

templateId*FunnelTemplateId

Funnel template catalog — the wizard's picker cards. Each template maps to one FunnelRecipe; its steps MIRROR what CreateFunnelFromRecipeUseCase builds for that recipe (a test in packages/logic pins the two together), so the picker can preview the chain before anything is created.

Benchmark hints are planning ranges in our own words; cold traffic sits at the low end or below.

Value in

"squeeze"
"tripwire"
"sales_oto"
"low_ticket"
"webinar"
"challenge"

productId?string

The product the template sells / delivers (must satisfy the template's requirement). Optional only for a webinar that plays a recording (webinar.liveRoomId): it is the funnel's subject. Missing otherwise → 400 product-required.

name?string

Optional custom funnel name; the recipe provides a default.

lang*FunnelCopyLanguageApiDTO

Copy language of generated pages / email sequences.

Value in

"en"
"pl"

webinar?

Webinar template only; ignored for the other templates.

pageTemplateId?string

Design-template seed for every generated page step (a page-templates catalog id, e.g. course-fresh); thank-you steps take the companion. Unknown id → 400 page-template-not-found. Omit for the default look.

Response Body

`application/json`

curl -X POST "https://example.com/funnels/from-template" \  -H "Content-Type: application/json" \  -d '{    "templateId": "squeeze",    "lang": "en"  }'

{  "funnel": {    "id": "string",    "name": "string",    "recipe": "lead_magnet",    "status": "draft",    "steps": [      {        "stepId": "string",        "type": "lead-magnet",        "name": "string",        "ref": {          "pageId": "string",          "checkoutId": "string",          "formId": "string",          "otoOfferId": "string"        },        "slug": "string",        "status": "ready"      }    ],    "workflowIds": [      "string"    ],    "productIds": [      "string"    ],    "challenge": {      "startAt": 0,      "timezone": "string",      "days": 0,      "courseProductId": "string",      "courseId": "string",      "registrationCheckoutId": "string",      "pitchProductId": "string",      "pitchCheckoutId": "string",      "cartClosesAt": 0,      "deadlineApplied": true,      "missions": [        {          "day": 0,          "moduleId": "string",          "lessonId": "string",          "unlockAt": 0        }      ],      "campaigns": [        {          "campaignId": "string",          "kind": "kickoff",          "day": 0,          "sendAt": 0        }      ]    },    "createdAt": 0,    "updatedAt": 0  },  "generations": [    {      "stepId": "string",      "stepName": "string",      "runId": "string"    }  ],  "skippedSteps": [    {      "stepId": "string",      "reason": "already_has_page"    }  ]}

{  "error": "string",  "message": "string"}

Get a funnel

GET/funnels/{funnelId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

funnelId*string

Funnel id

Response Body

`application/json`

curl -X GET "https://example.com/funnels/string"

{  "funnel": {    "id": "string",    "name": "string",    "recipe": "lead_magnet",    "status": "draft",    "steps": [      {        "stepId": "string",        "type": "lead-magnet",        "name": "string",        "ref": {          "pageId": "string",          "checkoutId": "string",          "formId": "string",          "otoOfferId": "string"        },        "slug": "string",        "status": "ready"      }    ],    "workflowIds": [      "string"    ],    "productIds": [      "string"    ],    "challenge": {      "startAt": 0,      "timezone": "string",      "days": 0,      "courseProductId": "string",      "courseId": "string",      "registrationCheckoutId": "string",      "pitchProductId": "string",      "pitchCheckoutId": "string",      "cartClosesAt": 0,      "deadlineApplied": true,      "missions": [        {          "day": 0,          "moduleId": "string",          "lessonId": "string",          "unlockAt": 0        }      ],      "campaigns": [        {          "campaignId": "string",          "kind": "kickoff",          "day": 0,          "sendAt": 0        }      ]    },    "createdAt": 0,    "updatedAt": 0  },  "event": {    "pageId": "string",    "mode": "live",    "startAt": "string",    "timezone": "string",    "durationMinutes": 0,    "joinUrl": "string",    "replayUrl": "string",    "liveRoomId": "string",    "rungs": [      {        "kind": "day_before",        "broadcastId": "string",        "sendAt": "string",        "status": "draft"      }    ]  }}

{  "error": "string",  "message": "string"}

Update a funnel

PATCH/funnels/{funnelId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

funnelId*string

Funnel id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partial funnel update — rename, status transition, step re-wiring.

name?string

status?FunnelStatus

Value in

"draft"
"live"
"archived"

steps?array<>

workflowIds?array<string>

Response Body

`application/json`

curl -X PATCH "https://example.com/funnels/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "updated": true}

{  "error": "string",  "message": "string"}

Delete a funnel

DELETE/funnels/{funnelId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

funnelId*string

Funnel id

Response Body

`application/json`

curl -X DELETE "https://example.com/funnels/string"

{  "deleted": true}

{  "error": "string",  "message": "string"}

Funnel stats

GET/funnels/{funnelId}/stats

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

funnelId*string

Funnel id

Response Body

`application/json`

curl -X GET "https://example.com/funnels/string/stats"

{  "funnelId": "string",  "since": "string",  "steps": [    {      "stepId": "string",      "views": 0,      "entries": 0,      "signups": 0,      "sessions": 0,      "completed": 0,      "otoViewed": 0,      "otoAccepted": 0    }  ],  "totals": {    "entryViews": 0,    "signups": 0,    "purchases": 0  },  "challenge": {    "participants": 0,    "missions": [      {        "day": 0,        "lessonId": "string",        "completed": 0      }    ]  }}

{  "error": "string",  "message": "string"}

Generate a page for a funnel step

POST/funnels/{funnelId}/generate-step-page

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

funnelId*string

Funnel id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Generate a hosted page for one page-type funnel step (opt-in / sales / thank-you) via the unified page-generation pipeline, grounded in the funnel's product + the step's checkout, then wire the step to the draft (ref.pageId + slug). One step per call — generation takes minutes.

stepId*string

lang*string

Language of the generated copy.

Value in

"en"
"pl"

brief?string

Optional creator notes appended to the synthesized brief.

templateId?string

Optional design seed — pass the same id for every step so pages look like siblings.

eventStartAt?string

Webinar registration step only: event start as ISO 8601 with offset.

eventTimezone?string

Webinar registration step only: IANA timezone of the event.

eventDurationMinutes?number

Webinar registration step only: event length in minutes (default 60).

eventMode?PageEventMode

Webinar registration step only: on_demand = an on-demand webinar (no date).

Value in

"live"
"on_demand"

eventJoinUrl?string

Webinar registration step only: where the live webinar happens (a ClickMeeting / Zoom / Teams / Meet link, http(s)). The family is born with it: the watch page's button, the calendar location, the thank-you page and every reminder. Ignored with liveRoomId.

Response Body

`application/json`

curl -X POST "https://example.com/funnels/string/generate-step-page" \  -H "Content-Type: application/json" \  -d '{    "stepId": "string",    "lang": "en"  }'

{  "runId": "string",  "publicAccessToken": "string"}

{  "error": "string",  "message": "string"}

This route needs two scopes, products:write and pages:write, because it creates a page and rewrites the signup page. A scoped key with products:write only answers 403 insufficient-scope; keys created before scopes existed keep their reach.

POST/funnels/{funnelId}/offer-page

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

funnelId*string

Funnel id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /funnels/:funnelId/offer-page: a designed one-time-offer page right after a signup step (the panel's „Oferta” step, the assistant's add-funnel-offer-page, the Workspace API / MCP / CLI). The page is built from the Glass tripwire template in the signup page's colors, its offer block wired to the koszyk (accept, pays on the page) and the next step (decline, 30-minute timer); created as a DRAFT the creator edits and publishes. No AI, no credits.

checkoutId*string

The koszyk (checkout) the offer sells; it must be live with a public address.

layout*FunnelOfferPageLayout

The designed one-time-offer page after a free signup, by what the offer is (oto-page-templates.md §9.8): a digital tripwire confirms first and puts the offer with its on-page checkout under the value.

Value in

"digital"
"physical"

afterStepId?string

The signup step the offer follows; omitted = the funnel's first signup step.

lang?string

Language of the template copy; defaults to en.

Value in

"en"
"pl"

Response Body

`application/json`

curl -X POST "https://example.com/funnels/string/offer-page" \  -H "Content-Type: application/json" \  -d '{    "checkoutId": "string",    "layout": "digital"  }'

{  "pageId": "string",  "slug": "string",  "stepId": "string",  "title": "string",  "afterStepId": "string"}

{  "error": "string",  "message": "string"}

Was this article helpful?

Spotted something off? Tell us at support@zanfia.com.

List funnels

200application/json

4XXapplication/json

Create a funnel from a recipe

200application/json

4XXapplication/json

List funnel templates

200application/json

4XXapplication/json

Create a funnel from existing pages

200application/json

4XXapplication/json

Create a funnel from a template

200application/json

4XXapplication/json

Get a funnel

200application/json

4XXapplication/json

Update a funnel

200application/json

4XXapplication/json

Delete a funnel

200application/json

4XXapplication/json

Funnel stats

200application/json

4XXapplication/json

Generate a page for a funnel step

200application/json

4XXapplication/json

Add a one-time-offer page after a signup step

200application/json

4XXapplication/json

Related articles

API overview

Authentication and API keys

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`